API Gateway 映射模板和访问日志记录变量引用 - Amazon API Gateway
$context数据模型、授权者、映射模板和 CloudWatch 访问日志的变量$context 变量模板示例仅适用于访问日志记录的 $context 变量$input 变量$input 变量模板示例$stageVariables$util 变量

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

API Gateway 映射模板和访问日志记录变量引用

本节提供了 Amazon API Gateway 定义的变量和函数的参考信息，这些变量和函数用于数据模型、授权方、映射模板和 CloudWatch 访问日志。有关如何使用这些变量和函数的详细信息，请参阅了解映射模板。有关 Velocity 模板语言 (VTL) 的更多信息，请参阅 VTL 参考。

注意

有关 $method 和 $integration 变量，请参阅 Amazon API Gateway API 请求和响应数据映射参考。

$context数据模型、授权者、映射模板和 CloudWatch 访问日志的变量

以下$context变量可用于数据模型、授权方、映射模板和 CloudWatch 访问日志记录。

有关只能在 CloudWatch 访问日志中使用的$context变量，请参见仅适用于访问日志记录的 $context 变量。

参数 描述
$context.accountId

API 所有者的 AWS 账户 ID。
$context.apiId

API Gateway 分配给您的 API 的标识符。
$context.authorizer.claims.property

成功对方法调用方进行身份验证后从 Amazon Cognito 用户池返回的声明的属性。有关更多信息，请参阅使用 Amazon Cognito 用户池作为授权方控制对 REST API 的访问。

注意

调用 $context.authorizer.claims 将返回 null。
$context.authorizer.principalId

与由客户端发送的令牌关联并从 API Gateway Lambda 授权方（以前称为自定义授权方）返回的委托人用户标识。有关更多信息，请参阅使用 API Gateway 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" 字符串。

有关更多信息，请参阅使用 API Gateway Lambda 授权方。
$context.awsEndpointRequestId

AWS 端点的请求 ID。
$context.domainName

用于调用 API 的完整域名。这应与传入的 Host 标头相同。
$context.domainPrefix

$context.domainName 的第一个标签。
$context.error.message

包含 API Gateway 错误消息的字符串。此变量只能用于GatewayResponse身体映射模板中的简单变量替换（Velocity 模板语言引擎不处理该模板）和访问日志中。有关更多信息，请参阅 使用 CloudWatch 指标监控 WebSocket API 执行 和 设置网关响应以自定义错误响应。
$context.error.messageString $context.error.message 的带引号的值，即 "$context.error.message"。
$context.error.responseType

一种 GatewayResponse. 此变量只能用于GatewayResponse身体映射模板中的简单变量替换（Velocity 模板语言引擎不处理该模板）和访问日志中。有关更多信息，请参阅 使用 CloudWatch 指标监控 WebSocket API 执行 和 设置网关响应以自定义错误响应。
$context.error.validationErrorString

包含详细验证错误消息的字符串。
$context.extendedRequestId API Gateway 生成并分配给 API 请求的扩展 ID。扩展请求 ID 包含调试和故障排除的有用信息。
$context.httpMethod

所用的 HTTP 方法。有效值包括：DELETE、GET、HEAD、OPTIONS、PATCH、POST 和 PUT。
$context.identity.accountId

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

对于需要 API 密钥的 API 方法，此变量是与该方法请求关联的 API 密钥。对于无需 API 密钥的方法，此变量为 null。有关更多信息，请参阅创建和使用带 API 密钥的使用计划。
$context.identity.apiKeyId 与需要 API 密钥的 API 请求关联的 API 密钥 ID。
$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

AWS 组织 ID。
$context.identity.sourceIp

向 API Gateway 终端节点发出请求的即时 TCP 连接的源 IP 地址。
$context.identity.clientCert.clientCertPem

客户端在双向 TLS 身份验证过程中提供的 PEM 编码的客户端证书。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。
$context.identity.clientCert.subjectDN

客户端提供的证书的主题的可分辨名称。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。
$context.identity.clientCert.issuerDN

客户端提供的证书的颁发者的可分辨名称。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。
$context.identity.clientCert.serialNumber

证书的序列号。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。
$context.identity.clientCert.validity.notBefore

证书无效之前的日期。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。
$context.identity.clientCert.validity.notAfter

证书无效后的日期。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。
$context.identity.user

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

API 调用方的 User-Agent 标头。
$context.identity.userArn

