# REST API のデータモデル
<a name="models-mappings-models"></a>

API Gateway では、モデルはペイロードのデータ構造を定義します。API Gateway では、[JSON スキーマのドラフト 4](https://tools.ietf.org/html/draft-zyp-json-schema-04) を使用してモデルを定義します。次の JSON オブジェクトは、PetStore の例のサンプルデータです。

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

データには、ペットの `id`、`type`、`price` が含まれています。このデータのモデルにより、以下のことが可能になります。
+ 基本的なリクエストの検証を使用する。
+ データ変換用のマッピングテンプレートを作成する。
+ SDK を生成するときに、ユーザー定義データ型 (UDT) を作成する。

![\[PetStore API の JSON データモデルの例。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/how-to-validate-requests.png)


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

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

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

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

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

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

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

## PetStore モデル
<a name="PetStore-model-text"></a>

```
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 です。

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

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

1.  6～17 行目で、モデルの `properties` は `id`、`type`、`price` です。各オブジェクトには、モデルに記述されているプロパティがあります。

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

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

## より複雑なモデルの作成
<a name="api-gateway-request-validation-model-more-complex"></a>

 `$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"
    }
  }
}
```

## 出力データモデルを使用する
<a name="api-gateway-request-validation-output-model"></a>

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

以下は、統合レスポンスからの出力データの例です。

```
{
[
  {
    "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 を作成します。

## 次のステップ
<a name="api-gateway-request-validation-model-next-steps"></a>
+ このセクションでは、このトピックで紹介した概念について理解を深めるために役立つリソースを紹介します。

  以下のリクエストの検証チュートリアルを参考にしてください。
  + [API Gateway コンソールを使用してリクエストの検証を設定する](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-in-console)
  +  [AWS CLI を使用して基本的なリクエストの検証を設定する](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-cli)
  +  [OpenAPI 定義を使用して基本的なリクエストの検証を設定する](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-importing-swagger)
+  データ変換とマッピングテンプレートの詳細については、「[API Gateway での REST API のテンプレート変換のマッピング](models-mappings.md)」を参照してください。