教學課程：匯入範例來建立 REST API - Amazon API Gateway

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

教學課程：匯入範例來建立 REST API

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

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

注意

本教學課程使用 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。

  2. 執行以下任意一項：

    • 若要建立您的第一個 API，請針對 REST API 選擇建置。

    • 如果您之前已建立 API，則選擇建立 API，然後針對 REST API 選擇建置。

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

    API Gateway 主控台中的範例 REST API。

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

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

    將 API 匯入 API Gateway 主控台後的範例 API。

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

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

    API Gateway 主控台中範例 API 的 POST /寵物方法。

    產生的方法執行窗格會顯示所選 (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 以提供用 end-to-end 戶體驗。

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

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

    在 API Gateway 主控台中測試 POST 方法。

    輸入指定我們要添加到 PetStore 網站上的寵物列表中的寵物的屬性。

  8. 結果顯示如下：

    在 API Gateway 主控台中測試 POST 方法的結果。

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

    若要使用 API Gateway test-invoke-request 功能以外的用戶端測試 API，您必須先將 API 部署到階段。

  9. 選擇部署 API以部署範例 API。

    使用部署按鈕來部署您的 API，以便 API 呼叫者可以叫用您的 API。

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

  11. 在描述，請輸入描述。

  12. 選擇部署。

  13. 在產生的階段窗格中的階段詳細資訊下，調用 URL 會顯示調用 API 的 GET / 方法請求的 URL。

    在建立 REST API 之後，主控台會顯示 API 的調用 URL。

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

  15. 在 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 授權，請使用 Signature 第 4 版 (SigV4) 通訊協定來簽署請求。如需這類請求的範例，請參閱教學課程：RESTAPI使用HTTP非代理整合建立。