配置 WebSocket API 的日志记录 - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

配置 WebSocket API 的日志记录

您可以启用日志记录以将日志写入 CloudWatch Logs。在 CloudWatch 中有两种类型的 API 日志记录：执行日志记录和访问日志记录。在执行日志记录中，API Gateway 管理 CloudWatch Logs。该过程包括创建日志组和日志流，以及向日志流报告任意调用方的请求和响应。

在访问日志记录中，作为 API 开发人员，您想要记录谁访问了您的 API 以及调用方访问 API 的方式。您可以创建自己的日志组，或者选择可由 API Gateway 管理的现有日志组。要指定访问详细信息，您可以选择 $context 变量（以您选择的格式表示），并选择日志组作为目标。

有关如何设置 CloudWatch 日志记录的说明，请参阅使用 API Gateway 控制台设置 CloudWatch API 日志记录。

当您指定 Log Format (日志格式) 时，您可以选择要记录的上下文变量。支持以下变量。

参数 说明
$context.apiId

API Gateway 分配给您的 API 的标识符。
$context.authorize.error 授权错误消息。
$context.authorize.latency 授权延迟时间（以毫秒为单位）。
$context.authorize.status 从授权尝试返回的状态代码。
$context.authorizer.error 从授权方返回的错误消息。
$context.authorizer.integrationLatency Lambda 授权方延迟（以毫秒为单位）。
$context.authorizer.integrationStatus 从 Lambda 授权方返回的状态代码。
$context.authorizer.latency 授权方延迟（以毫秒为单位）。
$context.authorizer.requestId Amazon 终端节点的请求 ID。
$context.authorizer.status 从授权方返回的状态代码。
$context.authorizer.principalId

与由客户端发送的令牌相关联的委托人用户标识，从API Gateway Lambda 授权方 Lambda 函数返回。（Lambda 授权方以前称为自定义授权方。）
$context.authorizer.property

从 API Gateway Lambda 授权方函数返回的 context 映射的指定键/值对的字符串化值。例如，如果授权方返回以下 context 映射：

"context" : {
                            "key": "value",
                            "numKey": 1,
                            "boolKey": true
                            }

调用 $context.authorizer.key 将返回 "value" 字符串，调用 $context.authorizer.numKey 将返回 "1" 字符串，而调用 $context.authorizer.boolKey 将返回 "true" 字符串。
$context.authenticate.error 从身份验证尝试返回的错误消息。
$context.authenticate.latency 身份验证延迟时间（以毫秒为单位）。
$context.authenticate.status 从身份验证尝试返回的状态代码。
$context.connectedAt

Epoch 格式的连接时间。
$context.connectionId

连接的唯一 ID，可用于对客户端进行回调。
$context.domainName

WebSocket API 的域名。这可用于对客户端进行回调（而不是硬编码值）。
$context.error.message

包含 API Gateway 错误消息的字符串。
$context.error.messageString $context.error.message 的带引号的值，即 "$context.error.message"。
$context.error.responseType

错误响应类型。
$context.error.validationErrorString

包含详细验证错误消息的字符串。
$context.eventType

事件类型：CONNECT、MESSAGE 或 DISCONNECT。
$context.extendedRequestId 等效于 $context.requestId。
$context.identity.accountId

与请求关联的 Amazon 账户 ID。
$context.identity.apiKey

API 所有者密钥与启用密钥的 API 请求关联。
$context.identity.apiKeyId API 密钥 ID 与启用密钥的 API 请求关联
$context.identity.caller

签发请求的调用方的委托人标识符。对于使用 IAM 授权的路由支持此项。
$context.identity.cognitoAuthenticationProvider

发出请求的调用方使用的 Amazon Cognito 身份验证提供商的逗号分隔列表。仅当使用 Amazon Cognito 凭证对请求签名时才可用。

例如，对于 Amazon Cognito 身份池中的身份，cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim

有关更多信息，请参阅 Amazon Cognito 开发人员指南 中的使用联合身份。
$context.identity.cognitoAuthenticationType

发出请求的调用方的 Amazon Cognito 身份验证类型。仅当使用 Amazon Cognito 凭证对请求签名时才可用。可能的值包括经过身份验证的身份的 authenticated 和未经身份验证的身份的 unauthenticated。
$context.identity.cognitoIdentityId