身份验证后标识的有效用户的 Amazon Resource Name (ARN)。有关更多信息，请参阅https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html。
$context.path 请求路径。例如，对于 https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child 的非代理请求 URL，$context.path 值为 /{stage}/root/child。
$context.protocol 请求的协议，例如，HTTP/1.1。
注意

API Gateway API 可以接受 HTTP/2 请求，但 API Gateway 使用 HTTP/1.1 向后端集成发送请求。因此，即使客户端发送的请求使用 HTTP/2，请求协议也会记录为 HTTP/1.1。
$context.requestId

请求的 ID。客户可以覆盖此请求 ID。使用 $context.extendedRequestId 用于 API Gateway 生成的唯一请求 ID。
$context.requestOverride.header.header_name

请求标头覆盖。如果定义此参数，则它将包含要使用的标题，而不是 Integration Request (集成请求) 窗格中定义的 HTTP Headers (HTTP 标头)。有关更多信息，请参阅使用映射模板覆盖 API 的请求和响应参数以及状态代码。
$context.requestOverride.path.path_name

请求路径覆盖。如果定义此参数，则它将包含要使用的请求路径，而不是 Integration Request (集成请求) 窗格中定义的 URL Path Parameters (URL 路径参数)。有关更多信息，请参阅使用映射模板覆盖 API 的请求和响应参数以及状态代码。
$context.requestOverride.querystring.querystring_name

请求查询字符串覆盖。如果定义此参数，则它将包含要使用的请求查询字符串，而不是 Integration Request (集成请求) 窗格中定义的 URL Query String Parameters (URL 查询字符串参数)。有关更多信息，请参阅使用映射模板覆盖 API 的请求和响应参数以及状态代码。
$context.responseOverride.header.header_name 响应标头覆盖。如果定义此参数，则它包含要使用的标头，而不是 Integration Response (集成响应) 窗格中定义为 Default mapping (默认映射) 的 Response header (响应标头)。有关更多信息，请参阅使用映射模板覆盖 API 的请求和响应参数以及状态代码。
$context.responseOverride.status 响应状态代码覆盖。如果定义此参数，则它包含要使用的状态代码，而不是 Integration Response (集成响应) 窗格中定义为 Default mapping (默认映射) 的 Method response status (方法响应状态)。有关更多信息，请参阅使用映射模板覆盖 API 的请求和响应参数以及状态代码。
$context.requestTime CLF 格式的请求时间 (dd/MMM/yyyy:HH:mm:ss +-hhmm)。
$context.requestTimeEpoch Epoch 格式的请求时间，以毫秒为单位。
$context.resourceId

API Gateway 分配给您的资源的标识符。
$context.resourcePath

资源路径。例如，对于 https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child 的非代理请求 URI，$context.resourcePath 值为 /root/child。有关更多信息，请参阅教程：使用 HTTP 非代理集成构建 REST API。
$context.stage

API 请求的部署阶段（例如，Beta 或 Prod）。
$context.wafResponseCode

从 AWS WAF 中收到的响应：WAF_ALLOW 或 WAF_BLOCK。如果阶段未与 Web ACL 关联，则不会设置。有关更多信息，请参阅使用 AWS WAF 保护 API。
$context.webaclArn

Web ACL 的完整 ARN，用于决定是允许还是阻止请求。如果阶段未与 Web ACL 关联，则不会设置。有关更多信息，请参阅使用 AWS WAF 保护 API。

$context 变量模板示例

如果您的 API 方法将结构化数据传递到要求数据采用特定格式的后端，则您可能要在映射模板中使用 $context 变量。

以下示例显示了一个映射模板，该模板将传入的 $context 变量映射到后端变量，这些变量在集成请求负载中的名称稍有不同：

注意

请注意，其中一个变量是 API 密钥。此示例假设方法已启用“需要 API 密钥”。

{
    "stage" : "$context.stage",
    "request_id" : "$context.requestId",
    "api_id" : "$context.apiId",
    "resource_path" : "$context.resourcePath",
    "resource_id" : "$context.resourceId",
    "http_method" : "$context.httpMethod",
    "source_ip" : "$context.identity.sourceIp",
    "user-agent" : "$context.identity.userAgent",
    "account_id" : "$context.identity.accountId",
    "api_key" : "$context.identity.apiKey",
    "caller" : "$context.identity.caller",
    "user" : "$context.identity.user",
    "user_arn" : "$context.identity.userArn"
}

仅适用于访问日志记录的 $context 变量

以下 $context 变量仅适用于访问日志记录。有关更多信息，请参阅在 API Gateway 中为 REST API 设置 CloudWatch 日志记录。（有关 WebSocket API 的信息，请参阅使用 CloudWatch 指标监控 WebSocket API 执行。）

