資料模型 REST APIs - Amazon API Gateway
建立更複雜的模型使用輸出資料模型後續步驟

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

資料模型 REST APIs

在API網關中，模型定義有效負載的數據結構。在API閘道中，模型是使用JSON架構草稿 4 定義的。以下JSON物件是寵物店範例中的範例資料。

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

資料包含寵物的 id、type 和 price。此資料的模型可讓您：

  • 使用基本請求驗證。

  • 建立對應範本進行資料轉換。

  • 產生一個使用者定義的資料類型 (UDT) SDK。

的範例JSON資料模型 PetStore API。

在這個模型中：

  1. $schema物件代表有效的 JSON Schema 版本識別元。該模式是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 Schema 版本識別元。該模式是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模型在中的PetStorePrice模型中定義APIa1234。

{
  "$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 或斯威夫特，對象對應於一個用戶定義的數據類型（）UDT。APIUDT如果您在產生資料模型時提供資料模型，Gateway 會建立SDK。如需資料轉型的詳細資訊，請參閱 的映射範本 REST APIs。

下列範例是整合回應的輸出資料。

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

使用此模型時，您可以呼叫以讀取description和askingPrice屬性SDK來擷取PetStoreOutputModel[i].description和PetStoreOutputModel[i].askingPrice屬性值。如果未提供模型，APIGateway 會使用空白模型建立預設模型UDT。

後續步驟