发出请求的调用方的 Amazon Cognito 身份 ID。仅当使用 Amazon Cognito 凭证对请求签名时才可用。
$context.identity.cognitoIdentityPoolId

发出请求的调用方的 Amazon Cognito 身份池 ID。仅当使用 Amazon Cognito 凭证对请求签名时才可用。
$context.identity.principalOrgId

Amazon 组织 ID。对于使用 IAM 授权的路由支持此项。
$context.identity.sourceIp

向 API Gateway 发出请求的 TCP 连接的源 IP 地址。
$context.identity.user

将获得资源访问权限授权的用户的委托人标识符。对于使用 IAM 授权的路由支持此项。
$context.identity.userAgent

API 调用方的用户代理。
$context.identity.userArn

身份验证后标识的有效用户的 Amazon 资源名称 (ARN)。
$context.integration.error 从集成返回的错误消息。
$context.integration.integrationStatus 对于 Lambda 代理集成，从 Amazon Lambda（而不是从后端 Lambda 函数代码）返回的状态代码。
$context.integration.latency 集成延迟（毫秒）。等效于 $context.integrationLatency。
$context.integration.requestId Amazon 终端节点的请求 ID。等效于 $context.awsEndpointRequestId。
$context.integration.status 从集成返回的状态代码。对于 Lambda 代理集成，这是 Lambda 函数代码返回的状态代码。等效于 $context.integrationStatus。
$context.integrationLatency 集成延迟（毫秒），仅可用于访问日志记录。
$context.messageId

消息的唯一服务器端 ID。仅当 $context.eventType 为 MESSAGE 时才可用。
$context.requestId

与 $context.extendedRequestId 相同。
$context.requestTime CLF 格式的请求时间 (dd/MMM/yyyy:HH:mm:ss +-hhmm)。
$context.requestTimeEpoch Epoch 格式的请求时间，以毫秒为单位。
$context.routeKey

选定的路由键。
$context.stage

API 调用的部署阶段（例如测试或生产）。
$context.status

响应状态。
$context.waf.error 从 返回的错误消息Amazon WAF
$context.waf.latency Amazon WAF 延迟时间（以毫秒为单位）。
$context.waf.status 从 返回的状态代码Amazon WAF

一些常用访问日志格式的示例在 API Gateway 控制台中显示，下面列出了这些格式。

  • CLF (常用日志格式 )：

    $context.identity.sourceIp $context.identity.caller \
$context.identity.user [$context.requestTime] "$context.eventType $context.routeKey $context.connectionId" \
$context.status $context.requestId

    继续符 (\) 用作视觉辅助。日志格式必须为单行。您可以在日志格式末尾添加换行符 (\n)，以便在每个日志条目末尾添加换行符。

  • JSON: 

    {
"requestId":"$context.requestId", \
"ip": "$context.identity.sourceIp", \
"caller":"$context.identity.caller", \
"user":"$context.identity.user", \
"requestTime":"$context.requestTime", \
"eventType":"$context.eventType", \
"routeKey":"$context.routeKey", \
"status":"$context.status", \
"connectionId":"$context.connectionId"
}

    继续符 (\) 用作视觉辅助。日志格式必须为单行。您可以在日志格式末尾添加换行符 (\n)，以便在每个日志条目末尾添加换行符。

  • XML: 

    <request id="$context.requestId"> \
 <ip>$context.identity.sourceIp</ip> \
 <caller>$context.identity.caller</caller> \
 <user>$context.identity.user</user> \
 <requestTime>$context.requestTime</requestTime> \
 <eventType>$context.eventType</eventType> \
 <routeKey>$context.routeKey</routeKey> \
 <status>$context.status</status> \
 <connectionId>$context.connectionId</connectionId> \
</request>

    继续符 (\) 用作视觉辅助。日志格式必须为单行。您可以在日志格式末尾添加换行符 (\n)，以便在每个日志条目末尾添加换行符。

  • CSV (逗号分隔值)：

    $context.identity.sourceIp,$context.identity.caller, \
$context.identity.user,$context.requestTime,$context.eventType, \
$context.routeKey,$context.connectionId,$context.status, \
$context.requestId

    继续符 (\) 用作视觉辅助。日志格式必须为单行。您可以在日志格式末尾添加换行符 (\n)，以便在每个日志条目末尾添加换行符。