View a markdown version of this page

REST APIs存取記錄 - Amazon API Gateway
存取日誌格式使用 API Gateway 主控台設定存取記錄使用 設定存取記錄 CloudFormation

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

REST APIs存取記錄

在存取日誌中，您會記錄誰已存取您的 API，以及發起人如何存取 API。您可以建立自己的日誌群組，或選擇現有的日誌群組。若要指定存取權詳細資訊，您可以選取 $context 變數、日誌格式及日誌群組目的地。

存取日誌格式

存取日誌格式必須至少包含 $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 存取記錄的變數。

選擇分析後端也會採用的日誌格式，例如通用日誌格式 (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

使用 API Gateway 主控台設定存取記錄

設定存取記錄之前，請將 API 部署至階段，並為您的帳戶設定適當的 CloudWatch Logs 角色 ARN。

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

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

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

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

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

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

  5. 開啟自訂存取記錄。

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

  7. 針對日誌格式，輸入日誌格式。您可以選擇 CLF、JSON、XML 或 CSV。若要進一步了解範例日誌格式，請參閱 存取日誌格式。

  8. 選擇儲存變更。

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

使用 設定存取記錄 CloudFormation

使用下列範例 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
      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