透過 ESP 在 App Engine 彈性環境中開始使用 Cloud Endpoints

本教學課程說明如何在 App Engine 彈性環境中，設定與部署在執行個體上執行的範例 API 和可擴充服務 Proxy (ESP)。本文使用 OpenAPI 規範說明範例程式碼的 REST API。本教學課程也會說明如何建立 API 金鑰並用於對 API 的要求中。

如需 Cloud Endpoints 的總覽資訊，請參閱關於 Endpoints 和 Endpoints 架構。

目標

請根據以下的主要工作清單，逐步進行本教學課程的各個步驟。您必須完成所有工作才能成功傳送要求至 API。

  1. 設定 Google Cloud 專案、安裝必要軟體，然後建立 App Engine 應用程式。請參閱事前準備一文。
  2. 下載範例程式碼。請參閱取得範例程式碼。
  3. 設定 openapi-appengine.yaml 檔案，這個檔案用於設定 Endpoints。請參閱設定 Endpoints 一節。
  4. 部署 Endpoints 設定以建立 Endpoints 服務。請參閱部署 Endpoints 設定一節。
  5. 將 API 和 ESP 部署至 App Engine。請參閱部署 API 後端一節。
  6. 傳送要求至 API。請參閱傳送要求至 API 一節。
  7. 追蹤 API 活動。請參閱追蹤 API 活動一節。
  8. 避免系統向您的 Google Cloud 帳戶收取費用。請參閱「清除所用資源」一節。

費用

在本文件中，您會使用 Google Cloud的下列計費元件：

您可以使用 Pricing Calculator 根據預測用量產生預估費用。 新 Google Cloud 使用者可能符合申請免費試用的資格。

完成本文件所述工作後，您可以刪除已建立的資源，避免繼續計費。詳情請參閱「清除所用資源」。

事前準備

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. 記下專案 ID，後續步驟將會用到。

  7. 您需要一個可以將要求傳送至範例 API 的應用程式。

    • Linux 和 macOS 使用者：本教學課程提供了使用 curl 的範例，這項工具通常已預先安裝於您的作業系統。如果您尚未安裝 curl，可以前往 curl 的版本與下載頁面下載這項工具。
    • Windows 使用者：本教學課程提供了使用 Invoke-WebRequest 的範例，PowerShell 3.0 以上版本均支援這項工具。
  8. 下載 Google Cloud CLI。
  9. 更新 gcloud CLI 並安裝 Endpoints 元件。
    gcloud components update
  10. 確認 Google Cloud CLI (gcloud) 已取得授權，可存取您在 Google Cloud中的資料與服務：
    gcloud auth login
     在開啟的新瀏覽器分頁中選取一個帳戶。
  11. 將預設專案設為您的專案 ID。
    gcloud config set project YOUR_PROJECT_ID

    將 YOUR_PROJECT_ID 替換為專案 ID。如果您有其他 Google Cloud 專案，而且想要使用 gcloud 加以管理，請參閱「 管理 gcloud CLI 設定」一文。

  12. 選取您要在其中建立 App Engine 應用程式的地區。執行以下指令即可取得地區的清單：
    gcloud app regions list
  13. 建立 App Engine 應用程式。請將 YOUR_PROJECT_ID 改成您的 Google Cloud專案 ID，並將 YOUR_REGION 改成您要建立 App Engine 應用程式的地區。
      gcloud app create \
  --project=YOUR_PROJECT_ID \
  --region=YOUR_REGION

取得程式碼範例

Java

如何複製或下載範例 API：

  1. 範例程式碼使用 Maven。如果您沒有 Maven 3.3.9 以上版本，請先下載並安裝。
  2. 將範例應用程式存放區複製到您的本機電腦：
    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

    或者，您也可以選擇下載範例 ZIP 檔案，然後再解壓縮。

  3. 前往包含範例程式碼的目錄：
    cd java-docs-samples/endpoints/getting-started
Python

如何複製或下載範例 API：

  1. 將範例應用程式存放區複製到您的本機電腦：
    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    或者，您也可以選擇下載範例 ZIP 檔案，然後再解壓縮。

  2. 前往包含範例程式碼的目錄：
    cd python-docs-samples/endpoints/getting-started
