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

# 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_tw/apigateway/latest/developerguide/images/how-to-validate-requests.png)


在這個模型中：

1. `$schema` 物件代表有效的 JSON 結構描述版本識別符。此結構描述為 JSON 結構描述草稿第 4 版。

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 結構描述草稿第 4 版。

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)。