REST API のマッピングテンプレート
API Gateway では、API のメソッドリクエストまたはレスポンスは、統合リクエストまたはレスポンスとは異なる形式のペイロードを受け取ることができます。
データを次のように変換できます。
ペイロードを API 指定の形式に一致させます。
API のリクエストおよびレスポンスパラメータとステータスコードを上書きします。
クライアントが選択したレスポンスヘッダーを返します。
HTTP プロキシまたは AWS サービスプロキシのメソッドリクエストにパスパラメータ、クエリ文字列パラメータ、またはヘッダーパラメータを関連付けます。
Amazon DynamoDB や Lambda 関数などの AWS サービス、または HTTP エンドポイントとの統合を使用して送信するデータを選択します。
データを変換するには、マッピングテンプレートを使用できます。マッピングテンプレートは、Velocity Template Language (VTL)
このセクションでは、マッピングテンプレートに関連する概念的な情報を説明します。API Gateway REST API のマッピングテンプレートを作成する手順については、「API Gateway でのデータ変換の設定」を参照してください。
マッピングテンプレートの例
次の例は、統合リクエストへの入力データです。
[ { "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 } ]
次の図は、このマッピングテンプレートの詳細を示しています。
![マッピングテンプレートの例](images/map-03-17.png)
$inputRoot
変数は、前のセクションにおける元の JSON データのルートオブジェクトです。ディレクティブは#
記号で始まります。foreach
ループは、元の JSON データ内の各オブジェクトを反復処理します。description は、元の JSON データからのペットの
id
とtype
を連結したものです。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 行目で、
$inputRoot
変数は前のセクションからの元の JSON データのルートオブジェクトを表します。ディレクティブは#
記号で始まります。 -
3 行目で、
foreach
ループは元の JSON データ内の各オブジェクトを反復処理します。 -
5 行目で、
description
は、元の JSON データからのペットのid
とtype
を連結したものです。 -
6 行目で、
askingPrice
は元の JSON データからの価格を示すprice
です。
Velocity Template Language の詳細については、「Apache Velocity - VTL Reference
マッピングテンプレートでは、基盤となるデータが JSON オブジェクトであることを前提としています。データのモデルを定義する必要はありません。ただし、出力データのモデルを使用すると、先行データを言語固有のオブジェクトとして返すことができます。詳細については、「REST API のデータモデル」を参照してください。
複雑なマッピングテンプレートの例
また、より複雑なマッピングテンプレートを作成することもできます。次の例は、参照の連結と 100 のカットオフを使用して、ペットが手頃な価格かどうかを判断する方法を示しています。
次の例は、統合リクエストへの入力データです。
[ { "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('$')) #set($cheap = 100) [ #foreach($elem in $inputRoot) { #set($name = "${elem.type}number$elem.id") "name" : $name, "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 ]
次の例は、変換からの出力データです。
[ { "name" : dognumber1, "description" : "Item 1 is a dog.", "askingPrice" : too much! }, { "name" : catnumber2, "description" : "Item 2 is a cat.", "askingPrice" : too much! }, { "name" : fishnumber3, "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ]
また、より複雑なデータモデルを表示することもできます。「API Gateway のデータモデルとマッピングテンプレートの例」を参照してください。