メニュー
Amazon API Gateway
開発者ガイド

リクエストおよびレスポンスマッピングのモデルおよびマッピングテンプレートを作成する

API Gateway では、API のメソッドリクエストは、バックエンドで必要となる、該当する統合リクエストペイロードとは異なる形式のペイロードを受け取ることができます。同様に、バックエンドは、フロントエンドで予期されるメソッドレスポンスペイロードとは異なる統合レスポンスペイロードを返す場合があります。API Gateway では、ペイロードをメソッドリクエストから該当する統合リクエストにマッピングしたり、統合レスポンスから該当するメソッドレスポンスにマッピングしたりできます。マッピングテンプレートを使用してマッピングを指定し、モデルを作成してテンプレート生成を容易にすることができます。このセクションでは、モデルとマッピングテンプレートを使用して、API リクエストとレスポンスペイロードをマッピングする方法を説明します。

モデル

API Gateway では、モデルは、ペイロードの構造または形状 (ペイロードのスキーマとも呼ばれる) を定義します。API Gateway では、JSON スキーマを使用して JSON ペイロードのモデルを表す必要があります。

API Gateway は、マッピングテンプレートに従ってペイロードをマッピングします。モデルはテンプレートを生成するために役立ちますが、必須ではありません。ただし、API の厳密に型指定された SDK を生成するためにはモデルが必要です。モデルはペイロードの検証にも役立ちます。

次の JSON オブジェクトは、よくあるスーパーマーケットの青果部門の果物または野菜の在庫について記述したサンプルデータを示しています。

Copy
{ "department": "produce", "categories": [ "fruit", "vegetables" ], "bins": [ { "category": "fruit", "type": "apples", "price": 1.99, "unit": "pound", "quantity": 232 }, { "category": "fruit", "type": "bananas", "price": 0.19, "unit": "each", "quantity": 112 }, { "category": "vegetables", "type": "carrots", "price": 1.29, "unit": "bag", "quantity": 57 } ] }

JSON オブジェクトには、3 つのプロパティがあります。

  • department プロパティは文字列値 (produce) を持ちます。

  • categories プロパティは、2 つの文字列 (fruitvegetables) の配列です。

  • bins プロパティはオブジェクトの配列です。各オブジェクトが文字列値または数値のプロパティ (categorytypepriceunitquantity) を持ちます。

以下の JSON スキーマ表記は対応するモデルを示しています。

Copy
{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "GroceryStoreInputModel", "type": "object", "properties": { "department": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "bins": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "type": { "type": "string" }, "price": { "type": "number" }, "unit": { "type": "string" }, "quantity": { "type": "integer" } } } } } }

前の例では、以下のようになっています。

  • $schema オブジェクトは、有効な JSON スキーマのバージョン識別子を表します。この例では、JSON スキーマのドラフト v4 を表します。

  • title オブジェクトは、人間が読めるモデルの識別子です。この例では、GroceryStoreInputModel です。

  • JSON データのトップレベル (ルート) 構造体はオブジェクトです。

  • JSON データのルートオブジェクトには、departmentcategoriesbins プロパティが格納されます。

  • department プロパティは JSON データの文字列オブジェクトです。

  • categories プロパティは JSON データの配列です。この配列には、JSON データの文字列値が格納されます。

  • bins プロパティは JSON データの配列です。この配列には、JSON データのオブジェクトが格納されます。JSON データのこれらの各オブジェクトには、category 文字列、type 文字列、price 数値、unit 文字列、quantity 整数 (小数部または指数部のない数字) が格納されます。

または、このスキーマの一部 (bins 配列の項目の定義など) を同じファイルの別のセクションに含め、$ref プリミティブを使用して、スキーマの他の部分でこの再利用可能な定義を参照することができます。$ref を使用して、上記のモデル定義ファイルを次のように表現できます。

