如何在 API Gateway 中將資料模型與我的 REST API 建立關聯？

解決方法

若要在 API Gateway 中將資料模型與 REST API 建立關聯，請完成以下步驟。

撰寫要與 REST API 建立關聯的模型結構描述

**注意：**API Gateway 模型必須使用 JSON schema draft 4。如需如何撰寫模型結構描述的相關資訊，請參閱 REST API 的資料模型。

範例模型結構描述

此範例模型使用 application/json 作為選取對應範本的預設索引鍵。您的結構描述必須符合以下條件：

• API 使用者必須在請求主體中傳遞其 UserID 與 Name 值。
• UserID 與 Name 的值必須為字串值。
• Age 的值必須為 18 以上的整數值。

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User",
  "type": "object",
  "properties": {
    "UserID": {
      "type": "string"
    },
    "Name": {
      "type": "string"
    },
    "Age": {
      "description": "Age in years",
      "type": "integer",
      "minimum": 18
    }
  },
  "required": [
    "UserID",
    "Name"
  ]
}

為您的 REST API 建立模型

若要在 API Gateway 中建立模型，請參閱在 API Gateway 中設定基本請求驗證。

將您的模型與 API 方法建立關聯

請完成以下步驟：

1. 在 API Gateway 主控台中開啟您的 API。
2. 從導覽窗格中，選擇 Resources (資源)。
3. 選取您要與模型建立關聯的 API 方法。
4. 在 Method Execution (方法執行) 窗格中，選擇 Method Request (方法請求)。
5. 在 Request Validator (請求驗證器) 中，選取 Validate body (驗證主體)。然後，選擇核取圖示以儲存您的選擇。
6. 展開 Request Body (請求主體)。然後，選擇 Add model (新增模型)。
7. 在 Content type (內容類型) 中，輸入您模型的內容類型。例如，輸入 application/json。
8. 在 Model name (模型名稱) 中，選取您建立的模型。
9. 選擇核取圖示以儲存您的選擇。

測試模型

請完成以下步驟：

1. 從 API 的 Resources (資源) 清單中，選擇您與模型建立關聯的 API 方法。

2. 在 Method Execution (方法執行) 窗格中，選擇 TEST (測試)。

3. 在 Request Body (請求主體) 中，輸入符合您所建立模型結構描述的請求主體。
   **注意：**若要測試 application/json 範例模型，請使用以下範例請求主體：

   { "UserID": "abc123", "Name": "Ana", "Age": 21}

4. 選擇 Test (測試)。

5. 如果測試回應成功，則傳回的請求主體符合模型結構描述。

(選用) 為模型建立對應範本

您可以使用對應範本來修改傳送至 API 整合後端的請求。若要建立對應範本，請完成以下步驟：

1. 從 API 的 Resources (資源) 清單中，選擇您與模型建立關聯的 API 方法。

2. 在 Method Execution (方法執行) 窗格中，選擇 Integration Request (整合請求)。

3. 展開 Mapping Templates (對應範本)。

4. 在 Request body passthrough (請求主體直通傳遞) 中，選取 When there are no templates defined (recommended) (未定義範本時 (建議使用))。

5. 選擇 Add mapping template (新增對應範本)。

6. 在 Content-Type (內容類型) 中，輸入您模型的內容類型。例如，輸入 application/json。

7. 選擇核取圖示以儲存您的選擇。

8. 在 Generate template (產生範本) 中，選取您建立的模型。例如，application/json 範例模型會如下所示：

   #set($inputRoot = $input.path('$')) { "UserID" : "$inputRoot.UserID", "Name" : "$inputRoot.Name", "Age" : $inputRoot.Age }

9. 修改前述範本，使其包含您要傳遞至 API 整合後端的值。

10. 選擇 Save (儲存)。

部署您的 REST API 以提交變更

請完成以下步驟：

1. 從導覽窗格中，選擇 Resources (資源)。
2. 選擇 Actions (動作)。然後，選取 Deploy API (部署 API)。
3. 在 Deployment stage (部署階段) 中，選取現有階段，或選擇 [New Stage] ([新增階段]) 以建立階段。
   **重要：**如果您建立新的階段，則必須為 Stage name (階段名稱) 輸入名稱。
4. 選擇 Deploy (部署) 以取得 invoke URL (調用網址)，您可使用該網址對已部署的 API 發出請求。
5. 複製調用網址。

測試您的 REST API

傳送測試請求至您的 API，該請求需使用與模型建立關聯的方法與內容類型。成功的請求會傳回 200 OK 回應。失敗的請求會傳回 400 狀態碼。

若要傳送測試請求，請使用 API 開發工具或 curl 命令。如需 API Gateway 中 REST API 呼叫的詳細資訊，請參閱在 API Gateway 中調用 REST API。如需 curl 命令的詳細資訊，請參閱 curl 網站。

使用 POST HTTP 方法請求並測試 200 OK 回應的 curl 範例命令

**注意：**此範例命令會將測試請求傳送至範例 application/json 模型。該命令會傳回 200 OK 回應。

curl -X POST <API URL> -H 'Content-Type: application/json' -d '{ "UserID": "abc123", "Name": "Ana", "Age": 21 }'

(選用) 使用 POST HTTP 方法請求並測試 400 狀態碼的 curl 範例命令

**注意：**此範例命令中的請求主體無效，因其未包含必要的模型屬性 UserID。該命令會傳回 400 狀態碼。

curl -X POST <API URL> -H 'Content-Type: application/json' -d '{ "Name": "Ana", "Age": 21 }'