# REST API 的执行日志记录
<a name="rest-api-execution-logging"></a>

执行日志记录会记录 API Gateway 为处理 API 请求而执行的操作。记录的数据包括错误、执行跟踪、请求和响应参数值或有效载荷、Lambda 授权方使用的数据、是否需要 API 密钥，以及是否启用了使用计划。API Gateway 会从记录的数据中删除授权标头、API 密钥值和类似的敏感请求参数。

为了改善您的安全状况，我们建议您使用 `ERROR` 或 `INFO` 级别的执行日志记录。为遵守各种合规性框架，您可能需要执行此操作。有关更多信息，请参阅《Amazon Security Hub User Guide》**中的 [Amazon API Gateway Controls](https://docs.amazonaws.cn/securityhub/latest/userguide/apigateway-controls.html)。

## 标准执行日志记录
<a name="rest-api-execution-logging-standard"></a>

在阶段上启用执行日志记录后，API Gateway 会自动创建和管理 CloudWatch Logs 日志组。日志组命名为 `API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}`。在每个日志组内，日志划分到日志流中，按**上次事件时间**排序。

使用标准执行日志记录时：
+ 日志事件将在 1 KB 处截断。
+ API Gateway 管理日志组名称。您无法选择日志组名称或将日志直接发送到 Amazon S3 或 Firehose。

要启用标准执行日志记录，请将阶段上的 `loggingLevel` 设置为 `ERROR` 或 `INFO`。无需其他配置。

### 权限
<a name="rest-api-execution-logging-permissions"></a>

要启用 CloudWatch Logs，您必须向 API Gateway 授予权限，才能针对您的账户读取日志和将日志写入到 CloudWatch。[AmazonAPIGatewayPushToCloudWatchLogs](https://docs.amazonaws.cn/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html) 托管式策略具有所需的全部权限。

请以 `apigateway.amazonaws.com` 作为可信实体创建一个 IAM 角色，附加上述策略，然后在您[账户](https://docs.amazonaws.cn/apigateway/latest/api/API_GetAccount.html)的 [cloudWatchRoleArn](https://docs.amazonaws.cn/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn) 属性上设置 IAM 角色 ARN。您必须为每个要启用 CloudWatch Logs 的 Amazon 区域单独设置此属性。

**注意**  
API Gateway 将调用 Amazon Security Token Service 以代入 IAM 角色，因此请确保已为该区域启用 Amazon STS。有关更多信息，请参阅[在Amazon区域中管理Amazon STS](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html)。

### 启用执行日志记录（控制台）
<a name="rest-api-execution-logging-console"></a>

在开始之前，请将 API 部署到某个阶段，并为您的账户配置相应的 CloudWatch Logs 角色 ARN。

1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.amazonaws.cn/apigateway)。

1. 在主导航窗格上选择**设置**，然后在**日志记录**下选择**编辑**。

1. 对于 **CloudWatch 日志角色 ARN**，请输入具有相应权限的 IAM 角色的 ARN。对于每个使用 API Gateway 创建 API 的 Amazon Web Services 账户，您都需要执行一次此操作。

1. 在主导航窗格中，选择 **API**，选择您的 REST API，然后选择**阶段**。

1. 选择一个阶段，然后在**日志和跟踪**部分中，选择**编辑**。

1. 从 **CloudWatch Logs** 下拉菜单中选择日志记录级别：
   + **关闭**：API Gateway 不记录此阶段的请求。
   + **仅限错误**：API Gateway 仅记录错误。
   + **错误和信息日志**：API Gateway 记录所有事件。

1. （可选）选择**数据跟踪**以记录完整的请求和响应数据。这可能会导致记录敏感数据。
**注意**  
建议不要为生产 API 启用**数据跟踪**。

1. （可选）选择**详细指标**来开启详细的 CloudWatch 指标。有关更多信息，请参阅 [使用 Amazon CloudWatch 指标监控 REST API 执行](monitoring-cloudwatch.md)。

1. 选择**保存更改**。

更新阶段设置时，您无需重新部署 API。

### 启用执行日志记录（Amazon CloudFormation）
<a name="rest-api-execution-logging-cfn"></a>

使用阶段资源上的 `MethodSettings` 属性来启用执行日志记录。

```
  TestStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      StageName: test
      RestApiId: !Ref MyAPI
      DeploymentId: !Ref Deployment
      MethodSettings:
        - ResourcePath: "/*"
          HttpMethod: "*"
          LoggingLevel: INFO
```

要启用 CloudWatch Logs，您必须向 API Gateway 授予权限，才能针对您的账户读取日志和将日志写入到 CloudWatch。要了解更多信息，请参阅《Amazon CloudFormation 用户指南》**中的[将账户与 IAM 角色关联](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-account.html#aws-resource-apigateway-account--examples)。

## 执行日志的 Amazon CloudWatch Logs 传输
<a name="rest-api-execution-logging-delivery"></a>

Amazon CloudWatch Logs 传输为执行日志提供了另一种路径。您无需写入由 API Gateway 管理的日志组，而是配置一个传输，用于将执行日志发送到您拥有和控制的目标。

使用 Amazon CloudWatch Logs 传输：
+ 日志事件最大可达 1 MB，能够捕获更完整的请求和响应数据。超过 1 MB 的有效载荷仍会被截断。
+ 您可以选择目标：您自己的 CloudWatch Logs 日志组、Amazon S3 存储桶或 Firehose 流。
+ 您可以将日志同时发送到多个目标。
+ 您可以控制日志组配置，包括命名和保留。

**重要**  
CloudWatch Logs 传输取代了标准执行日志记录。配置传输时，API Gateway 会停止写入自动管理的日志组。不能对同一个阶段同时使用这两条路径。

创建传输时，API Gateway 将执行日志路由到您配置的目标，而不是自动管理的日志组。删除传输后，执行日志会自动恢复流向自动管理的日志组。除了将 `loggingLevel` 设置为 `ERROR` 或 `INFO` 这一先决条件外，无需对 API Gateway 进行任何其它配置更改。

**注意**  
日志传输是尽力而为的。在极少数情况下，可能会无法传输某些日志事件。

**警告**  
在启用日志传输之前，请更新所有引用自动管理的日志组 (`API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}`) 的控制面板、警报或订阅筛选条件。传输处于活动状态后，该日志组不再接收新事件。

下表对标准执行日志记录与 Amazon CloudWatch Logs 传输进行了比较。


|  | 标准执行日志记录 | Amazon CloudWatch Logs 传输 | 
| --- | --- | --- | 
| 最大日志事件大小 | 1KB | 1 MB | 
| 目标 | CloudWatch Logs（托管式日志组） | CloudWatch Logs、Amazon S3、Firehose（您自己的资源） | 
| 多个目标 | 否 | 是 | 
| 日志组名称 | 由 API Gateway 固定 | 由您选择 | 
| 设置 | 启用日志记录时自动执行 | 需要创建 Amazon CloudWatch Logs 传输 | 
| 先决条件 | 将 loggingLevel 设置为 ERROR 或 INFO | 将 loggingLevel 设置为 ERROR 或 INFO | 

**注意**  
如果在配置传输后将 `loggingLevel` 设置为 `OFF`，则不会生成或传输任何执行日志。您的传输目标仍处于已配置状态，但不会接收任何数据。

要创建传输，请参阅[为 REST API 执行日志创建日志传输](rest-api-create-log-delivery.md)。