Copy
{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "GroceryStoreInputModel", "type": "object", "properties": { "department": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "bins": { "type": "array", "items": { "$ref": "#/definitions/Bin" } } }, "definitions": { "Bin" : { "type": "object", "properties": { "category": { "type": "string" }, "type": { "type": "string" }, "price": { "type": "number" }, "unit": { "type": "string" }, "quantity": { "type": "integer" } } } } }

definitions セクションには、bins 配列で "ref": "#/definitions/Bin" で参照される Bin 項目のスキーマ定義を含めることができます。このようにして再利用可能な定義を使用すると、モデル定義は読みやすくなります。

さらに、そのモデルの URL を $ref プロパティの値 "$ref": "https://apigateway.amazonaws.com/restapis/{restapi_id}/models/{model_name}" として設定することで、外部モデルファイルで定義された別のモデルスキーマを参照することもできます。たとえば、ID fugvjdxtri を使って API で作成された、Bin2 という名前の次の本格的なモデルがあるとします。

Copy
{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "GroceryStoreInputModel", "type": "object", "properties": { "Bin" : { "type": "object", "properties": { "category": { "type": "string" }, "type": { "type": "string" }, "price": { "type": "number" }, "unit": { "type": "string" }, "quantity": { "type": "integer" } } } } }

次に示すように、同じ API の GroceryStoreInputModel から、これを参照できます。

Copy
{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "GroceryStoreInputModel", "type": "object", "properties": { "department": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "bins": { "type": "array", "items": { "$ref": "https://apigateway.amazonaws.com/restapis/fugvjdxtri/models/Bin2" } } } }

参照元および参照先モデルは、同じ API からのものである必要があります。

この例では、必須項目を指定したり、文字列、数値、配列項目の最大および最小許容長を指定したり、正規表現を使用したりするような、JSON スキーマの高度な機能は使用していません。詳細については、「Introducing JSON」と「JSON Schema」を参照してください。

より複雑な JSON データの形式とそれらのモデルについては、以下の例を参照してください。

API Gateway でモデルを試すには、「レスポンスペイロードをマッピングする」の「ステップ1: モデルを作成する」の手順に従ってください。

マッピングテンプレート

API Gateway では、一部のデータの形式を変換する目的でマッピングテンプレートが使用されます。 呼び出し元から送られるか呼び出し元に返されるデータのスキーマについて API Gateway に通知する必要がある場合は、入力マッピングテンプレートと出力マッピングテンプレートをそれぞれ使用します。API Gateway では、Velocity Template Language (VTL)JSONPath 表現を使用して、マッピングテンプレートを定義します。

入力マッピングテンプレートの例について、前のセクションの JSON データの例で考えます。以下の入力マッピングテンプレートでは、API Gateway が呼び出し元から JSON データを受け取るときに、JSON データを変換しません。

Copy
#set($inputRoot = $input.path('$')) { "department": "$inputRoot.department", "categories": [ #foreach($elem in $inputRoot.categories) "$elem"#if($foreach.hasNext),#end #end ], "bins" : [ #foreach($elem in $inputRoot.bins) { "category" : "$elem.category", "type" : "$elem.type", "price" : $elem.price, "unit" : "$elem.unit", "quantity" : $elem.quantity }#if($foreach.hasNext),#end #end ] }

前の例では、入力マッピングテンプレートは以下のように表現されています。

  • 入力マッピングテンプレートの $inputRoot 変数は、元の JSON データのルートオブジェクトを表します。

  • 入力マッピングテンプレートの department オブジェクト、categories 配列、bins 配列の値 ($inputRoot.department$inputRoot.categories$inputRoot.bins によって表現) は、元の JSON データのルートオブジェクト内の対応する department オブジェクト、categories 配列、bins 配列の値にマッピングされます。

  • 入力マッピングテンプレートの categories 配列の各値 (最初の $elem で表現) と、bins 配列の各オブジェクト (2 番目の $elem で表現) は、元の JSON データのルートオブジェクト内の対応する categories 配列の値と bins 配列のオブジェクトにそれぞれマッピングされます。

  • 入力マッピングテンプレートの bins オブジェクト内のオブジェクトごとに、categorytypepriceunitquantity オブジェクトの値 ($elem.category$elem.type$elem.price$elem.unit$elem.quantity によってそれぞれ表現) は、元の JSON データの対応する categorytypepriceunitquantity オブジェクトの値にそれぞれマッピングされます。