参数 说明
$context.authorize.error 授权错误消息。
$context.authorize.latency 授权延迟时间（以毫秒为单位）。
$context.authorize.status 从授权尝试返回的状态代码。
$context.authorizer.error 从授权方返回的错误消息。
$context.authorizer.integrationLatency 授权方延迟（以毫秒为单位）。
$context.authorizer.integrationStatus 从 Lambda 授权方返回的状态代码。
$context.authorizer.latency 授权方延迟（以毫秒为单位）。
$context.authorizer.requestId AWS 端点的请求 ID。
$context.authorizer.status 从授权方返回的状态代码。
$context.authenticate.error 从身份验证尝试返回的错误消息。
$context.authenticate.latency 身份验证延迟时间（以毫秒为单位）。
$context.authenticate.status 从身份验证尝试返回的状态代码。
$context.customDomain.basePathMatched

传入请求所匹配的 API 映射路径。适用于客户端使用自定义域名访问 API 的情况。例如，如果客户端向 https://api.example.com/v1/orders/1234 发送请求，且该请求匹配路径为 v1/orders 的 API 映射，则值为 v1/orders。要了解更多信息，请参阅“对 REST API 使用 API 映射”。
$context.integration.error 从集成返回的错误消息。
$context.integration.integrationStatus 对于 Lambda 代理集成，返回的状态代码来自后端 Lambda 函数代码 AWS Lambda，而不是来自后端 Lambda 函数代码。
$context.integration.latency 集成延迟（毫秒）。等效于 $context.integrationLatency。
$context.integration.requestId AWS 端点的请求 ID。等效于 $context.awsEndpointRequestId。
$context.integration.status 从集成返回的状态代码。对于 Lambda 代理集成，这是 Lambda 函数代码返回的状态代码。
$context.integrationLatency 集成延迟（毫秒）。
$context.integrationStatus 对于 Lambda 代理集成，此参数表示从后端 Lambda 函数代码返回的状态代码 AWS Lambda，而不是从后端 Lambda 函数代码返回的状态码。
$context.responseLatency 响应延迟（毫秒）。
$context.responseLength 响应负载长度（以字节为单位）。
$context.status 方法响应状态。
$context.waf.error 返回的错误消息来自于 AWS WAF。
$context.waf.latency AWS WAF 延迟（以毫秒为单位）。
$context.waf.status 返回的状态码 AWS WAF。
$context.xrayTraceId

X-Ray 跟踪的跟踪 ID。有关更多信息，请参阅使用 API Gateway REST API 设置 AWS X-Ray。

$input 变量

$input 变量表示将由映射模板处理的方法请求负载和参数。它提供四个函数：

变量和函数 说明
$input.body

以字符串形式返回原始请求负载。
$input.json(x)

此函数计算 JSONPath 表达式并以 JSON 字符串形式返回结果。

例如，$input.json('$.pets') 返回一个表示 pets 结构的 JSON 字符串。

有关 JSONPath 的更多信息，请参阅 JSONPath 或适用于 Java 的 JSONPath。
$input.params()

返回所有请求参数的映射。我们建议您使用 $util.escapeJavaScript 对结果进行清理，以避免潜在的注入攻击。要完全控制请求清理，可以使用没有模板的代理集成，并在集成中处理请求清理。
$input.params(x)

在给定参数名称字符串 x 的情况下，返回路径中的方法请求参数值、查询字符串或标头值（按照该顺序搜索）。我们建议您使用 $util.escapeJavaScript 对参数进行清理，以避免潜在的注入攻击。要完全控制参数清理，可以使用没有模板的代理集成，并在集成中处理请求清理。
$input.path(x)

获取一个 JSONPath 表达式字符串 (x) 并返回结果的 JSON 对象表达式。这样，您便可通过 Apache Velocity 模板语言 (VTL) 在本机访问和操作负载的元素。

例如，如果表达式 $input.path('$.pets') 返回一个如下所示的对象：

[
  { 
    "id": 1, 
    "type": "dog", 
    "price": 249.99 
  }, 
  { 
    "id": 2, 
    "type": "cat", 
    "price": 124.99 
  }, 
  { 
    "id": 3, 
    "type": "fish", 
    "price": 0.99 
  } 
]

$input.path('$.pets').count() 将返回 "3"。

有关 JSONPath 的更多信息，请参阅 JSONPath 或适用于 Java 的 JSONPath。

$input 变量模板示例

