本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 選擇 HTTP 整合教學課程
若要建置具有 HTTP 整合的 API，您可以使用 HTTP 代理整合或 HTTP 自訂整合。
在 HTTP 代理整合中，您只需根據後端需求來設定 HTTP 方法和 HTTP 端點 URI。建議您盡可能使用 HTTP 代理整合，以充分善用簡化的 API 設定。
如果您需要為後端轉換用戶端請求資料，或為用戶端轉換後端回應資料，您可能會想要使用 HTTP 自訂整合。
**Topics**
+ [教學：建立具有 HTTP 代理整合的 REST API](api-gateway-create-api-as-simple-proxy-for-http.md)
+ [教學：建立具有 HTTP 非代理整合的 REST API](api-gateway-create-api-step-by-step.md)
# 教學：建立具有 HTTP 代理整合的 REST API
HTTP 代理整合是建置 API 的簡單、功能強大且多樣化的機制，可讓 Web 應用程式存取整合式 HTTP 端點 (例如整個網站) 的多個資源或功能，以簡化單一 API 方法的設定。在 HTTP 代理整合中，API Gateway 會將用戶端提交的方法請求傳遞至後端。傳遞的請求資料包含請求標頭、查詢字串參數、URL 路徑變數和承載。後端 HTTP 端點或 Web 伺服器會剖析傳入請求資料，以判斷其所傳回的回應。在設定 API 方法之後，HTTP 代理整合可讓用戶端和後端直接互動，而不需要 API Gateway 介入，除了 [Amazon API Gateway 重要說明](api-gateway-known-issues.md)所列的一些已知問題，例如不支援的字元。
使用全能代理資源 `{proxy+}`，以及 HTTP 方法的 catch-all `ANY` 動詞，您可以使用 HTTP 代理整合來建立單一 API 方法的 API。此方法會公開網站的整個可公開存取的 HTTP 資源和操作集。後端 Web 伺服器開啟更多資源來進行公開存取時，用戶端可以搭配使用這些新的資源與相同的 API 設定。若要啟用此功能，網站開發人員必須與用戶端開發人員清楚地溝通新資源以及每個新資源適用的操作。
下列教學是快速簡介，可示範 HTTP 代理整合。在教學課程中，我們使用 API Gateway 主控台建立 API 以透過一般代理資源 `{proxy+}` 與 PetStore 網站整合，並建立 HTTP 方法預留位置 `ANY`。
**Topics**
+ [使用 API Gateway 主控台來建立具有 HTTP 代理整合的 API。](#api-gateway-create-api-as-simple-proxy-for-http-build)
+ [測試具有 HTTP 代理整合的 API](#api-gateway-create-api-as-simple-proxy-for-http-test)
## 使用 API Gateway 主控台來建立具有 HTTP 代理整合的 API。
下列程序會逐步解說如何使用 API Gateway 主控台，建立和測試具有 HTTP 後端之代理資源的 API。HTTP 後端是「`PetStore`」中的 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` 網站 ([教學：建立具有 HTTP 非代理整合的 REST API](api-gateway-create-api-step-by-step.md))；其中，螢幕擷取畫面是用來顯示提醒，以說明 API Gateway UI 元素。如果您是第一次使用 API Gateway 主控台來建立 API，則建議您先遵循該節。
**建立 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 名稱**，輸入 **HTTPProxyAPI**。
1. 在**描述**，請輸入描述。
1. 將 **API 端點類型**保持設定為**區域**。
1. 針對 **IP 位址類型**，選擇 **IPv4**。
1. 選擇**建立 API**。
在此步驟中，您會建立 `{proxy+}` 的代理資源路徑。這是 `http://petstore-demo-endpoint.execute-api.com/` 下方之任何後端端點的預留位置。例如，它可以是 `petstore`、`petstore/pets` 和 `petstore/pets/{petId}`。API Gateway 會在您建立 `{proxy+}` 資源時建立 `ANY` 方法，並在執行時間將該方法作為任何受支援 HTTP 動詞的預留位置。
**建立 **/\$1proxy\$1\$1** 資源**
1. 選擇您的 API。
1. 在主導覽窗格中，選擇**資源**。
1. 選擇**建立資源**。
1. 開啟**代理資源**。
1. 將**資源路徑**保持為 `/`。
1. 針對**資源名稱**，輸入 **\$1proxy\$1\$1**。
1. 讓 **CORS (跨來源資源分享)** 保持關閉。
1. 選擇**建立資源**。
![\[建立子資源。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/api-gateway-simple-proxy-create-proxy-resource-new-console.png)
在此步驟中，您會使用代理整合將 `ANY` 方法與後端 HTTP 端點整合。在代理整合中，API Gateway 會將用戶端提交的方法請求傳遞至後端，而不需要 API Gateway 介入。
**建立 `ANY` 方法**
1. 選擇 **/\$1proxy\$1\$1** 資源。
1. 選擇 **ANY** 方法。
1. 在警告符號下，選擇**編輯整合**。如果 API 的方法沒有整合，便無法部署該 API。
1. 針對**整合類型**，選取 **HTTP**。
1. 開啟 **HTTP 代理整合**。
1. 針對 **HTTP 方法**，選取 **ANY**。
1. 針對**端點 URL**，輸入 **http://petstore-demo-endpoint.execute-api.com/\$1proxy\$1**。
1. 選擇**儲存**。
## 測試具有 HTTP 代理整合的 API
特定用戶端請求成功與否取決於下列項目：
+ 如果後端已讓對應的後端端點可供使用，因此已授予所需的存取許可。
+ 如果用戶端提供正確的輸入。
例如，這裡使用的 PetStore API 未公開 `/petstore` 資源。因此，您會取得包含錯誤訊息 `404 Resource Not Found` 的 `Cannot GET /petstore` 回應。
此外，用戶端必須能夠處理後端的輸出格式，才能正確地剖析結果。API Gateway 不會居中來促進用戶端與後端之間的互動。
**透過代理資源使用 HTTP 代理整合來測試與 PetStore 網站整合的 API**
1. 選取**測試**索引標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。
1. 針對**方法類型**，選取 `GET`。
1. 針對**路徑**，在**代理**下輸入 **petstore/pets**。
1. 針對**查詢字串**，輸入 **type=fish**。
1. 選擇**測試**。
![\[使用測試功能來測試方法。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/api-gateway-simple-proxy-petstore-call-proxy-resource-new-console.png)
因為後端網站支援 `GET /petstore/pets?type=fish` 請求，所以它會傳回與下列類似的成功回應：
```
[
{
"id": 1,
"type": "fish",
"price": 249.99
},
{
"id": 2,
"type": "fish",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
如果您嘗試呼叫 `GET /petstore`，則會取得具有錯誤訊息 `404` 的 `Cannot GET /petstore` 回應。原因是後端不支援指定的操作。如果您呼叫 `GET /petstore/pets/1`，則會取得具有下列承載的 `200 OK` 回應，因為 PetStore 網站支援請求。
```
{
"id": 1,
"type": "dog",
"price": 249.99
}
```
您也可以使用瀏覽器來測試您的 API。部署您的 API 並將其關聯到某個階段，以建立 API 的調用 URL。
**部署 API**
1. 選擇**部署 API**。
1. 針對**階段**，選取**新階段**。
1. 針對**階段名稱**，輸入 **test**。
1. 在**描述**，請輸入描述。
1. 選擇**部署**。
現在，用戶端可以呼叫您的 API。
**若要調用您的 API**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇您的 API。
1. 在主導覽窗格中，選擇**階段**。
1. 在**階段詳細資訊**下，選擇複製圖示以複製 API 的調用 URL。
在 Web 瀏覽器中輸入 API 的調用 URL。
完整 URL 看起來應該會像這樣：`https://abcdef123.execute-api.us-east-2.amazonaws.com/test/petstore/pets?type=fish`。
您的瀏覽器將向 API 傳送 `GET` 請求。
1. 結果應該與在 API Gateway 主控台中使用**測試**時所傳回的結果相同。
# 教學：建立具有 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)。