# 针对 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 对象是 Pet Store 示例中的示例数据。

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

数据包含宠物的 `id`、`type` 和 `price`。这些数据的模型允许您：
+ 使用基本请求验证。
+ 创建用于数据转换的映射模板。
+ 生成 SDK 时创建用户定义的数据类型（UDT）。

![\[PetStore API 的示例 JSON 数据模型。\]](http://docs.aws.amazon.com/zh_cn/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 时向其提供数据模型，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)。