菜单
Amazon API Gateway
开发人员指南

API Gateway 映射模板参考

Amazon API Gateway 定义了一组变量和函数,以便使用模型和映射模板。本文档介绍了这些函数,并提供了使用输入负载的示例。

访问 $context 变量

$context 变量包含您的 API 调用的所有上下文信息。

$context 变量引用

参数 说明
$context.apiId

API Gateway 分配给您的 API 的标识符。

$context.authorizer.claims.property

成功对方法调用方进行身份验证后从 Amazon Cognito 用户池返回的声明的属性。

注意

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

$context.authorizer.principalId

与由客户端发送的令牌关联并从 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" 字符串。

$context.httpMethod

所用的 HTTP 方法。有效值包括:DELETEGETHEADOPTIONSPATCHPOSTPUT

$context.error.message

API Gateway 错误消息字符串。此变量只能用于 GatewayResponse 正文映射模板 (不由 Velocity 模板语言引擎处理) 中的简单变量替换。

$context.error.messageString $context.error.message 的带引号的值,即 "$context.error.message"
$context.error.responseType

GatewayResponse 的一种类型。此变量只能用于 GatewayResponse 正文映射模板 (不由 Velocity 模板语言引擎处理) 中的简单变量替换。

$context.identity.accountId

与请求关联的 AWS 账户 ID。

$context.identity.apiKey

API 所有者密钥与启用密钥的 API 请求关联。

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

发出请求的调用方的委托人标识符。

$context.identity.cognitoAuthenticationProvider

发出请求的调用方使用的 Amazon Cognito 身份验证提供商。只有在使用 Amazon Cognito 凭证签署请求时才可用。

有关与此变量以及其他 Amazon Cognito $context 变量相关的信息,请参阅 Amazon Cognito 开发人员指南中的使用联合身份

$context.identity.cognitoAuthenticationType

发出请求的调用方的 Amazon Cognito 身份验证类型。只有在使用 Amazon Cognito 凭证签署请求时才可用。

$context.identity.cognitoIdentityId

发出请求的调用方的 Amazon Cognito 身份 ID。只有在使用 Amazon Cognito 凭证签署请求时才可用。

$context.identity.cognitoIdentityPoolId

发出请求的调用方的 Amazon Cognito 身份池 ID。只有在使用 Amazon Cognito 凭证签署请求时才可用。

$context.identity.sourceIp

向 API Gateway 发出请求的 TCP 连接的源 IP 地址。

$context.identity.user

发出请求的用户的委托人标识符。

$context.identity.userAgent

API 调用方的用户代理。

$context.identity.userArn

身份验证后标识的有效用户的 Amazon 资源名称 (ARN)。

$context.path 请求路径。例如,对于 https://{rest-api-id.execute-api.{region}.amazonaws.com/{stage}/root/child 的非代理请求 URI,$context.path 值为 /{stage}/root/child
$context.protocol 请求的协议,例如,HTTP/1.1
$context.requestId

针对 API 调用自动生成的 ID。

$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 自定义集成构建 API

$context.responseLength 响应负载长度,仅可用于访问日志记录。
$context.status 响应状态,仅可用于访问日志记录。
$context.stage

API 调用的部署阶段 (例如 Beta 或 Prod)。

示例

如果您使用 AWS Lambda 作为 API 方法所调用的目标后端,则可能希望使用 $context 变量。例如,您可能希望根据所处阶段是 Beta 阶段还是 Prod 阶段,执行两种不同的操作。

上下文变量模板示例

以下示例展示了将上下文变量映射到集成请求负载的映射模板:

{ "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" }

在以上示例中,所用的方法假定启用了 API 密钥。如果方法请求中未要求提供 API 密钥,api_key 将为空。

对于 AWS_IAM 授权类型的请求,您可以利用 $context.identity.* 属性将授权用户的信息传递到集成终端节点。对于COGNITO_USER_POOLS 授权类型的请求,授权用户的信息中也将包括 $context.identity.cognito*$context.authorizer.claims.* 属性。对于使用自定义 Lambda 函数的授权方的请求,您可以将 $context.authorizer.principalId 和其他适用的 $context.authorizer.* 属性作为授权用户的附加上下文传递给集成终端节点。

借助代理集成,API Gateway 可以在 requestContext.identity 对象中将授权身份信息传递到后端。您无需设置任何映射模板,而是要将输入显式解析到集成后端。以下示例展示了授权类型设置为 AWS_IAM 时,将 requestContext 传递到 Lambda 代理集成终端节点。

{ ..., "requestContext": { "requestTime": "20/Feb/2018:22:48:57 +0000", "path": "/test/", "accountId": "123456789012", "protocol": "HTTP/1.1", "resourceId": "yx5mhem7ye", "stage": "test", "requestTimeEpoch": 1519166937665, "requestId": "3c3ecbaa-1690-11e8-ae31-8f39f1d24afd", "identity": { "cognitoIdentityPoolId": null, "accountId": "123456789012", "cognitoIdentityId": null, "caller": "AIDAJ........4HCKVJZG", "sourceIp": "51.240.196.104", "accessKey": "IAM_user_access_key", "cognitoAuthenticationType": null, "cognitoAuthenticationProvider": null, "userArn": "arn:aws:iam::123456789012:user/alice", "userAgent": "PostmanRuntime/7.1.1", "user": "AIDAJ........4HCKVJZG" }, "resourcePath": "/", "httpMethod": "GET", "apiId": "qr2gd9cfmf" }, ... }

访问 $input 变量

$input 变量表示将由您的模板处理的输入负载和参数。它提供四个函数:

函数引用

变量和函数 描述
$input.body

以字符串形式返回原始负载。

$input.json(x)

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

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

有关 JSONPath 的更多信息,请参阅 JSONPath适用于 Java 的 JSONPath

$input.params()

返回您的 API 调用的所有请求参数的映射。

$input.params(x)

在给定参数名称字符串 x 的情况下,返回路径中的方法请求参数值、查询字符串或标头值 (按照该顺序)。

$input.path(x)

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

例如,$input.path('$.pets').size()

有关 JSONPath 的更多信息,请参阅 JSONPath适用于 Java 的 JSONPath

示例

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

示例 JSON 映射模板

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

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

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

示例输入映射模板

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

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

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

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

参数映射模板示例

以下参数映射示例将所有参数 (包括路径、查询字符串和标头) 通过 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 } }

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

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

示例请求和响应

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

请求模板:

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 变量

用于插入阶段变量的语法类似于:$stageVariables

$stageVariables 引用

语法 描述
$stageVariables.<variable_name>

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

$stageVariables['<variable_name>']

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

${stageVariables['<variable_name>']}

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

访问 $util 变量

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

注意

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

$util 变量引用

功能 说明
$util.escapeJavaScript()

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

注意

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

$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 编码字符串中的数据进行解码。