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

# 教學：建立具有 HTTP 代理整合的 REST API
<a name="api-gateway-create-api-as-simple-proxy-for-http"></a>

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。
<a name="api-gateway-create-api-as-simple-proxy-for-http-build"></a>

 下列程序會逐步解說如何使用 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
<a name="api-gateway-create-api-as-simple-proxy-for-http-test"></a>

 特定用戶端請求成功與否取決於下列項目：
+  如果後端已讓對應的後端端點可供使用，因此已授予所需的存取許可。
+ 如果用戶端提供正確的輸入。

例如，這裡使用的 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 主控台中使用**測試**時所傳回的結果相同。