API Gateway WebSocket API 映射模板参考 - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

API Gateway WebSocket API 映射模板参考

本节总结了 API Gateway 中 WebSocket API 当前支持的变量集。

参数 说明
$context.connectionId

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

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

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

事件类型：CONNECT、MESSAGE 或 DISCONNECT。
$context.messageId

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

选定的路由键。
$context.requestId

与 $context.extendedRequestId 相同。
$context.extendedRequestId 为 API 调用自动生成的 ID，其中包含用于调试/故障排除的更有用的信息。
$context.apiId

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

与由客户端发送的令牌关联并从 API Gateway 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.error.messageString $context.error.message 的带引号的值，即 "$context.error.message"。
$context.error.validationErrorString

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

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

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

发出请求的调用方的委托人标识符。
$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.sourceIp

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

发出请求的用户的委托人标识符。
$context.identity.userAgent

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

身份验证后标识的有效用户的 Amazon Resource Name (ARN)。
$context.requestTime CLF 格式的请求时间 (dd/MMM/yyyy:HH:mm:ss +-hhmm)。
$context.requestTimeEpoch Epoch 格式的请求时间，以毫秒为单位。
$context.stage

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

响应状态。
$input.body

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

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

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

有关 JSONPath 的更多信息，请参阅 JSONPath 或适用于 Java 的 JSONPath。
$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。
$stageVariables.<variable_name>

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

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

<variable_name> 表示任何阶段变量名称。
$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 编码字符串中的数据进行解码。