透過 ESPv2 為 Cloud Run 設定 Cloud Endpoints OpenAPI

保留 Cloud Run 主機名稱

您必須為 ESPv2 服務預留 Cloud Run 主機名稱，才能設定 OpenAPI 文件或 gRPC 服務設定。如要保留主機名稱，您必須將範例容器部署至 Cloud Run。稍後，您將部署 ESPv2 容器至相同的 Cloud Run 服務。

1. 確認 gcloud CLI 已獲授權，可存取您的資料和服務。
   1. 登入。

      gcloud auth login

   2. 在開啟的新瀏覽器分頁中，選擇在用於將 ESPv2 部署至 Cloud Run 而建立的 Google Cloud 專案中，具有編輯者或擁有者角色的帳戶。
2. 設定區域。

   gcloud config set run/region us-central1

3. 將範例映像檔 gcr.io/cloudrun/hello 部署至 Cloud Run。將 CLOUD_RUN_SERVICE_NAME 替換為您想要用於該服務的名稱。

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
       --image="gcr.io/cloudrun/hello" \
       --allow-unauthenticated \
       --platform managed \
       --project=ESP_PROJECT_ID
   

   成功完成後，這個指令會顯示類似如下的訊息：

   Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

   舉例來說，如果您將 CLOUD_RUN_SERVICE_NAME 設為 gateway：

   Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

   在這個範例中，https://gateway-12345-uc.a.run.app 是 CLOUD_RUN_SERVICE_URL，gateway-12345-uc.a.run.app 是 CLOUD_RUN_HOSTNAME。

4. 請記下 CLOUD_RUN_SERVICE_NAME 和 CLOUD_RUN_HOSTNAME。之後，您會將 ESPv2 部署至 CLOUD_RUN_SERVICE_NAME Cloud Run 服務。您可以在 OpenAPI 文件的 host 欄位中指定 CLOUD_RUN_HOSTNAME。

設定 Endpoints

您必須提供符合 OpenAPI 規範 v2.0 的 OpenAPI 文件，此文件須說明您後端服務的介面以及所有驗證需求。此外，您也必須加入內含各服務網址的 Google 專用欄位，這樣 ESPv2 才能取得叫用服務所需的資訊。如果您還不熟悉 OpenAPI，請參閱 OpenAPI 總覽瞭解詳情。

1. 建立名為 openapi-run.yaml 的文字檔案。(為方便起見，本頁會以該檔案名稱來稱呼 OpenAPI 文件，但是您可以依據需求替該檔案命名)。
2. 您的 Cloud Run 後端服務會定義於 x-google-backend 檔案最上方的 openapi-run.yaml 定義之中，例如：

   swagger: '2.0'
   info:
     title: Cloud Endpoints + Cloud Run
     description: Sample API on Cloud Endpoints with a Cloud Run backend
     version: 1.0.0
   host: CLOUD_RUN_HOSTNAME
   schemes:
     - https
   produces:
     - application/json
   x-google-backend:
     address: BACKEND_SERVICE_NAME
     protocol: h2
   paths:
     /hello:
       get:
         summary: Greet a user
         operationId: hello
         responses:
           '200':
             description: A successful response
             schema:
               type: string

   縮排對 yaml 格式來說很重要。例如，host 欄位必須與 info 位於相同層級。

3. 在 x-google-backend 區段的 address 欄位中，將 BACKEND_SERVICE_NAME 替換為您在「事前準備」一節的步驟 6 中建立的後端 Cloud Run 服務實際網址。

   這個範例假設您使用的是「快速入門導覽課程：部署預先建立的範例容器」中建立的 hello 後端服務。如果您使用的是其他後端 Cloud Run 服務，請將 BACKEND_SERVICE_NAME 替換為 Cloud Run 服務的網址。

4. 在 host 欄位中，指定 CLOUD_RUN_HOSTNAME，也就是在上述「保留 Cloud Run 主機名稱」一節中保留的網址主機名稱部分。請勿加上通訊協定 ID https://，例如：

   swagger: '2.0'
   info:
     title: Cloud Endpoints + Cloud Run
     description: Sample API on Cloud Endpoints with a Cloud Run backend
     version: 1.0.0
   host: gateway-12345-uc.a.run.app

5. 請注意 openapi-run.yaml 檔案中的 title 屬性值：

   title: Cloud Endpoints + Cloud Run

   部署設定後，title 屬性的值就會成為 Endpoints 服務的名稱。

6. 儲存 OpenAPI 文件。

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

部署 Endpoints 設定

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

如何部署 Endpoints 設定：

1. 確定您位於內含 OpenAPI 文件的目錄。

