Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

在 API Gateway 中设置 CloudWatch API 日志记录

为了帮助调试与请求执行或客户端对您 API 访问的相关问题,您可以启用 Amazon CloudWatch Logs 记录 API 调用。有关 CloudWatch 的更多信息,请参阅 使用 Amazon CloudWatch 监控 API 执行

针对 API Gateway 的 CloudWatch 日志格式

在 CloudWatch 中有两种类型的 API 日志记录:执行日志记录和访问日志记录。在执行日志记录中,API Gateway 管理 CloudWatch Logs。该过程包括创建日志组和日志流,以及向日志流报告任意调用方的请求和响应。记录的数据包括错误或执行跟踪 (例如请求或响应的参数值或负载)、Lambda 授权方 (以前称为自定义授权方) 使用的数据、是否需要 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 变量,而不支持 $input 等。

选择您的分析后端也采用的日志格式,例如常用日志格式 (CLF)、JSON、XML 或 CSV。然后,您可以将访问日志直接输送到其中,以计算和呈现您的指标。要定义日志格式,请在阶段accessLogSettings/destinationArn 属性上设置日志组 ARN。您可以在 CloudWatch 控制台中获取日志组 ARN,前提是选择了要显示的 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

    继续符 (\) 用作视觉辅助,日志格式不能有任何换行符。

  • JSON

    { "requestId":"$context.requestId", \ "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"> \ <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

    继续符 (\) 用作视觉辅助,日志格式不能有任何换行符。

针对 CloudWatch 日志记录的权限

要启用 CloudWatch Logs,您必须授予 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

要将这些权限授予您的账户,请使用 apigateway.amazonaws.com 作为可信实体创建 IAM 角色,将之前的策略附加到 IAM 角色,然后在您账户cloudWatchRoleArn 属性上设置 IAM 角色 ARN。

如果您在设置 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. 通过 https://console.amazonaws.cn/apigateway 登录 API Gateway 控制台。

  2. 从主导航窗格中选择 Settings (设置) 并在 CloudWatch log role ARN (CloudWatch 日志角色 ARN) 中键入具有相应权限的 IAM 角色的 ARN。您需要执行一次此操作。

  3. 请执行下列操作之一:

    1. 选择现有 API,然后选择一个阶段。

    2. 创建 API 并将其部署到阶段。

  4. Stage Editor (阶段编辑器) 中选择 Logs/Tracing (日志/跟踪)

  5. 启用执行日志记录:

    1. CloudWatch Settings (CloudWatch 设置) 下选择 Enable CloudWatch Logs (启用 CloudWatch 日志)

    2. 从下拉菜单中选择 Error (错误)Info (信息)

    3. 如果需要,请选择 Enable Detailed CloudWatch Metrics (启用详细的 CloudWatch 指标)

    有关 CloudWatch 指标的更多信息,请参阅使用 Amazon CloudWatch 监控 API 执行

  6. 启用访问日志记录:

    1. Custom Access Logging (自定义访问日志记录) 下选择 Enable Access Logging (启用访问日志记录)

    2. Access Log Destination ARN (访问日志目标 ARN) 中输入日志组的 ARN。ARN 格式为 arn:aws:logs:{region}:{account-id}:log-group:API-Gateway-Execution-Logs_{rest-api-id}/{stage-name}

    3. Log Format (日志格式) 中输入日志格式。您可以选择 CLFJSONXMLCSV 以使用提供的示例之一作为指南。

  7. 选择 Save Changes (保存更改)

注意

您可以分别启用执行日志记录和访问日志记录,这两者相互独立。

API Gateway 现已准备好记录对您 API 的请求。在更新阶段设置、日志或阶段变量时,您无需重新部署 API。