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

# 教學課程：匯入範例來建立 REST API
<a name="api-gateway-create-api-from-example"></a>

您可以使用 Amazon API Gateway 主控台，利用 HTTP 整合，針對 PetStore 網站建立和測試簡單的 REST API。API 定義會預先設定為 OpenAPI 2.0 檔案。將 API 定義載入至 API Gateway 之後，您可以使用 API Gateway 主控台來檢查 API 的基本結構，或僅部署和測試 API。

 PetStore 範例 API 支援下列方法，讓用戶端存取 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` 的 HTTP 後端網站。

**注意**  
本教學課程使用 HTTP 端點作為範例。當您建立自己的 API 時，我們建議您使用 HTTPS 端點進行 HTTP 整合。
+ `GET /`：適用於未與任何後端端點整合之 API 根資源的讀取存取。API Gateway 會回應 PetStore 網站的概觀。這是 `MOCK` 整合類型範例。
+ `GET /pets`：適用於與相同具名後端 `/pets` 資源整合之 API `/pets` 資源的讀取存取。後端會傳回 PetStore 中可用寵物的頁面。這是 `HTTP` 整合類型範例。整合端點的 URL 是 `http://petstore-demo-endpoint.execute-api.com/petstore/pets`。
+ `POST /pets`：適用於與後端 `/pets` 資源整合之 API `/petstore/pets` 資源的寫入存取。在收到正確的請求時，後端會將指定的寵物新增至 PetStore，並將結果傳回給發起人。此整合也是 `HTTP`。
+ `GET /pets/{petId}`：適用於指定為傳入請求 URL 之路徑變數的 `petId` 值所識別寵物的讀取存取。這個方法也有 `HTTP` 整合類型。後端會傳回 PetStore 中找到的指定寵物。後端 HTTP 端點的 URL 是 `http://petstore-demo-endpoint.execute-api.com/petstore/pets/n`，其中 `n` 是作為所查詢寵物識別符的整數。

 API 支援透過 `OPTIONS` 整合類型之 `MOCK` 方法的 CORS 存取。API Gateway 會傳回支援 CORS 存取的所需標頭。

下列程序會逐步解說如何使用 API Gateway 主控台從範例建立和測試 API。

**匯入、建置和測試範例 API**

1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。

1. 執行以下任意一項：
   + 若要建立您的第一個 API，請針對 **REST API** 選擇**建置**。
   + 如果您之前已建立 API，則選擇**建立 API**，然後針對 **REST API** 選擇**建置**。

