本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# API Gateway 中 REST API 的映射範本轉換
<a name="models-mappings"></a>

映射範本轉換會使用映射範本來修改您的整合請求或整合回應。*映射範本*是以 [Velocity 範本語言 (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_tw/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)。