英語の翻訳が提供されている場合で、内容が矛盾する場合には、英語版がオリジナルとして取り扱われます。翻訳は機械翻訳により提供されています。
REST API のデータ変換の設定
API Gateway では、API のメソッドリクエストは、バックエンドで必要となる、該当する統合リクエストペイロードとは異なる形式のペイロードを受け取ることができます。同様に、バックエンドは、フロントエンドで予期されるメソッドレスポンスペイロードとは異なる統合レスポンスペイロードを返す場合があります。API Gateway では、マッピングテンプレートを使用して、ペイロードをメソッドリクエストから該当する統合リクエストにマッピングしたり、統合レスポンスから該当するメソッドレスポンスにマッピングしたりできます。
マッピングテンプレートは、Velocity Template Language (VTL)
ペイロードでは、JSON スキーマのドラフト 4
このセクションでは、モデルとマッピングテンプレートを使用して、API リクエストとレスポンスペイロードをマッピングする方法を説明します。
モデル
API Gateway では、モデルはペイロードのデータ構造を定義します。API Gateway では、JSON スキーマのドラフト 4
次の JSON オブジェクトは、よくあるスーパーマーケットの青果部門の果物または野菜の在庫を記述したサンプルデータを示しています。
スーパーマーケットの青果部門で果物と野菜の在庫を管理するための API があるとします。マネージャーからバックエンドに現在の在庫についての問い合わせがあると、サーバーは次のレスポンスペイロードを送り返します。
{ "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 つの文字列 (fruitとvegetables) の配列です。 -
binsプロパティは、category、type、price、unit、およびquantityの文字列または数値プロパティを持つオブジェクトの配列です。
上記のデータのモデルを定義するには、次の JSON スキーマを使用できます。
{ "$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 データのルートオブジェクトには、
department、categories、binsプロパティが格納されます。 -
departmentプロパティは JSON データの文字列オブジェクトです。 -
categoriesプロパティは JSON データの配列です。この配列には、JSON データの文字列値が格納されます。 -
binsプロパティは JSON データの配列です。この配列には、JSON データのオブジェクトが格納されます。JSON データのこれらの各オブジェクトには、category文字列、type文字列、price数値、unit文字列、quantity整数 (小数部または指数部のない数字) が格納されます。
または、このスキーマの一部 (bins 配列の項目の定義など) を同じファイルの別のセクションに含めて、$ref プリミティブを使用して、スキーマの他の部分でこの再利用可能な定義を参照することができます。$ref を使用すると、上記のモデル定義ファイルを次のように表現できます。
{ "$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 セクションには、Bin 配列で bins で参照される "$ref": "#/definitions/Bin" 項目のスキーマ定義を含めることができます。このようにして再利用可能な定義を使用すると、モデル定義は読みやすくなります。
さらに、そのモデルの URL を $ref プロパティの値 "$ref":
"https://apigateway.amazonaws.com/restapis/{restapi_id}/models/{model_name}" として設定することで、外部モデルファイルで定義された別のモデルスキーマを参照することもできます。たとえば、ID fugvjdxtri を使って API で作成された、Bin という名前の次の本格的なモデルがあるとします。
{ "$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 から、これを参照できます。
{ "$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 スキーマのアドバンスト機能は使用していません。詳細については、「JSON のご紹介
より複雑な JSON データの形式とそれらのモデルについては、以下の例を参照してください。
API Gateway でモデルを試すには、「レスポンスペイロードをマッピングする」の手順 (特に「ステップ1: モデルを作成する」) に従ってください。
マッピングテンプレート
バックエンドから返されるクエリ結果 (モデル セクション) は、次のように表示されると青果部門のマネージャーに役立つと思われます。
{ "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 } ] }
これを有効にするには、データをバックエンド形式から変換するマッピングテンプレートを API Gateway に提供する必要があります。それを行うのは次のマッピングテンプレートです。
#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 データのtype配列内のオブジェクトごとのvalueオブジェクトとbinsオブジェクトの対応する値からそれぞれマッピングされます。 -
出力マッピングテンプレートの
choicesオブジェクト内のオブジェクトごとに、suggestedPriceオブジェクトの値は、元の JSON データのオブジェクトごとのpriceオブジェクトとunitオブジェクトのそれぞれ対応する値の連結であり、各値はperという単語で区切られます。
Velocity Template Language の詳細については、「Apache Velocity - VTL Reference
マッピングテンプレートでは、基盤となるデータが JSON オブジェクトであることを前提としています。データのモデルを定義する必要はありません。API 開発者は、フロントエンドとバックエンドの両方のデータ形式を知っています。その知識があれば、形式を混同することはなく、必要なマッピングを定義できます。
API 用の SDK を生成するために、上記のデータが言語固有のオブジェクトとして返されます。Java、Objective-C、Swift などの厳密に型指定された言語では、オブジェクトはユーザー定義データ型 (UDT) に対応します。API Gateway にデータモデルを提供すると、このような UDT が作成されます。上記のメソッドレスポンス例では、統合レスポンスで次のペイロードモデルを定義できます。
{ "$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整数 (小数部または指数部のない数字) が格納されます。
このモデルでは、SDK を呼び出して kind、suggestedPrice、および available の各プロパティを読み取ることで、GroceryStoreOutputModel[i].kind、GroceryStoreOutputModel[i].suggestedPrice、および GroceryStoreOutputModel[i].available の各プロパティ値を取得できます。モデルが指定されていない場合、API Gateway は空のモデルを使用してデフォルト UDT を作成します。この場合、厳密に型指定された
SDK を使用して、これらのプロパティを読み取ることはできません。
より複雑なマッピングテンプレートを試すには、以下の例を参照してください。
API Gateway でマッピングテンプレートを試すには、「レスポンスペイロードをマッピングする」の手順 (特に「ステップ 5: メソッドをセットアップしてテストする」) に従ってください。
次のステップ
モデルとマッピングテンプレートで行えるその他の作業については、以下を参照してください。
