View a markdown version of this page

REST API 的访问日志记录 - Amazon API Gateway
访问日志格式使用 API Gateway 控制台设置访问日志记录使用 CloudFormation 设置访问日志记录

REST API 的访问日志记录

在访问日志记录中，您可以记录谁访问了您的 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. 通过以下网址登录到 Amazon 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