参数映射模板示例

以下参数映射示例将所有参数（包括path、querystring 和 header）通过 JSON 负载传递到集成终端节点：

#set($allParams = $input.params())
{
  "params" : {
    #foreach($type in $allParams.keySet())
    #set($params = $allParams.get($type))
    "$type" : {
      #foreach($paramName in $params.keySet())
      "$paramName" : "$util.escapeJavaScript($params.get($paramName))"
      #if($foreach.hasNext),#end
      #end
    }
    #if($foreach.hasNext),#end
    #end
  }
}

实际上，此映射模板输出负载中的所有请求参数，如下所述：

{
  "params" : {
     "path" : {    
       "path_name" : "path_value", 
       ...
     }
     "header" : {  
       "header_name" : "header_value",
       ...
     }
     "querystring" : {
       "querystring_name" : "querystring_value",
       ...
     }
   }
}

您可能希望使用 $input 变量来获取查询字符串和请求正文（无论是否使用模型）。您可能还希望将参数和负载（或负载的子部分）放入您的 Lambda 函数。以下示例显示如何执行此操作。

示例 JSON 映射模板（使用 $input）

以下示例介绍如何使用映射从查询字符串读取名称，然后在一个元素中包含整个 POST 正文：

{
    "name" : "$input.params('name')",
    "body" : $input.json('$') 
}

如果 JSON 输入包含无法解析的未转义字符 JavaScript，则可能会返回 400 响应。应用以上 $util.escapeJavaScript($input.json('$')) 将确保正确解析 JSON 输入。

示例映射模板（使用 $input）

以下示例介绍如何将 JSONPath 表达式传递到 json() 方法。您也可以通过使用句点 (.) 后跟属性名称来读取请求正文对象的特定属性：

{
    "name" : "$input.params('name')",
    "body" : $input.json('$.mykey')  
}

如果方法请求负载包含无法解析的未转义字符 JavaScript，则可能会得到400响应。在这种情况下，您需要调用映射模板中的 $util.escapeJavaScript() 函数，如下所示：

{
    "name" : "$input.params('name')",
    "body" : "$util.escapeJavaScript($input.json('$.mykey'))" 
}

示例请求和响应（使用 $input）

以下示例使用所有三个函数：

请求模板：

Resource: /things/{id}

With input template:
{
    "id" : "$input.params('id')",
    "count" : "$input.path('$.things').size()",
    "things" : "$util.escapeJavaScript($input.json('$.things'))"
}

POST /things/abc
{
    "things" : {
        "1" : {},
        "2" : {},
        "3" : {}
    }
}

响应：

{
  "id": "abc",
  "count": "3",
  "things": {
    "1": {},
    "2": {},
    "3": {}
  }
}

有关更多映射示例，请参阅了解映射模板。

$stageVariables

阶段变量可用于参数映射和映射模板，并可用作在方法集成中使用的 ARN 和 URL 中的占位符。有关更多信息，请参阅为 REST API 部署设置阶段变量。

语法 说明
$stageVariables.<variable_name>

<variable_name> 表示阶段变量名称。
$stageVariables['<variable_name>']

<variable_name> 表示任何阶段变量名称。
${stageVariables['<variable_name>']}

<variable_name> 表示任何阶段变量名称。

$util 变量

$util 变量包含映射模板中使用的实用程序函数。

注意

除非另行指定，否则默认字符集为 UTF-8。

函数 描述
$util.escapeJavaScript()

使用 JavaScript 字符串规则对字符串中的字符进行转义。

注意

此函数会将任何常规单引号 (') 变成转义单引号 (\')。但是，转义单引号在 JSON 中无效。因此，当此函数的输出用于 JSON 属性时，必须将任何转义单引号 (\') 变回常规单引号 (')。如下例所示: 

 "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")"
$util.parseJson()

获取“字符串化的”JSON 并返回结果的对象表示形式。您可以使用此函数的结果通过 Apache Velocity 模板语言 (VTL) 在本机访问和操作负载的元素。例如，如果您具有以下负载：

{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}

并使用以下映射模板 

#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
   "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}

您将得到以下输出：

{
   "errorMessageObjKey2ArrVal" : 1
}
$util.urlEncode()

将字符串转换为 “应用程序/x-www-form-urlencoded” 格式。
$util.urlDecode()

解码 “应用程序/x-www-form-urlencoded” 字符串。
$util.base64Encode()

将数据编码为 base64 编码的字符串。
$util.base64Decode()

对 base64 编码字符串中的数据进行解码。