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

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

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

以下 $context 变量可用于数据模型、授权方、映射模板和 CloudWatch 访问日志记录。API Gateway 可能会添加其他上下文变量。

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

"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}

$context 变量模板示例

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

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

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

此映射模板的输出应与以下内容类似：

{
  stage: 'prod',
  request_id: 'abcdefg-000-000-0000-abcdefg',
  api_id: 'abcd1234',
  resource_path: '/',
  resource_id: 'efg567',
  http_method: 'GET',
  source_ip: '192.0.2.1',
  user-agent: 'curl/7.84.0',
  account_id: '111122223333',
  api_key: 'MyTestKey',
  caller: 'ABCD-0000-12345',
  user: 'ABCD-0000-12345',
  user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}

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

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

$input 变量

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

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

$input 变量模板示例

以下示例显示了如何在映射模板中使用 $input 变量：您可以使用模拟集成或用于将输入事件返回到 API Gateway 的 Lambda 非代理集成来尝试这些示例。

参数映射模板示例

以下示例将所有请求参数（包括 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" : "myparam"
                }
    ,        "querystring" : {
            "querystring1" : "value1,value2"
      ,            "querystring2" : "value3"
                }
    ,        "header" : {
            "header3" : "value3"
      ,            "header2" : "value2"
      ,            "header1" : "value1"
                }
          }
}

JSON 映射模板示例

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

以下示例使用映射模板来获取负载的子部分。此示例获取输入参数 name，然后获取整个 POST 正文：

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

对于包含查询字符串参数 name=Bella&type=dog 和以下正文的请求：

{
    "Price" : "249.99",
    "Age": "6"
}

此映射模板的输出应与以下内容类似：

{
    "name" : "Bella",
    "body" : {"Price":"249.99","Age":"6"}
}

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

上面的示例在应用了 $util.escapeJavaScript($input.json('$')) 之后会如下所示：

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

在这种情况下，此映射模板的输出应与以下内容类似：

{
    "name" : "Bella",
    "body": {\"Price\":\"249.99\",\"Age\":\"6\"}
}

JSONPath 表达式示例

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

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

对于包含查询字符串参数 name=Bella&type=dog 和以下正文的请求：

{
    "Price" : "249.99",
    "Age": "6"
}

此映射模板的输出应与以下内容类似：

{
    "name" : "Bella",
    "body" : "6"
}

如果方法请求负载包含无法通过 JavaScript 解析的非转义字符，则 API Gateway 可能会返回 400 响应。应用 $util.escapeJavaScript() 来确保正确解析 JSON 输入。

上面的示例在应用了 $util.escapeJavaScript($input.json('$.Age')) 之后会如下所示：

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

在这种情况下，此映射模板的输出应与以下内容类似：

{
    "name" : "Bella",
    "body": "\"6\""
}

请求和响应示例

以下示例对路径为 /things/{id} 的资源使用 $input.params()、$input.path() 和 $input.json()：

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

对于包含路径参数 123 和以下正文的请求：

{
      "things": {
            "1": {},
            "2": {},
            "3": {}
      }
}

此映射模板的输出应与以下内容类似：

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

如果方法请求负载包含无法通过 JavaScript 解析的非转义字符，则 API Gateway 可能会返回 400 响应。应用 $util.escapeJavaScript() 来确保正确解析 JSON 输入。

上面的示例在应用了 $util.escapeJavaScript($input.json('$.things')) 之后会如下所示：

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

此映射模板的输出应与以下内容类似：

{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}

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

$stageVariables

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

$util 变量

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

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

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

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

{
   "errorMessageObjKey2ArrVal" : 1
}