本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 教學：建立具有 HTTP 非代理整合的 REST API
在本教學課程中，您會使用 Amazon API Gateway 主控台從頭開始建立 API。您可以將主控台視為 API 設計工作室，並使用它來限定 API 功能範圍、測試其行為、建立 API，以及分階段部署您的 API。
**Topics**
+ [建立具有 HTTP 自訂整合的 API](#api-gateway-create-resource-and-methods)
+ [(選用) 映射請求參數](#api-gateway-create-resources-and-methods-next-steps)
## 建立具有 HTTP 自訂整合的 API
本節將逐步引導您建立資源、在資源上公開方法、設定方法來達到所需的 API 行為，以及測試與部署 API。
在此步驟中，您將建立空白 API。在以下步驟中，您會建立資源和方法，以使用非代理 HTTP 整合將 API 連線到 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` 端點。
**建立 API**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 如果這是您第一次使用 API Gateway，您會看到服務功能的介紹頁面。在 **REST API** 下方，選擇 **Build (組建)**。當 **Create Example API (建立範例 API)** 快顯出現時，選擇 **OK (確定)**。
如果這不是第一次使用 API Gateway，請選擇 **Create API (建立 API)**。在 **REST API** 下方，選擇**組建**。
1. 對於**API 名稱**，輸入 **HTTPNonProxyAPI**。
1. 在**描述**，請輸入描述。
1. 將 **API 端點類型**保持設定為**區域**。
1. 針對 **IP 位址類型**，選擇 **IPv4**。
1. 選擇**建立 API**。
**Resources (資源)** 樹狀目錄顯示不含任何方法的根資源 (`/`)。在此練習中，我們將建立具有 PetStore 網站 (http://petstore-demo-endpoint.execute-api.com/petstore/pets) 之 HTTP 自訂整合的 API 為了方便說明，我們將建立 `/pets` 資源作為根目錄的子目錄，並在此資源上公開 GET 方法，讓用戶端可以從 PetStore 網站擷取可用的 Pets (寵物) 項目清單。
**建立 /pets 資源**
1. 選擇**建立資源**。
1. 讓**代理資源**保持關閉。
1. 將**資源路徑**保持為 `/`。
1. 針對**資源名稱**，輸入 **pets**。
1. 讓 **CORS (跨來源資源分享)** 保持關閉。
1. 選擇**建立資源**。
在此步驟中，您會在 **/pets** 資源上建立 `GET` 方法。`GET` 方法會與 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` 網站整合。API 方法的其他選項包括以下項目：
+ **POST**，主要用來建立子資源。
+ **PUT**，主要用來更新現有的資源 (也可用來建立子資源，但不建議)。
+ **DELETE**，用來刪除資源。
+ **PATCH**，用來更新資源。
+ **HEAD**，主要用來測試案例。它與 GET 相同，但不會傳回資源顯示方式。
+ **OPTIONS**，發起人可以使用它來取得目標服務之可用通訊選項的相關資訊。
對於整合請求的 **HTTP method (HTTP 方法)**，您必須選擇後端支援的方法。對於 `HTTP` 或 `Mock integration`，方法請求與整合請求最好使用相同的 HTTP 動詞。對於其他整合類型，方法請求可能會使用與整合請求不同的 HTTP 動詞。例如，若要呼叫 Lambda 函數，整合請求必須使用 `POST` 來叫用函數，而方法請求則可根據 Lambda 函數的邏輯來使用任何 HTTP 動詞。
**在 **/pets** 資源上建立 `GET` 方法**
1. 選取 **/pets** 資源。
1. 選擇**建立方法**。
1. 針對**方法類型**，選取 **GET**。
1. 針對**整合類型**，選取 **HTTP 整合**。
1. 讓 **HTTP 代理整合**保持關閉。
1. 針對 **HTTP 方法**，選取 **GET**。
1. 針對**端點 URL**，輸入 **http://petstore-demo-endpoint.execute-api.com/petstore/pets**。
PetStore 網站可讓您依指定頁面上的寵物類型 (例如 "Dog" 或 "Cat") 擷取 `Pet` 項目清單。
1. 針對**內容處理**，選取**傳遞**。
1. 選擇 **URL 查詢字串參數**。
PetStore 網站使用 `type` 與 `page` 查詢字串參數來接受輸入內容。您會將查詢字串參數新增至方法請求，然後將其映射至整合請求的映射查詢字串。
1. 若要將查詢字串參數，請執行下列操作：
1. 選擇**新增查詢字串**。
1. 對於**名稱**，輸入 **type**。
1. 將**必要**和**快取**保持關閉。
重複上述步驟，另外建立名稱為 **page** 的查詢字串。
1. 選擇**建立方法**。
用戶端現在可以在提交請求時，提供寵物類型與頁碼作為查詢字串參數。這些輸入參數必須映射到整合的查詢字串參數，以將輸入值轉送至後端的 PetStore 網站。
**將輸入參數映射至整合請求**
1. 在**整合請求**索引標籤上，於**整合請求設定**下，選擇**編輯**。
1. 選擇 **URL 查詢字串參數**，然後執行下列動作：
1. 選擇**新增查詢字串參數**。
1. 對於**名稱**，輸入 **type**。
1. 對於**映射自**，輸入 **method.request.querystring.type**。
1. 讓**快取**保持關閉。
1. 選擇**新增查詢字串參數**。
1. 對於**名稱**，輸入 **page**。
1. 對於**映射自**，輸入 **method.request.querystring.page**。
1. 讓**快取**保持關閉。
1. 選擇**儲存**。
**若要測試 API**
1. 選擇**測試**標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。
1. 針對**查詢字串**，輸入 **type=Dog&page=2**。
1. 選擇**測試**。
結果類似如下：
![\[測試呼叫 GET on Pets 方法結果\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/api-gateway-create-api-step-by-step-test-invoke-get-on-pets-result-new-console.png)
現在測試成功，我們可以部署 API 來公開提供使用。
1. 選擇**部署 API**。
1. 針對**階段**，選取**新階段**。
1. 針對**階段名稱**，輸入 **Prod**。
1. 在**描述**，請輸入描述。
1. 選擇**部署**。
1. (選用) 針對**階段詳細資訊**下的**調用 URL**，您可以選擇複製圖示以複製 API 的調用 URL。您可以使用此項與 [Postman](https://www.postman.com) 和 [cURL](https://curl.se/) 這類工具搭配，來測試您的 API。
如果您使用開發套件建立用戶端，您可以呼叫開發套件所公開的方法來簽署請求。如需實作詳細資訊，請參閱您選擇的 [AWS 軟體開發套件](https://aws.amazon.com/developer/tools/)。
**注意**
當您的 API 變更時，您必須重新部署 API，以提供新的或更新的功能，再重新呼叫請求 URL。
## (選用) 映射請求參數
### 對應 API Gateway API 的請求參數
本教學課程顯示如何在 API 的方法請求上建立 `{petId}` 的路徑參數，以指定項目 ID、將它映射至整合請求 URL 中的 `{id}` 路徑參數，然後將請求傳送到 HTTP 端點。
**注意**
如果您輸入大小寫錯誤的字母 (例如輸入小寫字母而非大寫字母)，這可能會在稍後的演練中造成錯誤。
#### 步驟 1：建立資源
在此步驟中，您會建立路徑參數為 \$1petId\$1 的資源。
**建立 \$1petId\$1 資源**
1. 選取 **/pets** 資源，然後選擇**建立資源**。
1. 讓**代理資源**保持關閉。
1. 針對**資源路徑**，選取 **/pets**。
1. 針對**資源名稱**，輸入 **\$1petId\$1**。
使用大括號 (`{ }`) 括住 `petId`，以便顯示 **/pets/\$1petId\$1**。
1. 讓 **CORS (跨來源資源分享)** 保持關閉。
1. 選擇**建立資源**。
#### 步驟 2：建立及測試方法
在此步驟中，您會建立路徑參數為 `{petId}` 的 `GET` 方法。
**設定 GET 方法**
1. 選取 **/\$1petId\$1** 資源，然後選擇**建立方法**。
1. 針對**方法類型**，選取 **GET**。
1. 針對**整合類型**，選取 **HTTP 整合**。
1. 讓 **HTTP 代理整合**保持關閉。
1. 針對 **HTTP 方法**，選取 **GET**。
1. 針對**端點 URL**，輸入 **http://petstore-demo-endpoint.execute-api.com/petstore/pets/\$1id\$1**。
1. 針對**內容處理**，選取**傳遞**。
1. 讓**預設逾時**保持開啟。
1. 選擇**建立方法**。
此時您將剛建立的 `{petId}` 路徑參數映射至整合請求之 HTTP 端點 URL 中的 `{id}` 路徑參數。HTTP 端點 URL 為 **http://petstore-demo-endpoint.execute-api.com/petstore/pets/\$1id\$1**。
**映射 `{petId}` 路徑參數**
1. 在**整合請求**索引標籤上，於**整合請求設定**下，選擇**編輯**。
1. 選擇 **URL 路徑參數**。
1. API Gateway 會為名為 **petId** 的整合請求建立路徑參數，但此路徑參數對於您設定為後端整合的 HTTP 端點 URL 無效。HTTP 端點會使用 `{id}` 作為路徑參數。針對**名稱**，刪除 **petId** 並輸入 **id**。
這會將 `petId` 的方法請求路徑參數對應到 `id` 的整合請求路徑參數。
1. 選擇**儲存**。
現在，請測試該方法。
**測試該方法**
1. 選擇**測試**標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。
1. 在 **petId** 的**路徑**下，輸入 **4**。
1. 選擇**測試**。
若成功，**回應內文**會顯示如下：
```
{
"id": 4,
"type": "bird",
"price": 999.99
}
```
#### 步驟 3：部署 API
在此步驟中，將會部署 API，如此您即開始從 API Gateway 主控台之外呼叫 API。
**部署 API**
1. 選擇**部署 API**。
1. 對於**階段**，選取**生產**。
1. 在**描述**，請輸入描述。
1. 選擇**部署**。
#### 步驟 4：測試 API
在此步驟中，您會在 API Gateway 主控台外使用您的 API 存取 HTTP 端點。
1. 在主導覽窗格中，選擇**階段**。
1. 在**階段詳細資訊**下，選擇複製圖示以複製 API 的調用 URL。
此 URL 看起來如下：
```
https://my-api-id.execute-api.region-id.amazonaws.com/prod
```
1. 在新瀏覽器標籤的地址方塊中輸入此 URL，並為此 URL 附加 `/pets/4`，然後才提交請求。
1. 瀏覽器會傳回以下內容：
```
{
"id": 4,
"type": "bird",
"price": 999.99
}
```
#### 後續步驟
您可以開啟請求驗證、轉換資料或建立自訂閘道回應，以進一步自訂 API。
若要探索更多自訂 API 的方法，請參閱下列教學課程：
+ 如需請求驗證的詳細資訊，請參閱「[在 API Gateway 中設定基本請求驗證](api-gateway-request-validation-set-up.md)」。
+ 如需如何轉換請求和回應承載的相關資訊，請參閱[教學課程：修改 AWS 服務整合的整合請求和回應](set-up-data-transformations-in-api-gateway.md)。
+ 如需如何建立自訂閘道回應的相關資訊，請參閱[使用 API Gateway 主控台設定 REST API 的閘道回應](set-up-gateway-response-using-the-console.md)。