データモデルを理解する - Amazon API Gateway

データモデルを理解する

API Gateway では、モデルはペイロードのデータ構造を定義します。API Gateway では、JSON スキーマのドラフト 4 を使用してモデルを定義します。次の JSON オブジェクトは、PetStore の例のサンプルデータです。

{ "id": 1, "type": "dog", "price": 249.99 }

データには、ペットの idtypeprice が含まれています。このデータのモデルにより、以下のことが可能になります。

  • 基本的なリクエストの検証を使用する。

  • データ変換用のマッピングテンプレートを作成する。

  • SDK を生成するときに、ユーザー定義データ型 (UDT) を作成する。


          JSON データの例

このモデルの内容は以下のとおりです。

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

  2. title オブジェクトは、人間が読めるモデルの識別子です。このタイトルは PetStoreModel です。

  3. required 検証キーワードには、基本的なリクエストの検証用の type と price が必要です。

  4. モデルの properties は、idtypeprice です。各オブジェクトには、モデルに記述されているプロパティがあります。

  5. オブジェクト type は、値として dogcatfish のいずれかのみを持つことができます。

  6. オブジェクト price は数値で、minimum が 25、maximum が 500 に制限されます。

1 { 2 "$schema": "http://json-schema.org/draft-04/schema#", 3 "title": "PetStoreModel", 4 "type" : "object", 5 "required" : [ "price", "type" ], 6 "properties" : { 7 "id" : { 8 "type" : "integer" 9 }, 10 "type" : { 11 "type" : "string", 12 "enum" : [ "dog", "cat", "fish" ] 13 }, 14 "price" : { 15 "type" : "number", 16 "minimum" : 25.0, 17 "maximum" : 500.0 18 } 19 } 20 }

このモデルの内容は以下のとおりです。

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

  2. 3 行目で、title オブジェクトは、人間が読めるモデルの識別子です。このタイトルは PetStoreModel です。

  3. 5 行目で、required 検証キーワードには、基本的なリクエストの検証用の typeprice が必要です。

  4. 6~17 行目で、モデルの propertiesidtypeprice です。各オブジェクトには、モデルに記述されているプロパティがあります。

  5. 12 行目で、オブジェクト type は値として dogcatfish のいずれかのみを持つことができます。

  6. 14~17 行目で、オブジェクト price は数値で、minimum が 25、maximum が 500 に制限されます。

より複雑なモデルの作成

$ref プリミティブを使用すると、より長いモデルの再利用可能な定義を作成できます。例えば、price オブジェクトを記述する definitions セクションで、Price という定義を作成できます。$ref の値は Price 定義です。

{ "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "PetStoreModelReUsableRef", "required" : ["price", "type" ], "type" : "object", "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "price" : { "$ref": "#/definitions/Price" } }, "definitions" : { "Price": { "type" : "number", "minimum" : 25.0, "maximum" : 500.0 } } }

外部モデルファイルで定義された別のモデルスキーマを参照することもできます。$ref プロパティの値をモデルの場所に設定します。次の例では、Price モデルは API a1234 の PetStorePrice モデルに定義されています。

{ "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "PetStorePrice", "type": "number", "minimum": 25, "maximum": 500 }

より長いモデルは PetStorePrice モデルを参照できます。

{ "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "PetStoreModelReusableRefAPI", "required" : [ "price", "type" ], "type" : "object", "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "price" : { "$ref": "https://apigateway.amazonaws.com/restapis/a1234/models/PetStorePrice" } } }

出力データモデルを使用する

データを変換する場合、統合レスポンスでペイロードモデルを定義できます。ペイロードモデルは SDK を生成するときに使用できます。Java、Objective-C、Swift などの厳密に型指定された言語では、オブジェクトはユーザー定義データ型 (UDT) に対応します。SDK の生成時にデータモデルで UDT を指定すると、API Gateway は UDT を作成します。データ変換の詳細については、「マッピングテンプレートについて」を参照してください。

出力データ
{ [ { "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 } ] }
出力モデル
{ "$schema": "http://json-schema.org/draft-04/schema#", "title": ”PetStoreOutputModel", "type" : "object", "required" : [ "description", "askingPrice" ], "properties" : { "description" : { "type" : "string" }, "askingPrice" : { "type" : "number", "minimum" : 25.0, "maximum" : 500.0 } } }

このモデルでは、SDK を呼び出し、PetStoreOutputModel[i].description プロパティと PetStoreOutputModel[i].askingPrice プロパティを読み取ることで、description と askingPrice のプロパティ値を取得できます。モデルが指定されていない場合、API Gateway は空のモデルを使用してデフォルト UDT を作成します。

次のステップ