開始使用 API Gateway 搭配 Cloud Run 和 gRPC

本頁面說明如何設定 API Gateway，以便透過 gRPC 管理及保護 Cloud Run 後端服務。

工作清單

在逐步進行本教學課程時，請使用以下工作清單。您必須完成所有工作，才能為使用 gRPC 的 Cloud Run 後端服務部署 API 閘道。

  1. 建立或選取 Google Cloud 專案。
  2. 如果尚未部署您自己的 Cloud Run，請部署範例後端 gRPC 服務。請參閱「事前準備」中的步驟 7。
  3. 啟用必要的 API Gateway 服務。
  4. 建立說明 API 的 gRPC API 設定文件，並設定連至 Cloud Run 的路徑。請參閱「使用 gRPC 設定 API 設定」一文。
  5. 使用 API 設定部署 API 閘道。請參閱「部署 API 閘道」。
  6. 傳送要求來測試 API 部署作業。請參閱傳送要求至 API 一節。
  7. 追蹤您服務的活動。請參閱追蹤 API 活動一節。
  8. 避免系統向您的 Google Cloud 帳戶收取費用。請參閱「清除所用資源」一節。

事前準備

  1. 在 Google Cloud 控制台中，前往「Dashboard」頁面，選取或建立 Google Cloud 專案。

    前往資訊主頁

  2. 請確認您已為專案啟用計費功能。

    啟用計費功能

  3. 記下專案 ID，後續步驟將會用到。在本頁其餘部分，這個專案 ID 又稱為 PROJECT_ID。

  4. 記下專案編號，後續步驟將會用到。在本頁其餘部分，這個專案編號又稱為 PROJECT_NUMBER。

  5. 下載並安裝 Google Cloud CLI。

    下載 gcloud CLI

  6. 按照 gRPC Python 快速入門導覽課程中的步驟安裝 gRPC 和 gRPC 工具。

  7. 部署 python-grpc-bookstore-server 範例後端 gRPC Cloud Run 服務，以便搭配本教學課程使用。gRPC 服務會使用下列容器映像檔：

    gcr.io/endpointsv2/python-grpc-bookstore-server:2

    請按照「快速入門：部署預先建立的範例容器」一文中的步驟部署服務。請務必將快速入門課程中指定的容器映像檔替換為 gcr.io/endpointsv2/python-grpc-bookstore-server:2

    請記下服務網址，以及服務部署的地區和專案 ID。

啟用必要服務

API Gateway 要求您啟用下列 Google 服務：

名稱 標題
apigateway.googleapis.com API Gateway API
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

如要確認必要服務已啟用，請執行：

gcloud services list

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

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

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

使用 gRPC 建立 API 設定

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: "*.apigateway.PROJECT_ID.cloud.goog"
title: API Gateway + 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://python-grpc-bookstore-server-HASH-uc.a.run.app
     縮排對 yaml 格式來說很重要。例如，name 欄位必須與 type 位於相同層級。
  3. 在 name 欄位中，指定名為 *.apigateway.PROJECT_ID.cloud.goog 的服務，其中 PROJECT_ID 是您的 Google Cloud 專案 ID 名稱。

  4. 在 backend.rules 區段的 address 欄位中，將 grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app 替換為 python-grpc-bookstore-server 後端 gRPC Cloud Run 服務的實際網址，其中 HASH 是建立服務時產生的不重複雜湊碼。

    這個範例假設您使用的是「開始之前」一節中建立的 gRPC Bookstore 後端服務。如有需要，請將這個值替換為 Cloud Run 服務的網址。

  5. 儲存 gRPC API 設定文件。
  6. 建立 API 設定：
    gcloud api-gateway api-configs create CONFIG_ID \
--api=API_ID --project=PROJECT_ID \
--grpc-files=api_descriptor.pb,api_config.yaml
     其中：
    • CONFIG_ID 會指定 API 設定的名稱。
    • API_ID 會指定 API 名稱。
    • PROJECT_ID 會指定 Google Cloud 專案的名稱。
    例如： 
    gcloud api-gateway api-configs create grpc-config \
--api=grpc-test --project=my-test-project \
--grpc-files=api_descriptor.pb,api_config.yaml

部署 API 閘道

如要將 gRPC API 設定部署至閘道，請執行下列指令：

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

其中：

  • GATEWAY_ID 會指定閘道的名稱。
  • API_ID 會指定與此閘道相關聯的 API Gateway API 名稱。
  • CONFIG_ID 會指定部署至閘道的 API 設定名稱。

  • GCP_REGION 是部署閘道的Google Cloud 區域。

  • PROJECT_ID 會指定 Google Cloud 專案的名稱。

例如：

gcloud api-gateway gateways create bookstore-grpc \
  --api=grpc-test --api-config=grpc-config \
  --location=us-central1 --project=my-project

成功完成後，您可以使用下列指令查看網關的詳細資料：

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

請記下這項指令輸出內容中的 defaultHostname 屬性值。這是網關網址的主機名稱部分，您會在下一個步驟中使用這個值測試部署作業。

例如：

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

傳送要求至 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=DEFAULT_HOSTNAME --port 443 --use_tls true

    在 DEFAULT_HOSTNAME 中指定閘道的 defaultHostname 屬性，但不含通訊協定 ID。例如：

    python3 bookstore_client.py --host=my-gateway-a12bcd345e67f89g0h.uc.gateway.dev --port 443 --use_tls true

追蹤 API 活動

  1. 在Google Cloud 主控台的「API Gateway」頁面中查看 API 活動圖表。按一下 API，即可在「總覽」頁面中查看活動圖表。要求可能需要一些時間才能反映在圖表中。

  2. 在「Logs Explorer」頁面中查看您的 API 要求記錄。您可以在Google Cloud 控制台的「API Gateway」頁面中找到「Logs Explorer」頁面的連結。

    前往 API Gateway

    進入 API Gateway 頁面後，請按照下列步驟操作：

    1. 選取要查看的 API。
    2. 按一下 [Details] (詳細資料) 分頁標籤。
    3. 按一下「Logs」下方的連結。

您已在 API 閘道中部署並測試了使用 gRPC 的 API！

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取您在本快速入門中所用資源的費用，您可以：

或者，您也可以刪除本教學課程中使用的 Google Cloud 專案。