API Gateway 和 Cloud Run for gRPC 使用入门
本页介绍了如何设置 API Gateway 以通过 gRPC 管理和保护 Cloud Run 后端服务。
任务列表
学习本教程时,请使用以下任务列表。使用 gRPC 为 Cloud Run 后端服务部署 API Gateway 所需的所有任务。
- 创建或选择 Google Cloud 项目。
- 如果您尚未部署自己的 Cloud Run,请部署示例后端 gRPC 服务。请参阅准备工作中的第 7 步。
- 启用所需的 API Gateway 服务。
- 创建描述您的 API 的 gRPC API 配置文档,并配置到您的 Cloud Run 的路由。请参阅使用 gRPC 配置 API 配置。
- 使用您的 API 配置部署 API Gateway。 请参阅部署 API Gateway。
- 通过发送请求测试您的 API 部署。 请参阅向 API 发送请求。
- 跟踪您的服务的活动。请参阅跟踪 API 活动。
- 避免向您的 Google Cloud 账号收取费用。请参阅清理。
准备工作
在 Google Cloud 控制台中,转到信息中心页面,然后选择或创建 Google Cloud 项目。
确保您的项目已启用结算功能。
请记下项目 ID,您稍后需要用到它。在本页面的其余部分,此项目 ID 称为 PROJECT_ID。
请记下项目编号,您稍后会用到它。在本页面的其余部分,此项目编号称为 PROJECT_NUMBER。
下载并安装 Google Cloud CLI。
按照 gRPC Python 快速入门中的步骤安装 gRPC 和 gRPC 工具。
部署 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.comgcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
如需详细了解 gcloud
服务,请参阅 gcloud
服务。
使用 gRPC 创建 API 配置
bookstore-grpc
示例包含您需要在本地复制并进行配置的文件。
- 通过服务
.proto
文件创建一个独立的 protobuf 描述符文件:- 将示例代码库中
bookstore.proto
的副本保存到当前工作目录。此文件用于定义 Bookstore 服务的 API。 - 在工作目录下创建以下目录:
mkdir generated_pb2
- 使用
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
文件的目录。
- 将示例代码库中
-
在您当前的工作目录(即
bookstore.proto
所在的目录)中创建名为api_config.yaml
的文本文件。为方便起见,本页面用此文件名指代 gRPC API 配置文档,但如果您愿意的话,也可以改用其他名称。将以下内容添加到文件中: 缩进对于 yaml 格式非常重要。例如,# 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
name
字段必须与“type
”处于同一级别。 在
name
字段中,名为*.apigateway.PROJECT_ID.cloud.goog
的服务,其中 PROJECT_ID 是您的 Google Cloud 项目 ID 的名称。在
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 服务的网址。
- 保存您的 gRPC API 配置文档。
- 创建 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 客户端。
克隆托管 gRPC 客户端代码的 Git 代码库:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
更改您的工作目录:
cd python-docs-samples/endpoints/bookstore-grpc/
安装依赖项:
pip3 install virtualenv
virtualenv env
source env/bin/activate
pip3 install -r requirements.txt
向示例 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 活动
在 API Gateway 页面上查看 API 的活动图表, Google Cloud 控制台。点击您的 API 以在概览页面上查看其活动图表。请求可能要过一些时间才能反映在图表中。
在日志浏览器页面上查看 API 的请求日志。指向 日志浏览器页面位于 Google Cloud 控制台。
进入“API Gateway”页面后:- 选择要查看的 API。
- 点击详情标签页。
- 点击日志下的链接。
您刚刚使用 gRPC 在 API Gateway 中部署并测试了 API!
清理
为避免系统因本快速入门中使用的资源向您的 Google Cloud 账号收取费用,您可以执行以下操作:
或者,您还可以删除本教程中使用的 Google Cloud 项目。