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

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

また、次の例のように、カットオフを使用してペットが手頃な価格かどうかを確認する、より複雑なマッピングテンプレートを作成することもできます。

入力データ 
[
  {
    "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.",
    #if($elem.price > $cheap )#set ($afford = 'too much!') #{else}#set ($afford = $elem.price)#end
"askingPrice" : $afford
  }#if($foreach.hasNext),#end

#end
]
出力データ 
[
  {
    "description" : "Item 1 is a dog.",
     "askingPrice" : too much!
  },
  {
    "description" : "Item 2 is a cat.",
     "askingPrice" : too much!
  },
  {
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }
]

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