本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在 API Gateway 中設定 REST API 的 CloudWatch 記錄功能
<a name="set-up-logging"></a>

 為了協助偵錯 API 請求執行或用戶端存取相關問題，您可以啟用 Amazon CloudWatch Logs 來記錄 API 呼叫。如需 CloudWatch 的詳細資訊，請參閱 [使用 Amazon CloudWatch 指標監控 REST API 執行](monitoring-cloudwatch.md)。

## 適用於 API Gateway 的 CloudWatch 日誌格式
<a name="apigateway-cloudwatch-log-formats"></a>

 CloudWatch 有兩種類型的 API 記錄：執行記錄和存取記錄。在執行記錄中，API Gateway 會管理 CloudWatch Logs。此程序包含建立日誌群組和日誌串流，以及向日誌串流報告任何發起人的請求和回應。

所記錄的資料包含錯誤或執行追蹤 (例如請求或回應參數值或承載)、Lambda 授權方 (先前稱作自訂授權方) 所使用的資料、是否需要 API 金鑰、是否啟用用量方案，以及其他資訊。API Gateway 會從記錄的資料修訂授權標頭、API 金鑰值和類似的敏感請求參數。

若要提升您的安全狀態，建議您在 `ERROR` 或 `INFO` 層級使用執行記錄。您可能需要這樣做，才能符合各種合規架構。如需詳細資訊，請參閱《AWS Security Hub 使用者指南》**中的 [Amazon API Gateway 控制項](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html)。

當您部署 API 時，API Gateway 會在日誌群組下方建立日誌群組和日誌串流。日誌群組的命名是遵循 `API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}` 格式。在每個日誌群組內，日誌會進一步分割為日誌串流，而其在報告所記錄的資料時會依 **Last Event Time (上次事件時間)** 排序。

在存取記錄中，您身為 API 開發人員且想要記錄誰已存取您的 API 以及發起人存取 API 的方式。您可以建立自己的日誌群組，或選擇由 API Gateway 管理的現有日誌群組。若要指定存取權詳細資訊，您可以選取 [`$context`](api-gateway-variables-for-access-logging.md) 變數、日誌格式及日誌群組目的地。

存取日誌格式必須至少包含 `$context.requestId` 或 `$context.extendedRequestId`。最佳實務是將 `$context.requestId` 和 `$context.extendedRequestId` 納入您的日誌格式。

**`$context.requestId`**  
這會記錄 `x-amzn-RequestId` 標頭中的值。用戶端可以使用通用唯一識別碼 (UUID) 格式的值來覆寫 `x-amzn-RequestId` 標頭中的值。API Gateway 會傳回 `x-amzn-RequestId` 回應標頭中的此請求 ID。API Gateway 會將您的存取日誌中不是 UUID 格式的已覆寫請求 ID 取代為 `UUID_REPLACED_INVALID_REQUEST_ID`。

**`$context.extendedRequestId`**  
extendedRequestID 是 API Gateway 產生的唯一 ID。API Gateway 會傳回 `x-amz-apigw-id` 回應標頭中的此請求 ID。API 呼叫者無法提供或覆寫此請求 ID。您可能需要將此值提供給 AWS Support，以協助對 API 進行故障診斷。如需詳細資訊，請參閱[API Gateway 存取記錄的變數](api-gateway-variables-for-access-logging.md)。

