在 API Gateway 中設定 REST API 的 CloudWatch 記錄功能 - Amazon API Gateway
適用於 API Gateway 的 CloudWatch 日誌格式CloudWatch 記錄的許可使用 API Gateway 主控台設定 CloudWatch API 記錄功能使用 設定 CloudWatch API 記錄 AWS CloudFormation

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

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

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

適用於 API Gateway 的 CloudWatch 日誌格式

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

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

為了改善您的安全狀態，建議您在 ERROR或 INFO層級使用執行記錄。您可能需要這樣做，以符合各種合規架構。如需詳細資訊，請參閱AWS Security Hub 《 使用者指南》中的 Amazon API Gateway 控制項。

當您部署 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.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 進行故障診斷。如需詳細資訊，請參閱適用於資料模型、授權方、映射範本及 CloudWatch 存取記錄的 $context 變數。

注意

僅支援 $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 Logs，您必須授予 API Gateway 為您的帳戶將日誌讀取和寫入 CloudWatch 的許可。AmazonAPIGatewayPushToCloudWatchLogs 具有所有必要的許可權。

注意

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

若要將這些許可授予您的帳戶，請建立 apigateway.amazonaws.com 作為其信任實體的 IAM 角色，並將先前的政策連接至 IAM 角色，然後在帳戶的 cloudWatchRoleArn 屬性上設定 IAM 角色 ARN。您必須針對您要啟用 CloudWatch Logs 的每個區域分別設定 cloudWatchRoleArn 屬性。 AWS CloudWatch

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

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

若要設定 CloudWatch API 記錄功能，您必須已將 API 部署至階段。您也必須為您的帳戶設定了適當的 CloudWatch Logs 角色 ARN。

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

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

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

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

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

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

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

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

  7. 若要啟用執行記錄：

    1. 從 CloudWatch Logs 下拉式選單中選取記錄層級。記錄層級如下：

      • 關閉 – 此階段未開啟記錄。

      • 僅限錯誤 – 僅針對錯誤啟用記錄。

      • 錯誤和資訊日誌 – 針對所有事件啟用記錄。

    2. (選用) 選取資料追蹤以開啟您的階段的資料追蹤記錄。這對於故障排除 API 很有用，但可能會導致記錄機密資料。

      注意

      建議您不要針對生產 API 使用資料追蹤。

    3. (選用) 選取詳細指標以開啟詳細的 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。若要進一步了解範例日誌格式，請參閱 適用於 API Gateway 的 CloudWatch 日誌格式。

  9. 選擇 Save changes (儲存變更)。

注意

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

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

使用 設定 CloudWatch API 記錄 AWS CloudFormation

使用下列範例 AWS CloudFormation 範本來建立 Amazon CloudWatch Logs 日誌群組，並設定階段的執行和存取記錄。若要啟用 CloudWatch Logs，您必須授予 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