REST API のマッピングテンプレート - Amazon API Gateway
マッピングテンプレートの例複雑なマッピングテンプレートの例

REST API のマッピングテンプレート

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

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

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

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

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

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

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

データを変換するには、マッピングテンプレートを使用できます。マッピングテンプレートは、Velocity Template Language (VTL) で表現されるスクリプトであり、JSONPath を使用してペイロードに適用されます。

このセクションでは、マッピングテンプレートに関連する概念的な情報を説明します。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
  }
]

次の図は、このマッピングテンプレートの詳細を示しています。

マッピングテンプレートの例

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