在 API Gateway 中設定 REST API 的 CloudWatch 記錄 - Amazon API Gateway
CloudWatch API Gateway 的記錄檔格式 CloudWatch 記錄的權限使用 CloudWatch API Gateway 主控台設定 API 記錄使用以下方 CloudWatch 式設定 API 記錄 AWS CloudFormation

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

在 API Gateway 中設定 REST API 的 CloudWatch 記錄

若要協助偵錯與 API 的請求執行或用戶端存取相關的問題，您可以啟用 Amazon CloudWatch Logs 記錄 API 呼叫。如需有關的更多資訊 CloudWatch，請參閱使用 Amazon CloudWatch 指標監控 REST API 執行。

CloudWatch API Gateway 的記錄檔格式

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

記錄的資料包括錯誤或執行追蹤 (例如要求或回應參數值或承載)、Lambda 授權者使用的資料 (以前稱為自訂授權者)、是否需要 API 金鑰、是否啟用使用計畫，以及其他資訊。API Gateway 會從記錄的資料中編輯授權標頭、API 金鑰值和類似的敏感要求參數。

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

在存取記錄中，您身為 API 開發人員且想要記錄誰已存取您的 API 以及發起人存取 API 的方式。您可以建立自己的日誌群組，或選擇由 API Gateway 管理的現有日誌群組。若要指定存取詳細資訊，請選取$context變數、記錄格式和記錄群組目的地。

存取日誌格式必須至少包含 $context.requestId 或 $context.extendedRequestId。最佳做法是在記錄格式$context.extendedRequestId中加入$context.requestId和。

$context.requestId

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

$context.extendedRequestId

延伸重新申請是 API Gateway 產生的唯一 ID。API Gateway 會傳回 x-amz-apigw-id 回應標頭中的此請求 ID。API 呼叫者無法提供或覆寫此請求 ID。您可能需要將此值提供給 Sup AWS port 部門，以協助疑難排解您的 API。如需詳細資訊，請參閱 $context資料模型、授權者、對應範本和 CloudWatch 存取記錄的變數。

注意

僅支援$context變數。

選擇分析後端也會採用的日誌格式，例如通用日誌格式 (CLF)、JSON、XML 或 CSV。您接著可以直接饋送其存取日誌，以計算和轉譯您的指標。若要定義記錄格式，請在舞台上的 accessLogSettings/destinationARN 屬性上設定記錄群組 ARN。您可以在 CloudWatch 主控台中取得記錄群組 ARN。若要定義存取記錄格式，請在舞台上的 accessLogSetting/format 屬性上設定選擇的格式。

一些常用存取日誌格式範例會顯示在 API Gateway 主控台中，並列出如下。

  • CLF (通用日誌格式)：

    $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 記錄的權限

若要啟用 CloudWatch 記錄，您必須授與 API Gateway 權限，才能讀取和寫入帳戶 CloudWatch 的記錄。AmazonAPIGatewayPushToCloudWatchLogs 受管政策 (ARN 為 arn:aws:iam::aws:policy/service-role/AmazonAPIGatewayPushToCloudWatchLogs) 具備所有必要許可：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:DescribeLogGroups",
                "logs:DescribeLogStreams",
                "logs:PutLogEvents",
                "logs:GetLogEvents",
                "logs:FilterLogEvents"
            ],
            "Resource": "*"
        }
    ]
}
注意

API Gateway 呼叫 AWS Security Token Service 以承擔 IAM 角色，因此請確定該區域 AWS STS 已啟用該角色。如需詳細資訊，請參閱管理 AWS 區域中的 AWS STS。

若要將這些許可授與您的帳戶，請建立 IAM 角色apigateway.amazonaws.com做為其受信任的實體，將上述政策附加到 IAM 角色，然後在帳戶的 Arn 屬性上設定 IAM 角色 cloudWatchRoleARN。您必須針對要在其中啟用 CloudWatch 記錄的每個 AWS 區域個別設定 cloudWatchRoleArn 屬性。

如果您在設定 IAM 角色 ARN 時收到錯誤訊息，請檢查您的 AWS Security Token Service 帳戶設定，確認 AWS STS 已在您使用的區域中啟用該功能。如需啟用的詳細資訊 AWS STS，請參閱 IAM 使用者指南中的管理 AWS 區域中的 AWS ST S。

使用 CloudWatch API Gateway 主控台設定 API 記錄

若要設定 CloudWatch API 記錄，您必須將 API 部署到階段。您還必須為您的帳戶配置了適當的 CloudWatch 日誌角色 ARN。

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

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

  3. 對於CloudWatch 記錄角色 ARN，請輸入具有適當許可的 IAM 角色的 ARN。您需要為每個使用 API 網關創建 API Gateway AWS 帳戶 的執行此操作一次。

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

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

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

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

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

  7. 若要啟用執行記錄：

    1. 從 [記錄CloudWatch 檔] 下拉式功能表中選取記錄層級。記錄層級如下：

      • 關閉 — 此階段未開啟記錄功能。

      • 僅限錯誤 — 僅針對錯誤啟用記錄功能。

      • 錯誤和資訊記錄 — 已啟用所有事件的記錄功能。

      • 完整的請求和回應記錄 — 已啟用所有事件的詳細記錄。這對於故障排除 API 很有用，但可能會導致記錄機密資料。

        注意

        我們建議您不要對生產 API 使用完整的請求和回應日誌。

    2. 如有需要，請選取詳細量度以開啟詳細 CloudWatch 量度。

    如需 CloudWatch 測量結果的詳細資訊，請參閱使用 Amazon CloudWatch 指標監控 REST API 執行。

  8. 若要啟用存取記錄：

    1. 開啟自訂存取記錄。

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

    3. 在日誌格式中，輸入日誌格式。您可以選擇 CLF、JSON、XML 或 CSV。若要進一步了解範例日誌格式，請參閱 CloudWatch API Gateway 的記錄檔格式。

  9. 選擇儲存變更。

注意

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

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

使用以下方 CloudWatch 式設定 API 記錄 AWS CloudFormation

使用下列範例 AWS CloudFormation 範本建立 Amazon Lo CloudWatch gs 日誌群組，並設定階段的執行和存取記錄。若要啟用 CloudWatch 記錄，您必須授與 API Gateway 權限，才能讀取和寫入帳戶 CloudWatch 的記錄。若要深入了解，請參閱《AWS CloudFormation  使用者指南》中的將帳戶與 IAM 角色建立關聯。

  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