针对 REST API 的数据模型 - Amazon API Gateway
创建更复杂的模型使用输出数据模型后续步骤

针对 REST API 的数据模型

在 API Gateway 中，模型定义负载的数据结构。在 API Gateway 中，使用 JSON 架构草案 4 定义模型。以下 JSON 对象是 Pet Store 示例中的示例数据。

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

数据包含宠物的 id、type 和 price。这些数据的模型允许您：

  • 使用基本请求验证。

  • 创建用于数据转换的映射模板。

  • 生成 SDK 时创建用户定义的数据类型（UDT）。

PetStore API 的示例 JSON 数据模型。

在这个模型中：

  1. $schema 对象表示一个有效的 JSON 架构版本标识符。此架构为 JSON 架构草案 v4。

  2. title 对象是人类可读的模型标识符。此标题是 PetStoreModel。

  3. required 验证关键字要求使用 type 和 price 进行基本请求验证。

  4. 模型的 properties 为 id、type 和 price。每个对象都有模型中描述的属性。

  5. 对象 type 只能具有值 dog、cat 或 fish。

  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 验证关键字要求使用 type 和 price 进行基本请求验证。

  4. 在第 6 -- 17 行上，模型的 properties 为 id、type 和 price。每个对象都有模型中描述的属性。

  5. 在第 12 行上，对象 type 只能具有值 dog、cat 或 fish。

  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 时向其提供数据模型，API Gateway 将创建 UDT。有关数据转换的更多信息，请参阅针对 REST API 的映射模板。

以下示例是来自集成响应的输出数据。

{
[
  {
    "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。

后续步骤