# API Gateway 的访问日志记录的变量
<a name="api-gateway-variables-for-access-logging"></a>

 在访问日志记录中，作为 API 开发人员，您想要记录谁访问了您的 API 以及调用方访问 API 的方式。您可以创建自己的日志组，或者选择可由 API Gateway 管理的现有日志组。要指定访问详细信息，可以使用以下区分大小写的 `$context` 变量。

有关数据转换的参考变量的列表，请参阅 [API Gateway 的用于数据转换的变量](api-gateway-mapping-template-reference.md)。


| 参数 | 说明 | 
| --- | --- | 
| \$1context.accountId |  API 拥有者的 Amazon 账户 ID。  | 
| \$1context.apiId |  API Gateway 分配给您的 API 的标识符。  | 
| \$1context.authorize.error | 授权错误消息。 | 
| \$1context.authorize.latency | 授权延迟时间（以毫秒为单位）。 | 
| \$1context.authorize.status | 从授权尝试返回的状态代码。 | 
| \$1context.authorizer.claims.property |  成功对方法调用方进行身份验证后从 Amazon Cognito 用户池返回的声明的属性。有关更多信息，请参阅 [使用 Amazon Cognito 用户池作为授权方控制对 REST API 的访问](apigateway-integrate-with-cognito.md)。  调用 `$context.authorizer.claims` 将返回 null。   | 
| \$1context.authorizer.error | 从授权方返回的错误消息。 | 
| \$1context.authorizer.integrationLatency | 授权方集成延迟（毫秒）。 | 
| \$1context.authorizer.integrationStatus | 从 Lambda 授权方返回的状态代码。 | 
| \$1context.authorizer.latency | 授权方延迟（以毫秒为单位）。 | 
| \$1context.authorizer.principalId |  与由客户端发送的令牌关联并从 API Gateway Lambda 授权方（以前称为自定义授权方）返回的委托人用户标识。有关更多信息，请参阅 [使用 API Gateway Lambda 授权方](apigateway-use-lambda-authorizer.md)。  | 
| \$1context.authorizer.property |  从 API Gateway Lambda 授权方函数返回的 `context` 映射的指定键/值对的字符串化值。例如，如果授权方返回以下 `context` 映射： <pre>"context" : {<br />  "key": "value",<br />  "numKey": 1,<br />  "boolKey": true<br />}</pre> 调用 `$context.authorizer.key` 将返回 `"value"` 字符串，调用 `$context.authorizer.numKey` 将返回 `"1"` 字符串，而调用 `$context.authorizer.boolKey` 将返回 `"true"` 字符串。 对于*属性*，唯一支持的特殊字符是下划线 `(_)` 字符。 有关更多信息，请参阅 [使用 API Gateway Lambda 授权方](apigateway-use-lambda-authorizer.md)。  | 
| \$1context.authorizer.requestId | Amazon 端点的请求 ID。 | 
| \$1context.authorizer.status | 从授权方返回的状态代码。 | 
| \$1context.authenticate.error | 从身份验证尝试返回的错误消息。 | 
| \$1context.authenticate.latency | 身份验证延迟时间（以毫秒为单位）。 | 
| \$1context.authenticate.status | 从身份验证尝试返回的状态代码。 | 
| \$1context.awsEndpointRequestId |  Amazon 端点的请求 ID。  | 
| \$1context.cipherSuite |  客户端与 API Gateway 在 TLS 握手过程中协商的、采用 IANA 格式的密码。 | 
| \$1context.customDomain.basePathMatched |  传入请求所匹配的 API 映射路径。适用于客户端使用自定义域名访问 API 的情况。例如，如果客户端向 `https://api.example.com/v1/orders/1234` 发送请求，且该请求匹配路径为 `v1/orders` 的 API 映射，则值为 `v1/orders`。要了解更多信息，请参阅“[使用 API 映射将 API 阶段连接到 REST API 的自定义域名](rest-api-mappings.md)”。  | 
| \$1context.customDomain.routingRuleIdMatched | 传入请求所匹配的路由规则。适用于客户端使用自定义域名访问 API 的情况。要了解更多信息，请参阅[将 API 阶段连接到 REST API 的自定义域名的路由规则](rest-api-routing-rules.md)。 | 
| \$1context.deploymentId | API 部署的 ID。 | 
| \$1context.domainName |  用于调用 API 的完整域名。这应与传入的 `Host` 标头相同。  | 
| \$1context.domainPrefix |  `$context.domainName` 的第一个标签。  | 
| \$1context.endpointType | API 的端点类型。 | 
| \$1context.error.message |  包含 API Gateway 错误消息的字符串。此变量只能用于 [GatewayResponse](https://docs.amazonaws.cn/apigateway/latest/api/API_GatewayResponse.html) 正文映射模板中（不由 Velocity 模板语言引擎处理）和访问日志记录中的简单变量替换。有关更多信息，请参阅 [使用 CloudWatch 指标监控 WebSocket API 执行](apigateway-websocket-api-logging.md) 和 [设置网关响应以自定义错误响应](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)。  | 
| \$1context.error.messageString | \$1context.error.message 的带引号的值，即 "\$1context.error.message"。 | 
| \$1context.error.responseType |  [GatewayResponse](https://docs.amazonaws.cn/apigateway/latest/api/API_GatewayResponse.html) 的[类型](https://docs.amazonaws.cn/apigateway/latest/api/API_GatewayResponse.html#responseType) 此变量只能用于 [GatewayResponse](https://docs.amazonaws.cn/apigateway/latest/api/API_GatewayResponse.html) 正文映射模板中（不由 Velocity 模板语言引擎处理）和访问日志记录中的简单变量替换。有关更多信息，请参阅 [使用 CloudWatch 指标监控 WebSocket API 执行](apigateway-websocket-api-logging.md) 和 [设置网关响应以自定义错误响应](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)。  | 
| \$1context.error.validationErrorString |  包含详细验证错误消息的字符串。  | 
| \$1context.extendedRequestId | API Gateway 生成并分配给 API 请求的扩展 ID。扩展请求 ID 包含调试和故障排除的有用信息。 | 
| \$1context.httpMethod |  所用的 HTTP 方法。有效值包括：`DELETE`、`GET`、`HEAD`、`OPTIONS`、`PATCH`、`POST` 和 `PUT`。  | 
| \$1context.identity.accountId |  与请求关联的 Amazon 账户 ID。  | 
| \$1context.identity.apiKey |  对于需要 API 密钥的 API 方法，此变量是与该方法请求关联的 API 密钥。对于无需 API 密钥的方法，此变量为 null。有关更多信息，请参阅 [API Gateway 中针对 REST API 的使用计划和 API 密钥](api-gateway-api-usage-plans.md)。  | 
| \$1context.identity.apiKeyId | 与需要 API 密钥的 API 请求关联的 API 密钥 ID。 | 
| \$1context.identity.caller |  签发请求的调用方的委托人标识符。对于使用 IAM 授权的资源支持此项。  | 
| \$1context.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 开发人员指南* 中的[使用联合身份](https://docs.amazonaws.cn/cognito/latest/developerguide/cognito-identity.html)。 | 
| \$1context.identity.cognitoAuthenticationType |  发出请求的调用方的 Amazon Cognito 身份验证类型。仅当使用 Amazon Cognito 凭证对请求签名时才可用。可能的值包括经过身份验证的身份的 `authenticated` 和未经身份验证的身份的 `unauthenticated`。 | 
| \$1context.identity.cognitoIdentityId |  发出请求的调用方的 Amazon Cognito 身份 ID。仅当使用 Amazon Cognito 凭证对请求签名时才可用。  | 
| \$1context.identity.cognitoIdentityPoolId |  发出请求的调用方的 Amazon Cognito 身份池 ID。仅当使用 Amazon Cognito 凭证对请求签名时才可用。  | 
| \$1context.identity.principalOrgId |  [Amazon 组织 ID](https://docs.amazonaws.cn/organizations/latest/userguide/orgs_manage_org_details.html)。  | 
| \$1context.identity.sourceIp |  向 API Gateway 端点发出请求的即时 TCP 连接的源 IP 地址。  | 
| \$1context.identity.clientCert.clientCertPem |  客户端在双向 TLS 身份验证过程中提供的 PEM 编码的客户端证书。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。  | 
| \$1context.identity.clientCert.subjectDN |  客户端提供的证书的主题的可分辨名称。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。  | 
| \$1context.identity.clientCert.issuerDN |  客户端提供的证书的颁发者的可分辨名称。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。  | 
| \$1context.identity.clientCert.serialNumber |  证书的序列号。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。  | 
| \$1context.identity.clientCert.validity.notBefore |  证书无效之前的日期。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。  | 
| \$1context.identity.clientCert.validity.notAfter |  证书无效后的日期。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。  | 
|  \$1context.identity.vpcId | 向 API Gateway 端点发出请求的 VPC 的 VPC ID。 | 
|  \$1context.identity.vpceId |  向 API Gateway 端点发出请求的 VPC 端点的 VPC 端点 ID。仅当您具有私有 API 时才会显示。  | 
| \$1context.identity.user |  将获得资源访问权限授权的用户的委托人标识符。对于使用 IAM 授权的资源支持此项。  | 
| \$1context.identity.userAgent |  API 调用方的 [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 标头。  | 
| \$1context.identity.userArn |  身份验证后标识的有效用户的 Amazon Resource Name (ARN)。有关更多信息，请参阅 [https://docs.amazonaws.cn/IAM/latest/UserGuide/id_users.html](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_users.html)。  | 
| \$1context.integration.error | 从集成返回的错误消息。 | 
| \$1context.integration.integrationStatus | 对于 Lambda 代理集成，从 Amazon Lambda（而不是从后端 Lambda 函数代码）返回的状态代码。 | 
| \$1context.integration.latency | 集成延迟（毫秒）。等效于 \$1context.integrationLatency。 | 
| \$1context.integration.requestId | Amazon 端点的请求 ID。等效于 \$1context.awsEndpointRequestId。 | 
| \$1context.integration.responseTransferMode | 您的集成的响应传输模式。此值可以是 BUFFERED 或 STREAMED。 | 
| \$1context.integration.status | 从集成返回的状态代码。对于 Lambda 代理集成，这是 Lambda 函数代码返回的状态代码。 | 
| \$1context.integration.timeToAllHeaders | 从 API Gateway 建立集成连接到从客户端接收所有集成响应头之间的时间间隔。 | 
| \$1context.integration.timeToFirstContent | API Gateway 建立集成连接到接收第一个内容字节之间的时间间隔。 | 
| \$1context.integrationLatency | 集成延迟（毫秒）。 | 
| \$1context.integrationStatus | 对于 Lambda 代理集成，此参数表示从 Amazon Lambda（而不是从后端 Lambda 函数代码）返回的状态代码。 | 
| \$1context.isCanaryRequest |  如果请求定向到金丝雀，将返回 `true`，如果请求没有定向到金丝雀，将返回 `false`。仅当您启用金丝雀时才会显示。 | 
| \$1context.path | 请求路径。例如，对于 https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child 的非代理请求 URL，\$1context.path 值为 /\$1stage\$1/root/child。 | 
| \$1context.protocol | 请求的协议，例如，HTTP/1.1。 API Gateway API 可以接受 HTTP/2 请求，但 API Gateway 使用 HTTP/1.1 向后端集成发送请求。因此，即使客户端发送的请求使用 HTTP/2，请求协议也会记录为 HTTP/1.1。   | 
| \$1context.requestId |  请求的 ID。客户可以覆盖此请求 ID。使用 `$context.extendedRequestId` 用于 API Gateway 生成的唯一请求 ID。  | 
| \$1context.requestOverride.header.header\$1name |  请求标头覆盖。如果定义此参数，则它将包含要使用的标题，而不是**集成请求**窗格中定义的 **HTTP 标头**。有关更多信息，请参阅 [针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码](apigateway-override-request-response-parameters.md)。  | 
| \$1context.requestOverride.path.path\$1name |  请求路径覆盖。如果定义此参数，则它将包含要使用的请求路径，而不是**集成请求**窗格中定义的 **URL 路径参数**。有关更多信息，请参阅 [针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码](apigateway-override-request-response-parameters.md)。  | 
| \$1context.requestOverride.querystring.querystring\$1name |  请求查询字符串覆盖。如果定义此参数，则它将包含要使用的请求查询字符串，而不是**集成请求**窗格中定义的 **URL 查询字符串参数**。有关更多信息，请参阅 [针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码](apigateway-override-request-response-parameters.md)。  | 
| \$1context.responseLatency | 响应延迟（毫秒）。 | 
| \$1context.responseLength | 响应负载长度（以字节为单位）。 | 
| \$1context.responseOverride.header.header\$1name | 响应标头覆盖。如果定义此参数，则它包含要使用的标头，而不是集成响应窗格中定义为默认映射的响应标头。有关更多信息，请参阅 [针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码](apigateway-override-request-response-parameters.md)。 | 
| \$1context.responseOverride.status | 响应状态代码覆盖。如果定义此参数，则它包含要使用的状态代码，而不是集成响应窗格中定义为默认映射的方法响应状态。有关更多信息，请参阅 [针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码](apigateway-override-request-response-parameters.md)。 | 
| \$1context.requestTime | [CLF](https://httpd.apache.org/docs/current/logs.html#common) 格式的请求时间 (dd/MMM/yyyy:HH:mm:ss \$1-hhmm)。 | 
| \$1context.requestTimeEpoch | [Epoch](https://en.wikipedia.org/wiki/Unix_time) 格式的请求时间，以毫秒为单位。 | 
| \$1context.resourceId |  API Gateway 分配给您的资源的标识符。  | 
| \$1context.resourcePath |  资源路径。例如，对于 `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child` 的非代理请求 URI，`$context.resourcePath` 值为 `/root/child`。有关更多信息，请参阅 [教程：使用 HTTP 非代理集成创建 REST API](api-gateway-create-api-step-by-step.md)。  | 
| \$1context.stage |  API 请求的部署阶段（例如，`Beta` 或 `Prod`）。  | 
| \$1context.status | 方法响应状态。 | 
| \$1context.tlsVersion |  客户端与 API Gateway 在 TLS 握手过程中协商的 TLS 版本。 | 
| \$1context.waf.error | 从 返回的错误消息Amazon WAF | 
| \$1context.waf.latency | Amazon WAF 延迟时间（以毫秒为单位） | 
| \$1context.waf.status | 从 返回的状态代码Amazon WAF | 
| \$1context.xrayTraceId |  X-Ray 跟踪的跟踪 ID。有关更多信息，请参阅 [使用 API Gateway REST API 设置 Amazon X-Ray](apigateway-enabling-xray.md)。  | 
| \$1context.wafResponseCode |  从 [Amazon WAF](https://docs.amazonaws.cn/waf/latest/developerguide/waf-chapter.html) 中收到的响应：`WAF_ALLOW` 或 `WAF_BLOCK`。如果阶段未与 Web ACL 关联，则不会设置。有关更多信息，请参阅 [在 API Gateway 中使用 Amazon WAF 保护 REST API](apigateway-control-access-aws-waf.md)。  | 
| \$1context.webaclArn |  Web ACL 的完整 ARN，用于决定是允许还是阻止请求。如果阶段未与 Web ACL 关联，则不会设置。有关更多信息，请参阅 [在 API Gateway 中使用 Amazon WAF 保护 REST API](apigateway-control-access-aws-waf.md)。  |