透過 ESPv2 為 Cloud Run 設定 Cloud Endpoints gRPC

保留 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

bookstore-grpc 範例包含了需要在本機複製及設定的檔案。

1. 從您的服務 .proto 檔案中建立獨立的 protobuf 描述元檔案：
   1. 將範例存放區中的 bookstore.proto 複本儲存至目前的工作目錄。這個檔案定義了 Bookstore 服務的 API。
   2. 在工作目錄下建立以下目錄：mkdir generated_pb2
   3. 使用 protoc 通訊協定緩衝區編譯器建立描述元檔案 api_descriptor.pb。在儲存 bookstore.proto 的目錄中執行下列指令：

      python3 -m grpc_tools.protoc \
          --include_imports \
          --include_source_info \
          --proto_path=. \
          --descriptor_set_out=api_descriptor.pb \
          --python_out=generated_pb2 \
          --grpc_python_out=generated_pb2 \
          bookstore.proto

      在上述指令中，--proto_path 會設為目前的工作目錄。在您的 gRPC 建構環境中，如果您為 .proto 輸入檔案使用不同的目錄，請變更 --proto_path 以讓編譯器能夠搜尋您儲存 bookstore.proto 的目錄。

2. 在目前的工作目錄 (包含 bookstore.proto 的目錄) 中建立名為 api_config.yaml 的文字檔。為方便起見，本頁會以該檔案名稱來稱呼 gRPC API 設定文件，但您可以依據需求另外替檔案命名。在檔案中新增下列內容：

   # The configuration schema is defined by the service.proto file.
   # https://github.com/googleapis/googleapis/blob/master/google/api/service.proto
   
   type: google.api.Service
   config_version: 3
   name: CLOUD_RUN_HOSTNAME
   title: Cloud Endpoints + Cloud Run gRPC
   apis:
     - name: endpoints.examples.bookstore.Bookstore
   usage:
     rules:
     # ListShelves methods can be called without an API Key.
     - selector: endpoints.examples.bookstore.Bookstore.ListShelves
       allow_unregistered_calls: true
   backend:
     rules:
       - selector: "*"
         address: grpcs://BACKEND_HOST_NAME
   

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

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

4. 在 backend.rules 區段的 address 欄位中，將 BACKEND_HOST_NAME 替換為在事前準備中建立的實際 gRPC Bookstore Cloud Run 服務。

5. 請注意 api_config.yaml 檔案中的 title 屬性值：

   title: Cloud Endpoints + Cloud Run gRPC

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

6. 儲存 gRPC API 設定文件。

詳情請參閱設定 Endpoints。

部署 Endpoints 設定

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

1. 確認您所在的目錄有 api_descriptor.pb 和 api_config.yaml 檔案。
2. 確認 gcloud 指令列工具目前使用的預設專案，就是您要部署 Endpoints 設定的 Google Cloud 專案。請利用下列指令傳回的專案 ID 進行驗證，以確保系統沒有將服務建立在錯誤的專案中。

   gcloud config list project
   

   如要變更預設的專案，請執行下列指令：

   gcloud config set project YOUR_PROJECT_ID
   

3. 使用 Google Cloud CLI 部署 proto descriptor 檔案和設定檔：

   gcloud endpoints services deploy api_descriptor.pb api_config.yaml
   

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

   Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]

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

   Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
   

   在上方範例中，2017-02-13r0 是服務設定 ID，bookstore.endpoints.example-project.cloud.goog 則是服務名稱。服務設定 ID 是由一個日期戳記和一個修訂版本編號所組成。如果您在同一天再次部署 Endpoints 設定，服務設定 ID 中的修訂編號將會增加。

檢查必要服務

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

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

詳情請參閱部署 Endpoints 設定一文。

建構新的 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 權限，以便叫用 Cloud Run 服務。請對每個服務執行下列指令，在下列指令中：
   • 將 BACKEND_SERVICE_NAME 替換為叫用的 Cloud Run 服務名稱。如果您使用的是透過部署 `gcr.io/endpointsv2/python-grpc-bookstore-server:2` 建立的服務，請使用 python-grpc-bookstore-server 做為這個值。
   • 將 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，您可以使用以 Python 編寫的範例 gRPC 用戶端。

1. 複製託管 gRPC 用戶端程式碼的 git 存放區：

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

2. 變更您的工作目錄：

   cd python-docs-samples/endpoints/bookstore-grpc/

3. 安裝依附元件：

   pip3 install virtualenv
   virtualenv env
   source env/bin/activate
   pip3 install -r requirements.txt

4. 傳送要求至範例 API：

   python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true

   在 CLOUD_RUN_HOSTNAME 中指定 ESPv2 Cloud Run 服務的主機名稱，但不要加上通訊協定 ID。例如：

   python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true

   • 在「Endpoints」 >「Services」(服務) 頁面中查看 API 活動圖表。

     前往 Endpoints 服務頁面

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

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

     前往「Logs Explorer」頁面

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

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

追蹤 API 活動

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

   查看 Endpoints 活動圖表

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

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

   查看 Endpoints 要求記錄