适用于 gRPC 的 API Gateway 和 Cloud Run 使用入门

本页面介绍如何设置 API Gateway 以使用 gRPC 管理和保护 Cloud Run 后端服务。

任务列表

学习本教程时，请使用以下任务列表。使用 gRPC 为 Cloud Run 后端服务部署 API Gateway 所需的所有任务。

  1. 创建或选择 Google Cloud 项目。
  2. 如果您尚未部署自己的 Cloud Run，请部署示例后端 gRPC 服务。请参阅准备工作中的第 7 步。
  3. 启用所需的 API Gateway 服务。
  4. 创建描述您的 API 的 gRPC API 配置文档，并配置到您的 Cloud Run 的路由。请参阅使用 gRPC 配置 API 配置。
  5. 使用您的 API 配置部署 API Gateway。 请参阅部署 API Gateway。
  6. 通过发送请求测试您的 API 部署。 请参阅向 API 发送请求。
  7. 跟踪您的服务的活动。请参阅跟踪 API 活动。
  8. 避免向您的 Google Cloud 账号收取费用。请参阅清理。

准备工作

  1. 在 Google Cloud 控制台中，转到信息中心页面，然后选择或创建 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 Protocol Buffers 编译器创建描述符文件 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 Gateway

如需将 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 属性，而不使用协议标识符。例如：

    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. 在日志浏览器页面上查看 API 的请求日志。您可以在 Google Cloud 控制台的 API Gateway 页面上找到指向 Logs Explorer 页面的链接。

    转到“API Gateway”页面

    进入“API Gateway”页面后：

    1. 选择要查看的 API。
    2. 点击详情标签页。
    3. 点击日志下的链接。

您刚刚使用 gRPC 在 API Gateway 中部署并测试了 API！

清理

为避免系统因本快速入门中使用的资源向您的 Google Cloud 账号收取费用，您可以执行以下操作：

或者，您还可以删除本教程中使用的 Google Cloud 项目。