此页面由 Cloud Translation API 翻译。

使用入门：适用于采用 ESPv2 的代管式实例组的 Cloud Endpoints gRPC

OpenAPI | gRPC

本教程介绍如何在代管式实例组中使用 Extensible Service Proxy V2 (ESPv2) 部署一个简单的示例 gRPC 服务。

本教程使用 Python 版本的 bookstore-grpc 示例。如需其他语言的 gRPC 示例，请参阅后续步骤部分。

如需大致了解 Cloud Endpoints，请参阅 Endpoints 简介和 Endpoints 架构。

目标

学习本教程时，请使用以下概要任务列表。为确保请求成功发送到 API，您必须完成所有任务。

设置 Google Cloud 项目，然后下载所需的软件。请参阅准备工作。
复制并配置 bookstore-grpc 示例中的文件。请参阅配置 Endpoints。
部署 Endpoints 配置以创建 Endpoints 服务。请参阅部署 Endpoints 配置。
在代管式实例组后端上部署 API 和 ESPv2。请参阅部署 API 后端。
向 API 发送请求。请参阅向 API 发送请求。
避免系统向您的 Google Cloud 账号收费。请参阅清理。

费用

在本文档中，您将使用 Google Cloud 的以下收费组件：

您可使用价格计算器根据您的预计使用情况来估算费用。 Google Cloud 新用户可能有资格申请免费试用。

完成本文档中描述的任务后，您可以通过删除所创建的资源来避免继续计费。如需了解详情，请参阅清理。

准备工作

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

记下项目 ID，您稍后需要用到。
安装并初始化 Google Cloud CLI。
更新 gcloud CLI 并安装 Endpoints 组件：
```
gcloud components update
```
确保 Google Cloud CLI (gcloud) 有权访问您在 Google Cloud 上的数据和服务：
```
gcloud auth login
```
在浏览器打开的新标签页中，选择一个账号。
将默认项目设置为您的项目 ID。
```
gcloud config set project YOUR_PROJECT_ID
```
将 YOUR_PROJECT_ID 替换为项目 ID。如果您有其他 Google Cloud 项目，并且想使用“gcloud” 管理它们，请参阅管理 gcloud CLI 配置。
按照 gRPC Python 快速入门中的步骤安装 gRPC 和 gRPC 工具。

完成本文档中描述的任务后，您可以通过删除所创建的资源来避免继续计费。如需了解详情，请参阅清理。

配置 Endpoints

从 GitHub 克隆 bookstore-grpc 示例代码库。

要配置 Endpoints，请执行以下操作：

通过服务 .proto 文件创建一个独立的 protobuf 描述符文件：
1. 保存示例代码库中 bookstore.proto 的副本。此文件用于定义 Bookstore 服务的 API。
2. 创建以下目录：mkdir generated_pb2
3. 使用 protoc Protocol Buffers 编译器创建描述符文件 api_descriptor.pb。在您保存了 bookstore.proto 的目录中运行以下命令：
```
python -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 文件的目录。
创建 gRPC API 配置 YAML 文件：
1. 保存 api_config.yaml 文件的副本。此文件用于定义 Bookstore 服务的 gRPC API 配置。
2. 将 api_config.yaml 文件中的 MY_PROJECT_ID 替换为您的 Google Cloud 项目 ID。例如：
```
#
# Name of the service configuration.
#
name: bookstore.endpoints.example-project-12345.cloud.goog
```
  请注意，此文件中 apis.name 字段的值应该与 .proto 文件中的完全限定 API 名称完全匹配；否则部署将无法正常运行。Bookstore 服务是在 endpoints.examples.bookstore 包内的 bookstore.proto 中定义的。其完全限定的 API 名称为 endpoints.examples.bookstore.Bookstore，与其在 api_config.yaml 文件中的名称相同。
```
apis:
  - name: endpoints.examples.bookstore.Bookstore
