# API Gateway での REST API のテンプレート変換のマッピング
<a name="models-mappings"></a>

マッピングテンプレート変換では、統合リクエストまたは統合レスポンスの変更にマッピングテンプレートを使用します。*マッピングテンプレート*は、[Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) で表現されるスクリプトであり、`Content-type` ヘッダーに基づいて [JSONPath](https://goessner.net/articles/JsonPath/) を使用してペイロードに適用されます。マッピングテンプレート変換を使用する場合は、マッピングテンプレートを使います。このセクションでは、マッピングテンプレートに関連する概念的な情報を説明します。

次の図は、PetStore 統合エンドポイントと統合されている `POST /pets` リソースのリクエストライフサイクルを説明しています。この API では、ユーザーはペットに関するデータを送信し、統合エンドポイントはペットの譲渡料金を返します。このリクエストライフサイクルでは、マッピングテンプレート変換が、リクエスト本文を統合エンドポイントにフィルタリングして、統合エンドポイントからレスポンス本文をフィルタリングします。

![リクエストライフサイクルの例](http://docs.aws.amazon.com/ja_jp/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)」を参照してください。