Go

如何複製或下載範例 API：

  1. 確定您已設定 GOPATH 環境變數。
  2. 將範例應用程式存放區複製到您的本機電腦：
    go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
  3. 前往包含範例程式碼的目錄：
    cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
PHP

如何複製或下載範例 API：

  1. 將範例應用程式存放區複製到您的本機電腦：
    git clone https://github.com/GoogleCloudPlatform/php-docs-samples

    或者，您也可以選擇下載範例 ZIP 檔案，然後再解壓縮。

  2. 前往包含範例程式碼的目錄：
    cd php-docs-samples/endpoints/getting-started
Ruby

如何複製或下載範例 API：

  1. 將範例應用程式存放區複製到您的本機電腦：
    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    或者，您也可以選擇下載範例 ZIP 檔案，然後再解壓縮。

  2. 前往包含範例程式碼的目錄：
    cd ruby-docs-samples/endpoints/getting-started
NodeJS

如何複製或下載範例 API：

  1. 將範例應用程式存放區複製到您的本機電腦：
    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

    或者，您也可以選擇下載範例 ZIP 檔案，然後再解壓縮。

  2. 前往包含範例程式碼的目錄：
    cd nodejs-docs-samples/endpoints/getting-started

設定 Endpoints

範例程式碼中包含以 OpenAPI 規格 v2.0 為基礎的 OpenAPI 設定檔 openapi-appengine.yaml。

如何設定 Endpoints：
  1. 在範例程式碼目錄中開啟 openapi-appengine.yaml 設定檔。

    Java
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    Python
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    Go
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    PHP
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    Ruby
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    NodeJS
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"

    注意事項：

    • 設定範例會顯示 host 欄位附近的文字行，您必須修改這些文字行。如要將 openapi-appengine.yaml 部署至 Endpoints，您必須使用完整的 OpenAPI 文件。
    • 範例 openapi-appengine.yaml 中包含用來設定驗證作業的區段，不過本教學課程無須執行這個步驟。您不需要設定含有 YOUR-SERVICE-ACCOUNT-EMAIL 和 YOUR-CLIENT-ID 的文字行。
    • OpenAPI 是一種各語言通用的規範。為求方便，相同的 openapi-appengine.yaml 檔案皆位於每個語言 GitHub 存放區的 getting-started 範例中。

  2. 在含有 host 欄位的文字行中，以您的 Google Cloud 專案 ID 取代 YOUR-PROJECT-ID。例如：例如： 
    host: "example-project-12345.appspot.com"

Endpoints 使用 host 欄位中設定的文字做為服務名稱。在您將 API 部署至 App Engine 後端時，系統會自動建立名稱格式為 YOUR-PROJECT-ID.appspot.com 的 DNS 項目。

如要瞭解 Endpoints 所需的 OpenAPI 文件欄位，請參閱「設定 Endpoints」一文。

部署 Endpoints 設定

如要部署 Endpoints 設定，請使用 gcloud endpoints services deploy 指令。這個指令會使用 Service Management 建立代管服務。

如何部署 Endpoints 設定：

  1. 確認您位於 endpoints/getting-started 目錄。
  2. 上傳設定並建立代管服務：
    gcloud endpoints services deploy openapi-appengine.yaml

接著，gcloud 指令會呼叫 Service Management API，並使用您在 openapi-appengine.yaml 檔案 host 欄位中指定的名稱建立代管服務。Service Management 會依據 openapi-appengine.yaml 檔案中的設定建立服務。變更 openapi-appengine.yaml 時，您必須重新部署檔案才能更新 Endpoints 服務。

Service Management 在建立和設定服務時，會輸出資訊至終端機。您可以放心忽略 openapi-appengine.yaml 檔案中路徑不需要 API 金鑰的警告。完成服務設定程序之後，Service Management 會顯示含有服務設定 ID 與服務名稱的訊息，類似於以下內容：

Service Configuration [2017-02-13r0] uploaded for service [example-project-12345.appspot.com]