```

如需了解更多信息，请参阅配置 Endpoints。

部署 Endpoints 配置

如需部署 Endpoints 配置，请使用 gcloud endpoints services deploy 命令。此命令使用 Service Management 创建一项托管式服务。

确保您位于 api_descriptor.pb 和 api_config.yaml 文件所在的目录中。
确认 gcloud 命令行工具当前使用的默认项目是您要向其部署 Endpoints 配置的 Google Cloud 项目。验证从以下命令返回的项目 ID，以确保不会在错误的项目中创建服务。
```
gcloud config list project
```
如果您需要更改默认项目，请运行以下命令：
```
gcloud config set project YOUR_PROJECT_ID
```
使用 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 中的修订版本号将递增。

检查所需服务

Endpoints 和 ESP 至少需要启用以下 Google 服务：

姓名	标题
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API
`endpoints.googleapis.com`	Google Cloud 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
gcloud services enable endpoints.googleapis.com

同时启用 Endpoints 服务：

gcloud services enable ENDPOINTS_SERVICE_NAME

要确定 ENDPOINTS_SERVICE_NAME，您可以执行以下任一操作：

部署 Endpoints 配置后，前往 Cloud 控制台中的 Endpoints 页面。服务名称列下显示了可能的 ENDPOINTS_SERVICE_NAME 列表。
对于 OpenAPI，ENDPOINTS_SERVICE_NAME 是您在 OpenAPI 规范的 host 字段中指定的值。对于 gRPC，ENDPOINTS_SERVICE_NAME 是您在 gRPC Endpoints 配置的 name 字段中指定的值。

如需详细了解 gcloud 命令，请参阅 gcloud 服务。

如果您收到错误消息，请参阅排查 Endpoints 配置部署问题。如需了解详情，请参阅部署 Endpoints 配置。

部署 API 后端

到目前为止，您已将 API 配置部署到 Service Management，但尚未部署将服务 API 后端的代码。本部分逐步介绍了如何在代管式实例组上安装 Docker，以及如何在 Docker 容器中运行 API 后端代码和 ESPv2。

创建实例模板

创建将用于创建一组虚拟机实例的模板。基于模板创建的每个实例都会启动 ESPv2 和后端应用服务器。

在 Google Cloud 控制台中，转到实例模板页面。

转到“实例模板”
点击创建实例模板。
在名称下，输入 load-balancing-espv2-template。
在机器配置下，将机器类型设置为 e2-micro。
在启动磁盘下，将映像设置为 Container Optimized OS stable version。
在防火墙下，选择允许 HTTP 流量。
点击管理、安全、磁盘、网络、单独租用以显示高级设置。

点击管理标签页。在自动化下，输入以下启动脚本。请务必更新 ENDPOINTS_SERVICE_NAME。

sudo docker network create --driver bridge esp_net
sudo docker run \
  --detach \
  --name=bookstore \
  --net=esp_net \
  gcr.io/endpointsv2/python-grpc-bookstore-server:1
sudo docker run \
  --detach \
  --name=esp \
  --publish=80:9000 \
  --net=esp_net \
  gcr.io/endpoints-release/endpoints-runtime:2 \
  --service=ENDPOINTS_SERVICE_NAME \
  --rollout_strategy=managed \
  --listener_port=9000 \
  --healthz=/healthz \
  --backend=grpc://bookstore:8000

该脚本会在实例启动时获取、安装和启动 echo 应用服务器和 ESPv2 代理服务器。

点击创建。

等到模板创建完成后再继续。

创建区域托管实例组

如需运行应用，请使用实例模板创建区域代管式实例组：

在 Google Cloud Console 中，转到实例组页面。

进入“实例组”
点击创建实例组。
在名称下，输入 load-balancing-espv2-group。
在位置下，选择多个地区。

专家提示：为确保您的应用在极端事件（如地区服务中断）期间可用，Compute Engine 建议您跨多个地区分发应用。
在区域下，选择 us-central1。
点击配置地区下拉菜单以显示地区。选择以下地区：
- us-central1-b
- us-central1-c
- us-central1-f
在实例模板下，选择 load-balancing-espv2-template。
在自动扩缩下，选择不自动调节。
将实例数设置为 3。

专家提示：在创建区域代管式实例组时，Compute Engine 建议您预配足够的实例，以便在任何一个地区中的所有实例都不可用时，其余实例仍然达到所需的最少实例数。不过，如果预配的实例数量超出您的需求，可能会产生额外的费用。如需了解详情，请参阅选择实例组规模以确保可用性。
在实例重新分配下，选择开启。
在自动修复和健康检查下，选择不检查健康状况。
点击创建。这会使您返回实例组页面。
注意：您可能需要等待几分钟，直到组中的所有实例都处于运行状态并准备好显示 Web 应用。

创建负载平衡器

本部分介绍创建将 TCP 流量定向到您的实例组的地区负载平衡器所需的步骤。

在 Google Cloud 控制台中，进入创建负载均衡器页面。

转到“创建负载平衡器”
在 TCP 负载平衡下，点击开始配置。
在面向互联网或仅限内部下，选择从互联网到我的虚拟机。
在多区域或单区域下，选择仅单个区域。
在后端类型下，选择后端服务。
点击继续。
在名称下，输入 espv2-load-balancer。
在后端配置下，选择区域 us-central1。
选择实例组 load-balancing-espv2-group。
在健康检查下，创建新的健康检查。
- 在名称下，输入 espv2-load-balancer-check。
- 确认协议为 TCP，端口为 80。
在前端配置下，输入端口号 80。
在检查并最终确定下，验证
- 实例组是 load-balancing-espv2-group。
- 地区是 us-central1。
- 协议是 TCP。
- IP:端口是 EPHEMERAL:80。
负载平衡器创建后，从负载平衡器页面查找 IP 地址。

转到“负载平衡器”

向 API 发送请求

如果您从运行 Docker 容器的同一实例中发送请求，则可以将 SERVER_IP 替换为 localhost。否则，将 SERVER_IP 替换为实例的外部 IP。

您可以通过运行以下命令找到外部 IP 地址：

gcloud compute instances list

要向示例 API 发送请求，您可以使用以 Python 编写的示例 gRPC 客户端。

克隆托管 gRPC 客户端代码的 Git 代码库：

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

切换您的工作目录：

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

安装依赖项：

pip install virtualenv
virtualenv env
source env/bin/activate
python -m pip install -r requirements.txt

向示例 API 发送一个请求：
```
python bookstore_client.py --host SERVER_IP --port 80
```
- 在 Endpoints > 服务页面中查看 API 的活动图表。
  
  转到“Endpoints 服务”页面
  
  请求可能需要一些时间才能体现在图表中。
- 在“日志浏览器”页面中查看 API 的请求日志。
  
  转到“日志浏览器”页面

如果未获得成功响应，请参阅排查响应错误。

您刚刚在 Endpoints 中部署并测试了一个 API！

清除数据

为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用，请删除包含这些资源的项目，或者保留项目但删除各个资源。

确保 gcloud CLI (gcloud) 有权访问您的数据和服务：
```
gcloud auth login
```
输入以下命令，以显示 Google Cloud 项目的 ID：
```
gcloud projects list
```
使用上一步中相应的项目 ID，将默认 Google Cloud 项目设置为您的应用所在的项目：
```
gcloud config set project [YOUR_PROJECT_ID]
```
获取 Google Cloud 项目中所有托管式服务的名称：
```
gcloud endpoints services list
```
从 Service Management 中删除服务：将 SERVICE_NAME 替换为您要移除的服务的名称。
```
gcloud endpoints services delete SERVICE_NAME
```
运行 gcloud endpoints services delete 不会立即删除托管式服务。Service Management 会将该托管式服务停用 30 天，以便您在需要时对其进行恢复。30 天后，Service Management 将永久删除该服务。
转到负载平衡器页面。

转到“负载平衡器”

使用健康检查 espv2-load-balancer-check 删除负载均衡器 espv2-load-balancer。
转到实例组页面。

转到“实例组”

删除 load-balancing-espv2-group
转到实例模板页面。

转到“实例模板”

删除load-balancing-espv2-template。

后续步骤

了解如何为 Endpoints 配置您自己的 gRPC API。
仔细查看 GitHub 上的 Bookstore 示例。客户端和服务器均有 Python 版和 Java 版。
GitHub 上以下列语言提供了 getting-started-grpc 示例：
- Java
- Python
- Ruby
- Go
- Node.js