出力マッピングテンプレートの例について、まず、前のセクションの JSON データの例に基づいた以下の JSON データスキーマで考えます。

注記

この JSON データスキーマの配列とオブジェクトの名前はいずれも前のセクションの JSON データスキーマには一致しません。

Copy
{ "choices": [ { "kind": "apples", "suggestedPrice": "1.99 per pound", "available": 232 }, { "kind": "bananas", "suggestedPrice": "0.19 per each", "available": 112 }, { "kind": "carrots", "suggestedPrice": "1.29 per bag", "available": 57 } ] }

前のセクションの JSON データの例をこの JSON データスキーマに変換するには、以下のモデルを使用します。

Copy
{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "GroceryStoreOutputModel", "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "suggestedPrice": { "type": "string" }, "available": { "type": "integer" } } } } } }

前の例では、JSON スキーマは以下のように表現されています。

  • $schema オブジェクトは、有効な JSON スキーマのバージョン識別子を表します。この例では、JSON スキーマのドラフト v4 を表します。

  • title オブジェクトは、人間が読めるモデルの識別子です。この例では、GroceryStoreOutputModel です。

  • JSON データのトップレベル (ルート) 構造体はオブジェクトです。

  • JSON データのルートオブジェクトには、オブジェクトの配列が格納されます。

  • このオブジェクトの配列内の各オブジェクトには、kind 文字列、suggestedPrice 文字列、available 整数 (小数部または指数部のない数字) が格納されます。

このモデルに基づいた以下の出力マッピングテンプレートを使用します。

Copy
#set($inputRoot = $input.path('$')) { "choices": [ #foreach($elem in $inputRoot.bins) { "kind": "$elem.type", "suggestedPrice": "$elem.price per $elem.unit", "available": $elem.quantity }#if($foreach.hasNext),#end #end ] }

前の例では、出力マッピングテンプレートは以下のように表現されています。

  • 出力マッピングテンプレートの $inputRoot 変数は、前のセクションからの元の JSON データのルートオブジェクトを表します。出力マッピングテンプレートの変数は、変換後の JSON データスキーマではなく、元の JSON データにマッピングされています。

  • 出力マッピングテンプレートの choices 配列は、元の JSON データのルートオブジェクト内の bins 配列 ($inputRoot.bins) にマッピングされます。

  • 入力マッピングテンプレートの choices 配列の各オブジェクト ($elem によって表現) は、元の JSON データのルートオブジェクト内の bins 配列の対応するオブジェクトにマッピングされます。

  • 出力マッピングテンプレートの choices オブジェクト内のオブジェクトごとに、kind オブジェクトと available オブジェクトの値 ($elem.type$elem.quantity によって表現) は、元の JSON データの bins 配列内のオブジェクトごとに、type オブジェクトと value オブジェクトの対応する値にそれぞれマッピングされます。

  • 出力マッピングテンプレートの choices オブジェクト内のオブジェクトごとに、suggestedPrice オブジェクトの値は、元の JSON データのオブジェクトごとに、price オブジェクトと unit オブジェクトの対応する値にそれぞれ連結されて、各値は per という単語で区切られます。

Velocity Template Language の詳細については、「Apache Velocity - VTL Reference」を参照してください。JSONPath の詳細については、「JSONPath - XPath for JSON」を参照してください。

より複雑なマッピングテンプレートを試すには、以下の例を参照してください。

API Gateway でマッピングテンプレートを試すには、「レスポンスペイロードをマッピングする」の「ステップ 5: メソッドをセットアップし、テストする」の手順に従ってください。

モデルとマッピングテンプレートでの作業

モデルとマッピングテンプレートで行えるその他の作業については、以下を参照してください。