在上方的範例中，2017-02-13r0 是服務設定 ID，example-project-12345.appspot.com 則為 Endpoints 服務。服務設定 ID 是由一個日期戳記和一個修訂版本編號所組成。如果您在同一天再次部署 openapi-appengine.yaml 檔案，服務設定 ID 中的修訂版本編號就會遞增。您可以在控制台的「Endpoints」 >「Services」(服務) 頁面中查看 Endpoints 服務設定。 Google Cloud

如果您收到錯誤訊息，請參閱 Endpoints 設定部署疑難排解一文。

檢查必要服務

Endpoints 和 ESP 至少需要啟用下列 Google 服務：
名稱 標題
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

在大多數情況下，gcloud endpoints services deploy 指令會啟用這些必要服務。不過在以下情況中，即便您成功執行 gcloud 指令，還是無法啟用必要服務：

  • 您使用 Terraform 之類的第三方應用程式，而其中未包含這些服務。

  • 您已將 Endpoints 設定部署至現有Google Cloud 專案，但在專案中已明確停用這些服務。

使用下列指令確認已啟用必要服務：

gcloud services list

如果必要的服務並未列出，請執行下列指令加以啟用：

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

並啟用 Endpoints 服務：

gcloud services enable ENDPOINTS_SERVICE_NAME

如要判斷 ENDPOINTS_SERVICE_NAME，您可以採取下列任一做法：

  • 部署 Endpoints 設定後，請前往 Cloud 控制台的「Endpoints」頁面。Service name 欄下方會列出可能的 ENDPOINTS_SERVICE_NAME 清單。

  • 針對 OpenAPI，ENDPOINTS_SERVICE_NAME 是您在 OpenAPI 規格 host 欄位中指定的值。針對 gRPC，ENDPOINTS_SERVICE_NAME 是您在 gRPC Endpoints 設定的 name 欄位中指定的值。

如要進一步瞭解 gcloud 指令，請參閱 gcloud 服務。

部署 API 後端

到目前為止，您已將 OpenAPI 文件部署到 Service Management，但尚未部署為 API 後端提供服務的程式碼。本節會引導您將 API 範例和 ESP 部署至 App Engine。

如何部署 API 後端：

  1. 將您的服務名稱新增到 app.yaml 檔案中：

    Java

    開啟 endpoints/getting-started/src/main/appengine/app.yaml 檔案。

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    Python

    開啟 endpoints/getting-started/app.yaml 檔案。

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    Go

    開啟 endpoints/getting-started/app.yaml 檔案。

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    PHP

    開啟 endpoints/getting-started/app.yaml 檔案。

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
  # previously run the deploy command, you can list your existing configuration
  # ids using the 'configs list' command as follows:
  #
  #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
  #
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    Ruby

    開啟 endpoints/getting-started/app.yaml 檔案。

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    NodeJS

    開啟 endpoints/getting-started/app.yaml 檔案。

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    將 ENDPOINTS-SERVICE-NAME 替換為您的 Endpoints 服務名稱。這與您在 OpenAPI 文件的 host 欄位中設定的名稱相同。例如：

    endpoints_api_service:
  name: example-project-12345.appspot.com
  rollout_strategy: managed

    rollout_strategy: managed 選項可將 ESP 設為使用最新部署的服務設定。指定此選項時，在您部署新服務設定後 5 分鐘內，ESP 會偵測到變更並自動開始使用新設定。建議您指定此選項而非讓 ESP 使用特定的設定 ID。

  2. 儲存 app.yaml 檔案。

    3. 因為 app.yaml 檔案中包含 endpoints_api_service 區段，因此 gcloud app deploy 指令會設定獨立容器中的 ESP，並部署至您的 App Engine 彈性環境。所有的要求流量皆會透過 ESP 轉送，且其代理往返 (執行後端伺服器程式碼的) 容器的要求與回應。

  3. 確認您位於 endpoints/getting-started 目錄。這是 openapi-appengine.yaml 設定檔的所在位置。
  4. 執行下列指令以將範例 API 和 ESP 部署至 App Engine：

    5. Java

    使用 Maven 部署：

    mvn appengine:stage