選擇分析後端也會採用的日誌格式，例如[通用日誌格式](https://httpd.apache.org/docs/current/logs.html#common) (CLF)、JSON、XML 或 CSV。您接著可以直接饋送其存取日誌，以計算和轉譯您的指標。若要定義日誌格式，請在[階段](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)的 [accessLogSettings/destinationArn](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#destinationArn) 屬性上設定日誌群組 ARN。您可以在 CloudWatch 主控台取得日誌群組 ARN。若要定義存取日誌格式，請在[階段](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)的 [accessLogSetting/format](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#format) 屬性上設定選擇的格式。

一些常用存取日誌格式範例會顯示在 API Gateway 主控台中，並列出如下。
+ `CLF` ([通用日誌格式](https://httpd.apache.org/docs/current/logs.html#common))：

  ```
  $context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime]"$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId
  ```
+  `JSON`: 

  ```
  { "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId","ip": "$context.identity.sourceIp", "caller":"$context.identity.caller", "user":"$context.identity.user", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod", "resourcePath":"$context.resourcePath", "status":"$context.status", "protocol":"$context.protocol", "responseLength":"$context.responseLength" }
  ```
+ `XML`: 

  ```
  <request id="$context.requestId"> <extendedRequestId>$context.extendedRequestId</extendedRequestId> <ip>$context.identity.sourceIp</ip> <caller>$context.identity.caller</caller> <user>$context.identity.user</user> <requestTime>$context.requestTime</requestTime> <httpMethod>$context.httpMethod</httpMethod> <resourcePath>$context.resourcePath</resourcePath> <status>$context.status</status> <protocol>$context.protocol</protocol> <responseLength>$context.responseLength</responseLength> </request>
  ```
+ `CSV` (逗號分隔值)：

  ```
  $context.identity.sourceIp,$context.identity.caller,$context.identity.user,$context.requestTime,$context.httpMethod,$context.resourcePath,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId
  ```

## CloudWatch 記錄的許可
<a name="set-up-access-logging-permissions"></a>

若要啟用 CloudWatch Logs，您必須授予 API Gateway 為您的帳戶將日誌讀取和寫入 CloudWatch 的許可。[AmazonAPIGatewayPushToCloudWatchLogs](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html) 具有所有必要的許可權。

**注意**  
API Gateway 呼叫 AWS Security Token Service 以擔任 IAM 角色，因此請務必為 區域啟用 AWS STS 。如需詳細資訊，請參閱[在 AWS 區域中管理 AWS STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html)。

若要將這些許可授予您的帳戶，請建立 `apigateway.amazonaws.com` 作為其信任實體的 IAM 角色，並將先前的政策連接至 IAM 角色，然後在[帳戶](https://docs.aws.amazon.com/apigateway/latest/api/API_GetAccount.html)的 [cloudWatchRoleArn](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn) 屬性上設定 IAM 角色 ARN。您必須為要啟用 CloudWatch Logs 的每個區域分別設定 [cloudWatchRoleArn](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn) 屬性。 AWS CloudWatch 

如果您在設定 IAM 角色 ARN 時收到錯誤，請檢查您的 AWS Security Token Service 帳戶設定，以確保 AWS STS 已在您使用的區域中啟用。如需啟用 的詳細資訊 AWS STS，請參閱《*IAM 使用者指南*[AWS 》中的在 區域中管理 AWS STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate)。

## 使用 API Gateway 主控台設定 CloudWatch API 記錄功能
<a name="set-up-access-logging-using-console"></a>

若要設定 CloudWatch API 記錄功能，您必須已將 API 部署至階段。您也必須為您的帳戶設定了[適當的 CloudWatch Logs 角色](#set-up-access-logging-permissions) ARN。

1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。

1. 在主導覽窗格中，選擇**設定**，然後在**記錄**下選擇**編輯**。

1. 在 **CloudWatch 日誌角色 ARN** 中，輸入具有適當許可之 IAM 角色的 ARN。您需要針對每個使用 APIs建立 API AWS 帳戶 的 執行此操作一次。

1. 在主導覽窗格中，選擇 **API**，然後執行下列其中一項操作：

   1.  選擇現有 API，然後選擇階段。

   1.  建立 API，然後將它部署至階段。

1. 在主導覽窗格中，選擇**階段**。

1.  在**日誌和追蹤**區段中，選擇**編輯**。

1. 若要啟用執行記錄：

   1. 從 **CloudWatch Logs** 下拉式選單中選取記錄層級。記錄層級如下：
      + **關閉** – 此階段未開啟記錄。
      + **僅限錯誤** – 僅針對錯誤啟用記錄。
      + **錯誤和資訊日誌** – 針對所有事件啟用記錄。

   1. (選用) 選取**資料追蹤**以開啟您的階段的資料追蹤記錄。這對於故障排除 API 很有用，但可能會導致記錄機密資料。
**注意**  
建議您不要針對生產 API 使用**資料追蹤**。

   1. (選用) 選取**詳細指標**以開啟詳細的 CloudWatch 指標。

   如需 CloudWatch 指標的詳細資訊，請參閱 [使用 Amazon CloudWatch 指標監控 REST API 執行](monitoring-cloudwatch.md)。

1. 若要啟用存取記錄：

   1. 開啟**自訂存取記錄**。

   1. 在**存取日誌目的地 ARN** 中輸入日誌群組的 ARN。ARN 格式為 `arn:aws:logs:{region}:{account-id}:log-group:log-group-name`。

   1. 針對**日誌格式**，輸入日誌格式。您可以選擇 **CLF**、**JSON**、**XML** 或 **CSV**。若要進一步了解範例日誌格式，請參閱 [適用於 API Gateway 的 CloudWatch 日誌格式](#apigateway-cloudwatch-log-formats)。

1. 選擇**儲存變更**。

**注意**  
您可以個別啟用執行記錄和存取記錄。

API Gateway 現在已準備好將請求記錄至 API。當您更新階段設定、日誌或階段變數時，不需要重新部署 API。

## 使用 設定 CloudWatch API 記錄 CloudFormation
<a name="set-up-access-logging-using-cloudformation"></a>

使用下列範例 CloudFormation 範本建立 Amazon CloudWatch Logs 日誌群組，並設定階段的執行和存取記錄。若要啟用 CloudWatch Logs，您必須授予 API Gateway 為您的帳戶將日誌讀取和寫入 CloudWatch 的許可。若要深入了解，請參閱《*AWS CloudFormation  使用者指南*》中的[將帳戶與 IAM 角色建立關聯](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-account.html#aws-resource-apigateway-account--examples)。

```
  TestStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      StageName: test
      RestApiId: !Ref MyAPI
      DeploymentId: !Ref Deployment
      Description: "test stage description"
      MethodSettings:
        - ResourcePath: "/*"
          HttpMethod: "*"
          LoggingLevel: INFO
      AccessLogSetting:
        DestinationArn: !GetAtt MyLogGroup.Arn
        Format: $context.extendedRequestId $context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime] "$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId
  MyLogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Join
        - '-'
        - - !Ref MyAPI
          - access-logs
```