2. 上傳設定並建立代管服務。

   gcloud endpoints services deploy openapi-run.yaml \
     --project ESP_PROJECT_ID

   完成後，系統會建立新的 Endpoints 服務，並命名為您在 openapi-run.yaml 檔案的 host 欄位中指定的名稱。服務會根據您的 OpenAPI 文件進行設定。

   Service Management 在建立並設定服務時，會把資訊輸出到終端機。部署完成後，您將看到類似以下的訊息：

   Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]

   CONFIG_ID 是部署作業建立的 Endpoints 服務設定 ID。例如：

   Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]

   服務設定 ID 是由一個日期戳記和一個修訂版本編號所組成。如果您在同一天再次部署 openapi-run.yaml，服務設定 ID 中的修訂版本編號就會遞增。您可以在 Google Cloud 控制台的「Endpoints」>「Services」頁面中查看服務設定和部署記錄。

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

檢查必要服務

在大多數情況下，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 服務。

建構新的 ESPv2 映像檔

將 Endpoints 服務設定建構至新的 ESPv2 Docker 映像檔。您稍後會將這個映像檔部署至預留的 Cloud Run 服務。

如要將服務設定建構至新的 ESPv2 Docker 映像檔，請按照下列步驟操作：

1. 將這個指令碼下載到已安裝 gcloud CLI 的本機電腦。

2. 使用下列指令執行指令碼：

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
       -c CONFIG_ID -p ESP_PROJECT_ID

   針對 CLOUD_RUN_HOSTNAME，請指定您在保留 Cloud Run 主機名稱一節中保留的網址主機名稱。請勿加上通訊協定 ID https://，例如：

   例如：

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s gateway-12345-uc.a.run.app \
       -c 2019-02-01r0 -p your-project-id

3. 這個指令碼會使用 gcloud 指令下載服務設定，將服務設定建構至新的 ESPv2 映像檔，然後將新映像檔上傳至專案容器登錄。指令碼會自動使用最新的 ESPv2 版本，這可從輸出映像檔名稱中的 ESP_VERSION 標示得知。輸出圖片會上傳至：

   gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID

   例如：

   gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"

部署 ESPv2 容器

1. 使用上述建構的新映像檔部署 ESPv2 Cloud Run 服務。將 CLOUD_RUN_SERVICE_NAME 替換為您在「保留 Cloud Run 主機名稱」一節中，最初預留上述主機名稱時所用的 Cloud Run 服務名稱：

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --allow-unauthenticated \
     --platform managed \
     --project=ESP_PROJECT_ID

2. 如果您要設定 Endpoints 以使用其他 ESPv2 啟動選項，例如啟用 CORS，您可以傳送 ESPv2_ARGS 環境變數中的引數：

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
     --allow-unauthenticated \
     --platform managed \
     --project ESP_PROJECT_ID

   如要進一步瞭解如何設定 ESPv2_ARGS 環境變數，包括可用選項清單，以及如何指定多個選項的資訊，請參閱「Extensible Service Proxy V2 標記」。

3. 授予 ESPv2 權限，以便呼叫 Service Management 和 Service Control。

• 前往 Google Cloud 控制台的「Cloud Run」頁面。

前往 Cloud Run 頁面

• 您可以查看已部署的 Cloud Run 執行個體，以及與該執行個體相關聯的服務帳戶。
• 將必要權限授予服務帳戶：

gcloud projects add-iam-policy-binding PROJECT_NAME \
       --member "serviceAccount:SERVICE_ACCOUNT" \
       --role roles/servicemanagement.serviceController

詳情請參閱「 什麼是角色和權限？」一文。
4. 授予 ESPv2 權限，以便叫用 Cloud Run 服務。請對每個服務執行下列指令，在下列指令中：
   • 將 BACKEND_SERVICE_NAME 替換為叫用的 Cloud Run 服務名稱。如果您使用的是快速入門導覽課程：部署預先建立的範例容器中建立的後端服務，請使用 hello 做為這個值。
   • 將 ESP_PROJECT_NUMBER 替換為您為 ESPv2 建立的專案「編號」。找到此編號的方法之一，就是前往 Google Cloud 主控台的 IAM 頁面，然後找到「預設運算服務帳戶」，即 `member` 標記中使用的服務帳戶。

   gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
     --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
     --role "roles/run.invoker" \
     --platform managed \
     --project BACKEND_PROJECT_ID

詳情請參閱「使用 IAM 管理存取權」。

傳送要求至 API

本節會說明如何將要求傳送至您的 API。

1. 建立 Endpoints 服務名稱的環境變數，這是您在 OpenAPI 文件的 host 欄位中指定的名稱，例如：

   • Linux 或 macOS：

     export ENDPOINTS_HOST=gateway-12345-uc.a.run.app

   • Windows Powershell：

     $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

curl --request GET \
   --header "content-type:application/json" \
   "https://${ENDPOINTS_HOST}/hello"

(Invoke-WebRequest -Method GET `
    -Headers @{"content-type"="application/json"} `
    -URI "https://$Env:ENDPOINTS_HOST/hello").Content

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

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

追蹤 API 活動

1. 在 Google Cloud 主控台的「Endpoints」 >「Service」(服務) 頁面上，查看 API 的活動圖表。

   查看 Endpoints 活動圖表

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

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