gcloud app deploy target/appengine-staging
    Python
    gcloud app deploy
    Go
    gcloud app deploy
    PHP
    gcloud app deploy
    Ruby
    gcloud app deploy
    NodeJS
    gcloud app deploy

    gcloud app deploy 指令會以 YOUR_PROJECT_ID.appspot.com 格式建立 DNS 記錄，在您將要求傳送至 API 時即可使用。建議您稍等幾分鐘，然後在 App Engine 完成初始化後向 API 傳送要求。

如果您收到錯誤訊息，請參閱 App Engine 彈性部署疑難排解一文。

詳情請參閱部署 API 後端。

傳送要求至 API

現在該服務正在 App Engine 上執行，您可以向 App Engine 發送要求。

建立 API 金鑰並設定環境變數

範例程式碼需要 API 金鑰。為了簡化要求，請設定 API 金鑰的環境變數。

  1. 在您用於 API 的 Google Cloud 專案中，在 API 憑證頁面上建立 API 金鑰。如果您想在不同的 Google Cloud 專案中建立 API 金鑰，請參閱在 Google Cloud 專案中啟用 API。

    前往憑證頁面

  2. 按一下 [Create credentials] (建立憑證)，然後選取 [API key] (API 金鑰)。
  3. 將金鑰複製到剪貼簿。
  4. 按一下 [Close] (關閉)。
  5. 在本機電腦中貼上 API 金鑰，以便指派給環境變數：
    • 在 Linux 或 macOS 中：export ENDPOINTS_KEY=AIza...
    • 在 Windows PowerShell 中：$Env:ENDPOINTS_KEY="AIza..."

傳送要求

Linux 或 Mac OS

  1. 建立 App Engine 專案網址的環境變數。請將 YOUR_PROJECT_ID 替換為您的Google Cloud 專案 ID：

    export ENDPOINTS_HOST=https://YOUR_PROJECT_ID.appspot.com

  2. 使用先前設定的 ENDPOINTS_HOST 和 ENDPOINTS_KEY 環境變數傳送 HTTP 要求：

    curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"

在上方的 curl 中：

  • --data 選項會指定要發布至 API 的資料。
  • --header 選項會指定資料採用 JSON 格式。

PowerShell

  1. 建立 App Engine 專案網址的環境變數。請將 YOUR_PROJECT_ID 替換為您的Google Cloud 專案 ID：

    $Env:ENDPOINTS_HOST="https://YOUR_PROJECT_ID.appspot.com"

  2. 使用先前設定的 ENDPOINTS_HOST 和 ENDPOINTS_KEY 環境變數傳送 HTTP 要求：

    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "$Env:ENDPOINTS_HOST/echo?key=$Env:ENDPOINTS_KEY").Content

在上述範例中，前兩行的結尾為倒引號。當您將範例貼到 PowerShell 中時，請確保倒引號後面沒有空格。 如要瞭解範例要求中使用的選項，請參閱 Microsoft 說明文件中的 Invoke-WebRequest。

第三方應用程式

您可以使用諸如 Chrome 瀏覽器擴充功能 Postman 等第三方應用程式，傳送要求：

  • 選取 POST 做為 HTTP 動詞。
  • 選取 content-type 鍵和 application/json 值做為標頭。
  • 輸入以下內文：
    {"message":"hello world"}
  • 在網址中使用實際的 appspot.com 和 API 金鑰，而非環境變數。例如：
    https://example-project-12345.appspot.com/echo?key=AIza...

API 會回應您傳送給它的訊息，並回覆以下內容：

{
  "message": "hello world"
}

如果您未取得成功的回應，請參閱排解回應錯誤一文。

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

追蹤 API 活動

  1. 在「Endpoints」頁面中查看 API 的活動圖表。

    前往 Endpoints 服務頁面

    要求可能需要一些時間才能反映在圖表中。

  2. 在「Logs Explorer」(記錄檔探索工具) 頁面中查看您的 API 要求記錄。

    前往「Logs Explorer」頁面

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取本教學課程中所用資源的相關費用，請刪除含有該項資源的專案，或者保留專案但刪除個別資源。

如要瞭解如何停用本教學課程使用的服務，請參閱刪除 API 和 API 執行個體一文。

後續步驟