# 为 REST API 执行日志创建日志传输
<a name="rest-api-create-log-delivery"></a>

您可以将执行日志路由到您自己的 CloudWatch Logs 日志组、Amazon S3 存储桶或 Firehose 流。为此，请创建 Amazon CloudWatch Logs 传输。这包括三个步骤：创建传输源、创建传输目标，以及通过传输将二者关联起来。

## 先决条件
<a name="rest-api-create-log-delivery-prereqs"></a>

在创建日志传输之前，请确保您已具备以下条件：
+ 在您的 REST API 阶段中启用了执行日志记录。将 `loggingLevel` 设置为 `ERROR` 或 `INFO`。如果未启用日志记录，则传输源创建将失败。
+ 目标资源：您拥有的 CloudWatch Logs 日志组、Amazon S3 存储桶或 Firehose 流。
+ 调用 Amazon CloudWatch Logs 传输 API 的权限。有关更多信息，请参阅《Amazon CloudWatch Logs 用户指南》**中的[从 AWS 服务启用日志记录](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html)。

## Amazon CloudWatch Logs 传输的 API Gateway 特定的值
<a name="rest-api-create-log-delivery-values"></a>

在为 API Gateway 执行日志创建传输时，请使用以下值：

资源 ARN  
`arn:aws:apigateway:{{{region}}}:{{{account-id}}}:/restapis/{{{rest-api-id}}}/stages/{{{stage-name}}}`

日志类型  
`EXECUTION_LOGS`

## 创建日志传输（AWS CLI）
<a name="rest-api-create-log-delivery-cli"></a>

以下示例创建一个传输，用于将执行日志从 REST API 发送到您拥有的 CloudWatch Logs 日志组。

1. 

**创建传输源**

   将您的 REST API 注册为传输源。

   ```
   aws logs put-delivery-source \
       --name {{my-apigw-source}} \
       --log-type EXECUTION_LOGS \
       --resource-arn arn:aws:apigateway:{{{region}}}:{{{account-id}}}:/restapis/{{{rest-api-id}}}/stages/{{{stage-name}}}
   ```

1. 

**创建传输目标**

   将您的日志组注册为传输目标。

   ```
   aws logs put-delivery-destination \
       --name {{my-log-destination}} \
       --delivery-destination-configuration "destinationResourceArn=arn:aws:logs:{{{region}}}:{{{account-id}}}:log-group:{{{log-group-name}}}"
   ```

1. 

**创建传输**

   将源与目标关联。

   ```
   aws logs create-delivery \
       --delivery-source-name {{my-apigw-source}} \
       --delivery-destination-arn arn:aws:logs:{{{region}}}:{{{account-id}}}:delivery-destination:{{my-log-destination}}
   ```

要将日志发送到 Amazon S3 或 Firehose，请在 `put-delivery-destination` 命令中指定相应的资源 ARN。有关完整的 Amazon CloudWatch Logs 传输工作流程的更多信息，请参阅《Amazon CloudWatch Logs 用户指南》**中的[从 AWS 服务启用日志记录](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html)。

要将日志发送到多个目标，请使用相同的传输源以及不同的目标创建额外的传输。

## 记录字段
<a name="rest-api-create-log-delivery-record-fields"></a>

借助 Amazon CloudWatch Logs 传输，执行日志包含结构化字段，您可以针对每个目标对它们进行自定义。以下字段可用：
+ `resource_arn`：API 阶段的 ARN
+ `event_timestamp`：日志事件的时间
+ `api_id`：REST API 标识符
+ `stage`：阶段名称
+ `resource_path`：请求的资源路径
+ `http_method`：HTTP 方法
+ `payload`：执行日志内容（与标准执行日志相同）

您可以使用 `create-delivery` 上的 `--record-fields` 参数以及 `put-delivery-destination` 上的 `--output-format` 参数，选择要包含的字段及每个目标的输出格式。

可用的输出格式取决于目标：
+ **CloudWatch Logs**：json、纯文本
+ **Amazon S3**：json、纯文本、w3c、parquet
+ **Firehose**：json、纯文本

**匹配标准执行日志输出**  
如果您希望传输输出与标准执行日志记录相匹配（仅限有效载荷，不包含其它字段），请将 `--output-format "plain"` 添加到 `put-delivery-destination`，并将 `--record-fields "payload" --field-delimiter ""` 添加到 `create-delivery`。

## 创建日志传输（CloudFormation）
<a name="rest-api-create-log-delivery-cfn"></a>

为 CloudFormation 模板组装阶段 ARN 时，请使用以下模式：

```
  DeliverySource:
    Type: AWS::Logs::DeliverySource
    Properties:
      Name: my-apigw-source
      LogType: EXECUTION_LOGS
      ResourceArn: !Sub "arn:${AWS::Partition}:apigateway:${AWS::Region}:${AWS::AccountId}:/restapis/${MyApi}/stages/${MyStageName}"
```

## 创建日志传输（API Gateway 控制台）
<a name="rest-api-create-log-delivery-console"></a>

您可以在阶段详细信息页面的**日志和跟踪**部分创建日志传输。

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

1. 选择您的 REST API，然后选择**阶段**。

1. 选择一个阶段。

1. 在**日志和跟踪**部分的**日志传输目标**下，选择**添加目标**。

1. 选择目标类型（CloudWatch Logs、Amazon S3 或 Firehose）并指定目标资源。

1. 选择**保存**。

**重要**  
必须先在阶段上启用执行日志记录，然后才能添加传输目标。如果日志记录设置为**关闭**，则传输配置不会生成日志。

**注意**  
要配置跨账户传输目标，请使用 AWS CLI。在源账户中创建传输之前，必须先在目标账户中创建传输目标策略。有关更多信息，请参阅《Amazon CloudWatch Logs 用户指南》**中的[跨账户传输示例](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/vended-logs-crossaccount-example.html)。