マッピングテンプレートについて - Amazon API Gateway

マッピングテンプレートについて

API Gateway では、API のメソッドリクエストまたはレスポンスは、統合リクエストまたはレスポンスとは異なる形式のペイロードを受け取ることができます。

データを次のように変換できます。

  • ペイロードを API 指定の形式に一致させます。

  • API のリクエストおよびレスポンスパラメータとステータスコードを上書きします。

  • クライアントが選択したレスポンスヘッダーを返します。

  • HTTP プロキシまたは AWS のサービスプロキシのメソッドリクエストにパスパラメータ、クエリ文字列パラメータ、またはヘッダーパラメータを関連付けます。

  • Amazon DynamoDB や Lambda 関数などの AWS のサービス、または HTTP エンドポイントとの統合を使用して送信するデータを選択します。

データを変換するには、マッピングテンプレートを使用できます。マッピングテンプレートは、Velocity Template Language (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. description は、元の 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 Template Language の詳細については、「Apache Velocity - VTL Reference」を参照してください。JSONPath の詳細については、「JSONPath - XPath for JSON」を参照してください。

マッピングテンプレートでは、基盤となるデータが JSON オブジェクトであることを前提としています。データのモデルを定義する必要はありません。ただし、出力データのモデルを使用すると、先行データを言語固有のオブジェクトとして返すことができます。詳細については、「データモデルを理解する」を参照してください。

複雑なマッピングテンプレート

また、より複雑なマッピングテンプレートを作成することもできます。次の例は、参照の連結と 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 } ]

より複雑なモデルについては、フォトアルバムの例「写真の例」を参照してください。