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

了解映射模板

在 API Gateway 中，API 的方法请求或响应采用的负载格式可能与集成请求或响应的格式不同。

您可以转换数据，以便：

  • 将负载与 API 指定的格式进行匹配。

  • 覆盖 API 的请求和响应参数以及状态代码。

  • 返回客户端选择的响应标头。

  • 在 HTTP 代理或 Amazon Web Service 代理的方法请求中关联路径参数、查询字符串参数或标头参数。

  • 选择要使用与 Amazon Web Services（例如 Amazon DynamoDB 或 Lambda 函数或 HTTP 端点）的集成发送哪些数据。

您可以使用映射模板来转换数据。映射模板是一个用 Velocity 模板语言（VTL）表示的脚本，应用于使用 JSONPath 的负载。

以下示例显示了 PetStore 数据转换的输入数据、映射模板和输出数据。

输入数据 
[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]
映射模板 
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
  {
    "description" : "Item $elem.id is a $elem.type.",
    "askingPrice" : $elem.price
  }#if($foreach.hasNext),#end

#end
]
输出数据 
[
  {
    "description" : "Item 1 is a dog.",
    "askingPrice" : 249.99
  },
  {
    "description" : "Item 2 is a cat.",
    "askingPrice" : 124.99
  },
  {
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }
]

下图显示了此映射模板的详细信息。

映射模板示例

  1. $inputRoot 变量表示上一部分的原始 JSON 数据中的根对象。指令以 # 符号开头。

  2. foreach 循环遍历原始 JSON 数据中的每个对象。

  3. 该描述是原始 JSON 数据中宠物的 id 和 type 拼接的结果。

  4. askingPrice 是原始 JSON 数据中的 price。

1 #set($inputRoot = $input.path('$'))
2 [
3 #foreach($elem in $inputRoot)
4  {
5    "description" : "Item $elem.id is a $elem.type.",
6    "askingPrice" : $elem.price
7  }#if($foreach.hasNext),#end
8 #end
9 ]

在此映射模板中：

  1. 在第 1 行上，$inputRoot 变量表示上一部分的原始 JSON 数据中的根对象。指令以 # 符号开头。

  2. 在第 3 行上，foreach 循环遍历原始 JSON 数据中的每个对象。

  3. 在第 5 行上，description 是原始 JSON 数据中宠物的 id 和 type 拼接的结果。

  4. 在第 6 行上，askingPrice 是原始 JSON 数据中的 price。

有关 Velocity 模板语言的更多信息，请参阅 Apache Velocity – VTL 参考。有关 JSONPath 的更多信息，请参阅 JSONPath – 适用于 JSON 的 XPath。

该映射模板假定基础数据为 JSON 对象。它不要求为数据定义模型。但是，输出数据的模型允许将前面的数据作为语言特定的对象返回。有关更多信息，请参阅了解数据模型。

复杂的映射模板

您还可以创建更复杂的映射模板，例如以下示例，该示例使用截止值来查看宠物是否负担得起。

输入数据 
[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]
映射模板 
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
  {
    "description" : "Item $elem.id is a $elem.type.",
    #if($elem.price > $cheap )#set ($afford = 'too much!') #{else}#set ($afford = $elem.price)#end
"askingPrice" : $afford
  }#if($foreach.hasNext),#end

#end
]
输出数据 
[
  {
    "description" : "Item 1 is a dog.",
     "askingPrice" : too much!
  },
  {
    "description" : "Item 2 is a cat.",
     "askingPrice" : too much!
  },
  {
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }
]

有关更复杂的模型，请参阅示例相册照片示例。