Cloud Endpoints 快速入門導覽課程

本快速入門導覽課程會逐步引導您部署 Endpoints 管理的 API 範例。程式碼範例包括:

  • 可透過查詢機場的 IATA 代碼 (三個字母) 而找到機場名稱的 REST API。
  • 可將 API 設定上傳至 Endpoints 的指令碼。
  • 可部署託管 API 範例的 App Engine 彈性環境後端的指令碼。

傳送要求給 API 範例後,您可以在 Google Cloud Platform 主控台中查看 Endpoints 活動圖表和 Stackdriver 記錄。這些工具可讓您監控 API 並深入分析各 API 的使用情形。

本快速入門導覽課程使用指令碼來簡化設定步驟,以便您快速瞭解活動圖表和記錄的實務應用。要瞭解如何設定和部署 API 範例,請選擇其中一個 API 架構的教學課程:

事前準備

  1. 登入您的 Google 帳戶。

    如果您沒有帳戶,請申請新帳戶

  2. 選取或建立 Google Cloud Platform 專案。

    前往「Manage resources」(管理資源) 頁面

  3. 請確認您已啟用 Google Cloud Platform 專案的計費功能。

    瞭解如何啟用計費功能

啟動 Cloud Shell

  1. 在 GCP 主控台中,確認您位於要用於 API 範例的專案內。

  2. 開啟 Cloud Shell。

    開啟 Cloud Shell

    系統會在 GCP 主控台底部的新頁框中開啟 Cloud Shell 工作階段,並顯示指令列提示。工作階段可能需要幾秒鐘的時間才能完成初始化。

    Cloud Shell 工作階段

  3. 如果您是使用現有的專案,請確認所有已安裝的 gcloud 元件皆已安裝最新版本:

    gcloud components update
    

取得程式碼範例

  1. 在 Cloud Shell 中,輸入下列指令以取得 API 範例和指令碼:

    git clone https://github.com/GoogleCloudPlatform/endpoints-quickstart
    
  2. 變更為包含程式碼範例的目錄:

    cd endpoints-quickstart
    

部署端點配置

如要將 REST API 發佈至 Endpoints,您需要說明該 API 的 OpenAPI 設定檔。API 範例隨附一個名為 openapi.yaml 的預先設定 OpenAPI 檔案。

Endpoints 使用 Service Management 這個 GCP 基礎架構服務來建立和管理 API 與服務。如要使用 Endpoints 來管理 API,請將 API 的 OpenAPI 設定檔部署至 Service Management。

如何部署 Endpoints 設定:

  1. 在 Cloud Shell 的 endpoints-quickstart 目錄中,輸入下列指令:

    cd scripts
    
  2. 執行範例中包含的以下指令碼:

    ./deploy_api.sh
    

Endpoints 使用 OpenAPI 設定檔中的 host 欄位來識別服務。deploy_api.sh 指令碼會將 GCP 專案的 ID 設定為 host 欄位中設定的名稱的一部分。當您為自己的服務準備 OpenAPI 設定檔時,必須手動執行此操作。

指令碼接著會使用下列指令將 OpenAPI 設定部署至 Service Management:gcloud endpoints services deploy openapi.yaml

Service Management 在建立和設定服務時,會將資訊輸出至 GCP 主控台。您可以安全地忽略 openapi.yaml 中的路徑不需要 API 金鑰的警告。成功完成後,您將會看到類似下列包含服務設定 ID 和服務名稱的一行文字:

    Service Configuration [2017-02-13-r2] uploaded for service [airports-api.endpoints.example-project.cloud.goog]

部署 API 後端

到目前為止,您已經將 OpenAPI 設定部署到 Service Management,但還沒有部署程式碼來提供 API 後端。App Engine.範例中包含的 deploy_app.sh 指令碼會建立 App Engine 彈性環境來託管 API 後端,然後該指令碼會將 API 部署至 App Engine。

如何部署 API 後端:

  • 在 Cloud Shell 的 endpoints-quickstart/scripts 目錄中,執行下列指令碼:

    ./deploy_app.sh
    

該指令碼會執行下列指令,以在 us-central 地區中建立 App Engine 彈性環境: gcloud app create --region="$REGION"

建立 App Engine 彈性環境後端需要幾分鐘的時間。建立應用程式後,輸出結果如下:

Success! The app is now created.

接下來,指令碼會執行 gcloud app deploy 指令,將 API 範例部署至 App Engine。

輸出結果如下:

Deploying ../app/app_template.yaml...You are about to deploy the following services:

將 API 部署至 App Engine 需要幾分鐘的時間。API 成功部署至 App Engine 後,輸出結果如下:

Deployed service [default] to [https://example-project.appspot.com]

傳送要求至 API

  • 在 Cloud Shell 中,部署範例 API 後,您可以執行以下指令碼傳送要求:

    ./query_api.sh
    

該指令碼會回應它用來傳送要求至 API 的 curl 指令,然後顯示結果。輸出結果如下:

curl "https://example-project.appspot.com/airportName?iataCode=SFO"
San Francisco International Airport

該 API 需要一個設定到有效 IATA 機場代碼 (例如 SEAJFK) 的查詢參數 iataCode。例如:

./query_api.sh JFK

注意:App Engine 可能需要幾分鐘的時間才能成功回應要求。如果您在傳送要求後收到 HTTP 502、503 或其他伺服器錯誤,請稍後再重新提出要求。

您已在 Endpoints 中部署並測試了 API!

追蹤 API 活動

使用 Endpoints 部署 API 後,您就可以在 GCP 主控台中監控關鍵作業的指標數據,並運用 Stackdriver Logging 深入瞭解使用者與他們的使用情形。

  1. 在 Cloud Shell 中,執行流量產生指令碼以填入圖形和記錄:

    ./generate_traffic.sh
    
  2. 在 GCP 主控台中,查看 API 的活動圖表。

    前往 Endpoints 的「Services」(服務) 頁面

    要求可能需要一些時間才能反映在圖表中。等待資料顯示時:

    • 如果「Permissions」(權限) 側邊面板未開啟,請點選 [+Permissions] (+權限)。「Permissions」(權限) 面板可讓您控制誰有權存取 API,並控制這些人員的存取層級。

    • 按一下 [Deployment history] (部署記錄)。此分頁會顯示您的 API 部署記錄,包括部署時間和部署變更的人員。

    • 按一下 [Overview] (總覽)。您會看到流量進來。在流量產生指令碼執行一分鐘後,您應該會在「Total latency」(總延遲時間) 圖表上看到三行資料 (第 50、第 95 和第 98 百分位數)。您可使用此資料預估回應時間。

  3. 向下捲動至圖表底部,並按一下「Method」(方法) 下的 [GET/airportName]。「Logs Viewer」(記錄檢視器) 頁面會顯示該 API 的要求記錄。

  4. 開啟 Cloud Shell。

    開啟 Cloud Shell

  5. 如要停止指令碼,請輸入 Ctrl+C

新增配額至 API

Endpoints 可讓您透過設定配額控管應用程式呼叫您的 API 的頻率。您可以使用配額保護 API,避免單一用戶端的過多使用量。

  1. 在 Cloud Shell 中,部署具有配額的 Endpoints 設定。

    ./deploy_api.sh ../openapi_with_ratelimit.yaml
    

    部署更新的 Endpoints 設定後,它會在一分鐘內變成有效狀態。

  2. 在 GCP 主控台中,前往「Credentials」(憑證) 頁面。

    前往「Credentials」(憑證) 頁面

  3. 依序按一下 [Create credentials] (建立憑證) > [API key] (API 金鑰)。新的 API 金鑰會顯示在畫面上。

  4. 按一下 [Copy] (複製) file_copy

  5. 在 Cloud Shell 中輸入以下指令。將 YOUR_API_KEY 改為您剛建立的 API 金鑰。

    export API_KEY=YOUR_API_KEY
    
  6. 使用您剛產生的 API 金鑰傳送要求至您的 API。

    ./query_api_with_key.sh $API_KEY
    

    輸出結果會與下列內容相似:

    curl -H 'x-api-key: AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB' "https://example-project.appspot.com/airportName?iataCode=SFO"
    San Francisco International Airport
    
  7. API 現在有每分鐘 5 個要求的限制。請執行以下指令以傳送流量至該 API,並觸發配額限制。

    ./generate_traffic_with_key.sh $API_KEY
    
  8. 在指令碼執行了 5 至 10 秒後,輸入 Ctrl-C 以停止該指令碼。

  9. 傳送另一個通過驗證的要求至 API。

    ./query_api_with_key.sh $API_KEY
    

    輸出結果會與下列內容相似:

    {
     "code": 8,
     "message": "Insufficient tokens for quota 'airport_requests' and limit 'limit-on-airport-requests' of service 'example-project.appspot.com' for consumer     'api_key:AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB'.",
     "details": [
      {
       "@type": "type.googleapis.com/google.rpc.DebugInfo",
       "stackEntries": [],
       "detail": "internal"
      }
     ]
    }
    

如果您收到不同的回應,請重新執行 generate_traffic_with_key.sh 指令碼,然後再試一次。

恭喜!您已成功為 API 加上頻率限制。您也可以在不同的 API 方法上設定不同的限制、建立多種配額,以及追蹤哪些使用者使用了哪些 API。

詳情請參閱關於配額一文。

建立 API 開發人員入口網站

您可以透過 Cloud Endpoints 入口網站建立開發人員入口網站,並將該網站用於與範例 API 進行互動。詳情請參閱 Cloud Endpoints 入口網站總覽

清除所用資源

如何避免系統向您的 GCP 帳戶收取您在本快速入門中所用資源的相關費用:

如要避免支付費用,您可以刪除 GCP 專案,這樣系統就會停止對該專案使用的所有資源計費。

  1. 前往 GCP 主控台的「Projects」(專案) 頁面。

    前往專案頁面

  2. 在專案清單中選取要刪除的專案,然後按一下 [Delete] (刪除)
  3. 在對話方塊中輸入專案 ID,按一下 [Shut down] (關閉) 即可刪除專案。

相關資源

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Cloud Endpoints
需要協助嗎?請前往我們的支援網頁