针对 REST API 的数据模型 - Amazon API Gateway

针对 REST API 的数据模型

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

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

数据包含宠物的 idtypeprice。这些数据的模型允许您:

  • 使用基本请求验证。

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

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

PetStore API 的示例 JSON 数据模型。

在这个模型中:

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

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

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

  4. 模型的 propertiesidtypeprice。每个对象都有模型中描述的属性。

  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 a1234PetStorePrice 模型中定义的。

{ "$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].descriptionPetStoreOutputModel[i].askingPrice 属性来检索 descriptionaskingPrice 属性值。如果未提供模型,API Gateway 将使用空模型创建默认 UDT。

后续步骤