API Gateway 的用于数据转换的变量 - Amazon API Gateway
数据转换的上下文变量输入变量阶段变量Util 变量
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

API Gateway 的用于数据转换的变量

创建参数映射时，可以使用上下文变量作为数据来源。创建映射模板转换时，可以在用 Velocity Template Language (VTL) 编写的脚本中使用上下文变量、输入和 util 变量。有关使用这些参考变量的映射模板的示例，请参阅使用变量来映射 API Gateway 的模板转换的示例。

有关访问日志记录的参考变量的列表，请参阅 API Gateway 的访问日志记录的变量。

数据转换的上下文变量

可以使用以下区分大小写的 $context 变量来进行数据转换。

参数 说明
$context.accountId

API 拥有者的 Amazon 账户 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

Amazon 端点的请求 ID。
$context.deploymentId

API 部署的 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

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

对于需要 API 密钥的 API 方法，此变量是与该方法请求关联的 API 密钥。对于无需 API 密钥的方法，此变量为 null。有关更多信息，请参阅 API Gateway 中针对 REST API 的使用计划和 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

Amazon 组织 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.vpcId

向 API Gateway 端点发出请求的 VPC 的 VPC ID。
$context.identity.vpceId

向 API Gateway 端点发出请求的 VPC 端点的 VPC 端点 ID。仅当您具有私有 API 时才会显示。
$context.identity.user

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

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

身份验证后标识的有效用户的 Amazon Resource Name (ARN)。有关更多信息，请参阅 https://docs.amazonaws.cn/IAM/latest/UserGuide/id_users.html。
$context.isCanaryRequest

如果请求定向到金丝雀，将返回 true，如果请求没有定向到金丝雀，将返回 false。仅当您启用金丝雀时才会显示。
$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

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

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

请求查询字符串覆盖。如果定义此参数，则它将包含要使用的请求查询字符串，而不是集成请求窗格中定义的 URL 查询字符串参数。有关更多信息，请参阅 针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码。
$context.responseOverride.header.header_name 响应标头覆盖。如果定义此参数，则它包含要使用的标头，而不是集成响应窗格中定义为默认映射的响应标头。有关更多信息，请参阅 针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码。
$context.responseOverride.status 响应状态代码覆盖。如果定义此参数，则它包含要使用的状态代码，而不是集成响应窗格中定义为默认映射的方法响应状态。有关更多信息，请参阅 针对 API Gateway 中的 REST API 覆盖 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

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

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

输入变量

可以使用以下区分大小写的 $input 变量来引用方法请求有效载荷和方法请求参数。可以执行以下功能：

变量和函数 说明
$input.body

以字符串形式返回原始请求负载。您可以使用 $input.body 来保留整个浮点数，例如 10.00。
$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').size() 将返回 "3"。

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

阶段变量

在方法集成中，可以使用以下阶段变量作为 ARN 和 URL 的占位符。有关更多信息，请参阅 在 API Gateway 中对 REST API 使用阶段变量。

语法 描述
$stageVariables.variable_name、$stageVariables['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()

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

对“application/x-www-form-urlencoded”字符串进行解码。
$util.base64Encode()

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

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