# API Gateway 中 REST API 的映射模板转换
<a name="models-mappings"></a>

映射模板转换使用映射模板来修改集成请求或集成响应。*映射模板*是以 [Velocity Template Language（VTL）](https://velocity.apache.org/engine/devel/vtl-reference.html)表示的脚本，并使用 [JSONPath](https://goessner.net/articles/JsonPath/) 基于 `Content-type` 标头应用于有效载荷。使用映射模板转换时使用映射模板。此部分介绍与映射模板相关的概念性信息。

下图显示了与 PetStore 集成端点集成的 `POST /pets` 资源的请求生命周期。在此 API 中，用户发送有关宠物的数据，而集成端点返回与宠物关联的收养费。在此请求生命周期中，映射模板转换会将请求正文筛选到集成端点，并从集成端点筛选响应正文。

![\[请求生命周期示例\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/mapping-template-transforms.png)


以下各节解释请求和响应生命周期。

## 方法请求和集成请求
<a name="models-mappings-request"></a>

在前面的示例中，如果这是发送到方法请求的请求正文：

```
POST /pets
    HTTP/1.1
    Host:abcd1234.us-west-2.amazonaws.com
    Content-type: application/json
    
  {
    "id": 1,
    "type": "dog",
    "Age": 11,
  }
```

此请求正文的格式不适合集成端点使用，因此 API Gateway 执行映射模板转换。API Gateway 仅执行映射模板转换，因为已为 Content-Type `application/json` 定义了映射模板。如果您没有为 Content-Type 定义映射模板，则默认情况下，API Gateway 会通过集成请求将正文传递到集成端点。要修改此行为，请参阅 [API Gateway 中适用于 REST API 且无映射模板的有效载荷的方法请求行为](integration-passthrough-behaviors.md)。

以下映射模板先转换集成请求中的方法请求数据，然后将数据发送到集成端点：

```
#set($inputRoot = $input.path('$'))
  {
    "dogId" : "dog_"$elem.id,
    "Age": $inputRoot.Age
  }
```

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

1. `dog` 是用户的 `id` 和字符串值的串联。

1. `Age` 来自方法请求正文。

然后，将以下输出转发到集成端点：

```
{
    "dogId" : "dog_1",
    "Age": 11
  }
```

## 集成响应和方法响应
<a name="models-mappings-response"></a>

成功请求集成端点后，端点会向 API Gateway 的集成响应发送响应。以下是来自集成端点的示例输出数据：

```
{
    "dogId" : "dog_1",
    "adoptionFee": 19.95,
}
```

方法响应预期的有效载荷与集成响应返回的有效载荷不同。API Gateway 执行映射模板转换。API Gateway 仅执行映射模板转换，因为已为 Content-Type `application/json` 定义了映射模板。如果您没有为 Content-Type 定义映射模板，则默认情况下，API Gateway 会通过对方法响应的集成响应传递正文。要修改此行为，请参阅 [API Gateway 中适用于 REST API 且无映射模板的有效载荷的方法请求行为](integration-passthrough-behaviors.md)。

```
#set($inputRoot = $input.path('$'))
  {
    "adoptionFee" : $inputRoot.adoptionFee,
  }
```

以下输出发送到方法响应：

```
{"adoptionFee": 19.95}
```

这就完成了示例映射模板转换。我们建议尽可能使用代理集成来转换数据，而不是使用映射模板转换。有关更多信息，请参阅 [选择 API Gateway API 集成类型](api-gateway-api-integration-types.md)。