1.  在**建立 REST API** 下，選擇**範例 API**，然後選擇**建立 API** 來建立範例 API。

      
![\[API Gateway 主控台的 REST API 範例。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/api-gateway-create-api-by-importing-example-new-console.png)

    您可以先捲動 OpenAPI 定義以取得此範例 API 的詳細資訊，再選擇**建立 API**。

1. 在主導覽窗格中，選擇**資源**。新建立的 API 如下所示：

      
![\[匯入 API Gateway 主控台後的範例 API。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/api-gateway-create-api-by-importing-example-result-new-console.png)

    **Resources (資源)** 窗格會將已建立 API 的結構顯示為節點樹狀結構。每個資源上所定義的 API 方法就是樹狀結構的邊緣。選取資源時，其所有方法都會列在右側的**方法**表中。每一種方法都會顯示方法類型、整合類型、授權類型和 API 金鑰需求。

1.  若要檢視方法的詳細資訊、修改其設定或測試方法呼叫，請從方法清單或資源樹狀結構中選擇方法名稱。在這裡，我們選擇 `POST /pets` 方法作為插圖：

      
![\[用於 API Gateway 主控台的範例 API 的 POST /pets 方法。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/api-gateway-create-api-by-importing-example-post-method-execution-new-console.png)

    產生的**方法執行**窗格會顯示所選 (`POST /pets`) 方法結構和行為的邏輯檢視。

   **方法請求**和**方法回應**代表 API 與前端的介面，而**整合請求**和**整合回應**代表 API 與後端的介面。

    用戶端會使用 API 透過**方法請求**來存取後端功能。API Gateway 會在必要時先將用戶端請求轉譯為**整合請求**中後端可接受的形式，再將傳入請求轉送至後端。轉換後的請求稱為整合請求。同樣地，後端會傳回**整合回應**中的 API Gateway 回應。API Gateway 接著會先將它路由至 **Method Response (方法回應)**，再將它傳送至用戶端。同樣地，若有必要，API Gateway 可以將後端回應資料映射至用戶端所預期的形式。

    針對 API 資源上的 `POST` 方法，如果方法請求承載的格式與整合請求承載的格式相同，則可以將方法請求承載傳遞至整合請求，而不需要修改。

   `GET /` 方法請求會使用 `MOCK` 整合類型，而且未繫結至任何實際後端端點。對應的**整合回應**設定為傳回靜態 HTML 頁面。呼叫方法時，API Gateway 只需要接受請求，並立即透過**方法回應**，將已設定的整合回應傳回給用戶端。您可以使用模擬整合來測試 API，而不需要後端端點。您也可以使用它來服務從回應內文映射範本產生的本機回應。

   身為 API 開發人員，您可以設定方法請求和方法回應來控制 API 前端互動的行為。您可以設定整合請求和整合回應來控制 API 後端互動的行為。這些涉及方法與其映射整合之間的資料映射。現在，我們專注於測試 API，以提供端對端使用者體驗。

1.  選取**測試**索引標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。

1.  例如，若要測試 `POST /pets` 方法，請將下列 **\$1"type": "dog","price": 249.99\$1** 承載輸入至**請求內文**，然後選擇**測試**。

      
![\[在 API Gateway 主控台測試 POST 方法。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/api-gateway-create-api-by-importing-example-post-method-test-new-console.png)

    輸入指定我們想要新增至 PetStore 網站上寵物清單的寵物屬性。

1. 結果顯示如下：

      
![\[在 API Gateway 主控台測試 POST 方法的結果。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/api-gateway-create-api-by-importing-example-post-method-test-result-new-console.png)

    輸出的**日誌**項目會顯示從方法請求到整合請求，以及從整合回應到方法回應的狀態變更。這適用於故障診斷任何會導致請求失敗的映射錯誤問題。在這個範例中，不會套用任何映射：方法請求承載會透過整合請求傳遞至後端；且同樣地，後端回應會透過整合回應傳遞至方法回應。

    若要使用 API Gateway 測試呼叫請求功能以外的用戶端來測試 API，您必須先將 API 部署至階段。

1.  選擇**部署 API**以部署範例 API。

      
![\[使用部署按鈕來部署您的 API，讓 API 呼叫者可以調用您的 API。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/api-gateway-create-api-by-importing-example-deploy-api-new-console.png)

1. 針對**階段**，選取**新增階段**，然後輸入 **test**。

1. 在**描述**，請輸入描述。

1. 選擇**部署**。

1.  在產生的**階段**窗格中的**階段詳細資訊**下，**調用 URL** 會顯示調用 API 的 `GET /` 方法請求的 URL。  
![\[在建立 REST API 之後，主控台會顯示 API 的調用 URL。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/getting-started-rest-invoke-url.png)

1. 選擇複製圖示以複製您的 API 的調用 URL，然後在 Web 瀏覽器中輸入您的 API 調用 URL。成功回應會傳回整合回應中從映射範本產生的結果。

1.  在 **Stages** (階段) 導覽窗格中，展開 **test** (測試) 階段，並選取 `/pets/{petId}` 上的 **GET**，然後複製 `https://api-id.execute-api.region.amazonaws.com/test/pets/{petId}` 的 **Invoke URL** (叫用 URL) 值。`{petId}` 代表路徑變數。

    將 **Invoke URL (呼叫 URL)** 值 (在前一個步驟中取得) 貼入瀏覽器的網址列 (例如，將 `{petId}` 取代為 `1`)，以及按 Enter 來提交請求。200 OK 回應傳回時應該具有下列 JSON 承載：

   ```
   {
     "id": 1,
     "type": "dog",
     "price": 249.99
   }
   ```

    如所示呼叫 API 方法可能是因為其 **Authorization (授權)** 類型設定為 `NONE`。如果使用 `AWS_IAM` 授權，請使用[第 4 版簽署程序](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html) (SigV4) 或[第 4a 版簽署程序](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html#how-sigv4a-works) (SigV4a) 通訊協定來簽署請求。如需這類請求的範例，請參閱[教學：建立具有 HTTP 非代理整合的 REST API](api-gateway-create-api-step-by-step.md)。