本教程介绍如何在代管式实例组 (MIG) 上配置和部署在预建 Docker 容器中运行的示例 API 和 Extensible Service Proxy V2 (ESPv2)。
示例代码的 REST API 是使用 OpenAPI 规范描述的。本教程还介绍如何创建 API 密钥,以及在向 API 发送请求时如何使用此密钥。
如需大致了解 Cloud Endpoints,请参阅关于 Endpoints 和 Endpoints 架构。
目标
学习本教程时,请使用以下概要任务列表。为确保请求成功发送到 API,您必须完成所有任务。- 设置 Google Cloud 项目。请参阅准备工作。
- 下载示例代码。请参阅获取示例代码。
- 配置
openapi.yaml
文件,该文件用于配置 Endpoints。请参阅配置 Endpoints。 - 部署 Endpoints 配置以创建 Endpoints 服务。请参阅部署 Endpoints 配置。
- 在代管式实例组 (MIG) 后端上部署 API 和 ESPv2。 请参阅部署 API 后端。
- 使用 IP 地址向 API 发送请求。请参阅使用 IP 地址发送请求。
- 为示例 API 配置 DNS 记录。请参阅为 Endpoints 配置 DNS。
- 使用完全限定的域名向 API 发送请求。请参阅使用 FQDN 发送请求。
- 跟踪 API 活动。请参阅跟踪 API 活动。
- 避免系统向您的 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.
-
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.
-
Make sure that billing is enabled for your Google Cloud project.
- 记下项目 ID,您稍后需要用到。
-
您需要一个应用来向示例 API 发送请求。
- Linux 和 macOS 用户:本教程提供了一个使用
curl
的示例,它通常已预装在您的操作系统中。如果您没有curl
,可以从curl
版本和下载页面中下载。 - Windows 用户:本教程提供了一个使用
Invoke-WebRequest
的示例,PowerShell 3.0 及更高版本支持该命令。
- Linux 和 macOS 用户:本教程提供了一个使用
- 下载 Google Cloud CLI。
-
更新 gcloud CLI 并安装端点
组件。
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 配置。
完成本文档中描述的任务后,您可以通过删除所创建的资源来避免继续计费。如需了解详情,请参阅清理。
下载示例代码
将示例代码下载到本地机器。
如需克隆或下载示例 API,请执行以下操作:
- 将示例应用代码库克隆到本地机器:
git clone https://github.com/GoogleCloudPlatform/java-docs-samples
或者,下载该示例的 zip 文件并将其解压缩。
- 转到包含示例代码的目录:
cd java-docs-samples/endpoints/getting-started
如需克隆或下载示例 API,请执行以下操作:
- 将示例应用代码库克隆到本地机器:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples
或者,下载该示例的 zip 文件并将其解压缩。
- 转到包含示例代码的目录:
cd python-docs-samples/endpoints/getting-started
如需克隆或下载示例 API,请执行以下操作:
- 确保已设置
GOPATH
环境变量。 - 将示例应用代码库克隆到本地机器:
go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
- 转到包含示例代码的目录:
cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
如需克隆或下载示例 API,请执行以下操作:
- 将示例应用代码库克隆到本地机器:
git clone https://github.com/GoogleCloudPlatform/php-docs-samples
或者,下载该示例的 zip 文件并将其解压缩。
- 转到包含示例代码的目录:
cd php-docs-samples/endpoints/getting-started
如需克隆或下载示例 API,请执行以下操作:
- 将示例应用代码库克隆到本地机器:
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples
或者,下载该示例的 zip 文件并将其解压缩。
- 转到包含示例代码的目录:
cd ruby-docs-samples/endpoints/getting-started
如需克隆或下载示例 API,请执行以下操作:
- 将示例应用代码库克隆到本地机器:
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples
或者,下载该示例的 zip 文件并将其解压缩。
- 切换到包含示例代码的目录:
cd nodejs-docs-samples/endpoints/getting-started
配置 Endpoints
示例代码包括 OpenAPI 配置文件 openapi.yaml
,该文件基于 OpenAPI 规范 v2.0。您可以在本地机器上配置和部署 openapi.yaml
。
要配置 Endpoints,请执行以下操作:
- 在示例代码目录中,打开
openapi.yaml
配置文件。Java Python Go PHP Ruby NodeJS 请注意以下事项:
- 配置示例显示了
host
字段附近的几行内容,您需要修改这些内容。如需将openapi.yaml
文件部署到 Endpoints,您需要完整的 OpenAPI 文档。 - 示例
openapi.yaml
文件包含用于配置身份验证的部分(本教程不需要)。您无需使用 YOUR-SERVICE-ACCOUNT-EMAIL 和 YOUR-CLIENT-ID 配置这些行。 - OpenAPI 是一种与语言无关的规范。为方便起见,每种语言的 GitHub 存储库中的
getting-started
示例均包含相同的openapi.yaml
文件。
- 配置示例显示了
- 将
host
字段中的文本替换为 Endpoints 服务名称,该名称应采用以下格式:host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。例如:
host: "echo-api.endpoints.example-project-12345.cloud.goog"
请注意,echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
是 Endpoints 服务名称。该名称不是您用于向 API 发送请求的完全限定域名 (FQDN)。
如需了解 OpenAPI 文档中 Endpoints 所需的字段,请参阅配置 Endpoints。
为了能够使用 IP 地址向示例 API 成功发送请求,您需要完成以下所有配置步骤。在完成这些步骤后,请参阅配置 Endpoints DNS,了解如何将 echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
配置为 FQDN。
部署 Endpoints 配置
如需部署 Endpoints 配置,请使用 gcloud endpoints
services deploy
命令。此命令使用 Service Management 创建一项托管式服务。
如需部署 Endpoints 配置,请执行以下操作:
- 确保您位于
endpoints/getting-started
目录中。 - 上传配置并创建托管式服务:
gcloud endpoints services deploy openapi.yaml
然后,gcloud
命令会调用 Service Management API,以便使用您在 openapi.yaml
文件的 host
字段中指定的名称创建托管式服务。Service Management 会根据 openapi.yaml
文件中的设置来配置服务。如果您对 openapi.yaml
做出更改,则必须重新部署该文件才能更新 Endpoints 服务。
在创建和配置服务时,Service Management 会向终端输出信息。您尽可忽略有关 openapi.yaml
文件中的路径未要求使用 API 密钥的警告。完成服务配置后,Service Management 将显示如下所示的消息,其中包含服务配置 ID 和服务名称:
Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]
在上面的示例中,2017-02-13r0
是服务配置 ID,echo-api.endpoints.example-project-12345.cloud.goog
是 Endpoints 服务。服务配置 ID 由日期戳后跟一个修订版本号组成。如果您在同一天再次部署 openapi.yaml
文件,服务配置 ID 中的修订版本号将递增。您可以查看
端点上的 Endpoints 服务配置 >
Google Cloud 控制台中的服务页面。
如果您收到错误消息,请参阅排查 Endpoints 配置部署问题。
检查所需服务
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.comgcloud 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
服务。
部署 API 后端
创建实例模板
创建将用于创建一组虚拟机实例的模板。基于模板创建的每个实例都会启动 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=echo \ --net=esp_net \ gcr.io/google-samples/echo-python:1.0 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=echo:8080
该脚本会在实例启动时获取、安装和启动 echo 应用服务器和 ESPv2 代理服务器。
点击创建。
等到模板创建完成后再继续。
创建区域托管实例组
如需运行应用,请使用实例模板创建区域代管式实例组:
在 Google Cloud Console 中,转到实例组页面。
点击创建实例组。
在名称下,输入
load-balancing-espv2-group
。在位置下,选择多个地区。
在区域下,选择 us-central1。
点击配置地区下拉菜单以显示地区。 选择以下地区:
- us-central1-b
- us-central1-c
- us-central1-f
在实例模板下,选择
load-balancing-espv2-template
。在自动扩缩下,选择不自动调节。
将实例数设置为
3
。在实例重新分配下,选择开启。
在自动修复和健康检查下,选择不检查健康状况。
点击创建。这会使您返回实例组页面。
创建负载平衡器
本部分介绍创建将 HTTP 流量定向到实例组的全局负载平衡器所需的步骤。此负载平衡器使用前端接收传入流量,使用后端将此流量分配到运行状况良好的实例。由于负载均衡器由多个组件组成,因此此任务分为下列几部分:
- 后端配置
- 前端配置
- 检查并最终确定
完成创建负载平衡器的所有步骤。
在 Google Cloud 控制台中,进入创建负载均衡器页面。
在应用负载均衡器 (HTTP/S) 部分,点击开始配置。
在面向互联网或仅限内部下,选择从互联网到我的虚拟机。然后,点击继续。
对于负载平衡器的名称,请输入
espv2-load-balancer
。
后端配置
- 在创建全球外部应用负载均衡器页面的左侧面板中,点击后端配置。
- 点击创建或选择后端服务和后端存储桶以打开下拉菜单。点击后端服务,然后点击创建后端服务。
- 在新窗口中,对于后端应用的名称,输入
espv2-backend
。 - 将实例组设置为
load-balancing-espv2-group
。 - 将端口号设置为
80
。这允许 HTTP 流量在负载均衡器和实例组之间传输。 - 在平衡模式下,选择利用率。
- 点击完成以创建后端。
为负载均衡器的后端创建健康检查:
- 在健康检查下,从下拉菜单中选择创建健康检查(或另创建一项健康检查)。系统会打开一个新窗口。
- 在新窗口中的名称下,输入
espv2-load-balancer-check
。 - 将协议设置为 HTTP。
- 在端口下,输入
80
。 - 对于本教程,将请求路径设置为
/healthz
,这是 ESPv2 应该响应的路径。 设置以下运行状况判断标准:
- 将检查间隔设置为
3
秒。这定义了从一次探测开始到下一次探测开始之间的时间间隔。 - 将超时设置为
3
秒。这定义了 Google Cloud 等待探测响应的时间。其值必须小于或等于检查间隔时间。 - 将状况良好判断阈值设置为连续成功
2
次。这定义了要将实例视为运行状况良好必须成功的连续探测次数。 - 将状况不佳判断阈值设置为连续失败
2
次。这定义了要将实例视为运行状况不佳所必须失败的连续探测次数。
- 将检查间隔设置为
点击保存并继续以创建健康检查。
点击创建以创建后端服务。
前端配置
- 在创建全球外部应用负载均衡器页面的左侧面板中,点击前端配置。
- 在前端配置页面的名称下,输入
espv2-ipv4-frontend
。 - 将协议设置为
HTTP
。 - 将端口设置为
80
。 - 点击完成以创建前端。
检查并最终确定
在创建负载均衡器之前验证负载均衡设置:
- 在创建全球外部应用负载均衡器页面的左侧面板中,点击检查并最终确定。
在检查并最终确定页面上,验证以下后端设置:
- 后端服务是
espv2-backend
。 - 端点协议是
HTTP
。 - 健康检查是
espv2-load-balancer-check
。 - 实例组是
load-balancing-espv2-group
。
- 后端服务是
在同一页面上,验证前端是否使用协议为
HTTP
的 IP 地址。
在创建全球外部应用负载均衡器页面的左侧面板中,点击创建以完成负载均衡器的创建。
您可能需要等待几分钟,以便负载平衡器创建完成。
负载平衡器创建后,从负载平衡器页面查找 IP 地址。
使用 IP 地址发送请求
示例 API 和 ESPv2 在已部署的后端上运行后,您可以从本地机器向 API 发送请求。
创建 API 密钥并设置环境变量
示例代码需要 API 密钥。为简化请求,请为 API 密钥设置环境变量。
在您用于 API 的同一 Google Cloud 项目中,在 API 凭据页面上创建 API 密钥。如果要在其他 Google Cloud 项目中创建 API 密钥,请参阅在 Google Cloud 项目中启用 API。
- 点击创建凭据,然后选择 API 密钥。
- 将密钥复制到剪贴板。
- 点击关闭。
- 在本地计算机上,粘贴 API 密钥以将其分配给环境变量:
- 在 Linux 或 macOS 中:
export ENDPOINTS_KEY=AIza...
- 在 Windows PowerShell 中:
$Env:ENDPOINTS_KEY="AIza..."
- 在 Linux 或 macOS 中:
发送请求
Linux 或 macOS
通过 curl
使用之前设置的 ENDPOINTS_KEY 环境变量发送 HTTP 请求。将 IP_ADDRESS 替换为实例的外部 IP 地址。
curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"
在上面的 curl
中:
--data
选项用于指定要发布到 API 的数据。--header
选项用于指定数据采用 JSON 格式。
PowerShell
通过 Invoke-WebRequest
使用之前设置的 ENDPOINTS_KEY
环境变量发送 HTTP 请求。将 IP_ADDRESS 替换为实例的外部 IP 地址。
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' ` -Headers @{"content-type"="application/json"} ` -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content
在上面的示例中,前两行以反引号结束。将示例粘贴到 PowerShell 中时,请确保反引号后面没有空格。 如需了解示例请求中使用的选项,请参阅 Microsoft 文档中的 Invoke-WebRequest。
第三方应用
您可以使用第三方应用(如 Chrome 浏览器扩展程序 Postman)发送请求:
- 选择
POST
作为 HTTP 谓词。 - 对于标头,请选择键
content-type
和值application/json
。 - 对于正文,请输入以下内容:
{"message":"hello world"}
-
在网址中,使用实际的 API 密钥,而非环境变量。例如:
http://192.0.2.0:80/echo?key=AIza...
API 会回显您发送的消息,并以如下内容作为响应:
{
"message": "hello world"
}
如果未成功收到响应,请参阅排查响应错误。
您刚刚在 Endpoints 中部署并测试了一个 API!
为 Endpoints 配置 DNS
由于 API 的 Endpoints 服务名称在 .endpoints.YOUR_PROJECT_ID.cloud.goog
域名中,因此您在 openapi.yaml
文件中稍微更改一下配置,即可将该名称用作完全限定的域名 (FQDN)。这样,您就可使用 echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
(而非 IP 地址)向示例 API 发送请求。
如需配置 Endpoints DNS,请执行以下操作:
- 打开 OpenAPI 配置文件
openapi.yaml
,并在该文件的顶层添加x-google-endpoints
属性(请勿使用缩进或嵌套结构),如以下代码段所示:host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog" x-google-endpoints: - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog" target: "IP_ADDRESS"
- 在
name
属性中,将 YOUR_PROJECT_ID 替换为您的项目 ID。 - 在
target
属性中,将 IP_ADDRESS 替换为您向示例 API 发送请求时使用的 IP 地址。 - 将更新后的 OpenAPI 配置文件部署到 Service Management:
gcloud endpoints services deploy openapi.yaml
例如,假设 openapi.yaml
文件进行了以下配置:
host: "echo-api.endpoints.example-project-12345.cloud.goog" x-google-endpoints: - name: "echo-api.endpoints.example-project-12345.cloud.goog" target: "192.0.2.1"
使用上述 gcloud
命令部署 openapi.yaml
文件时,Service Management 会创建一条 DNS A 记录 echo-api.endpoints.my-project-id.cloud.goog
,该记录将解析为目标 IP 地址 192.0.2.1
。新 DNS 配置可能需要几分钟的时间才能传播。
配置 SSL
如需详细了解如何配置 DNS 和 SSL,请参阅为 Endpoints 启用 SSL。
使用 FQDN 发送请求
在为示例 API 配置 DNS 记录后,请使用 FQDN(将 YOUR_PROJECT_ID 替换为您的项目 ID)和先前设置的 ENDPOINTS_KEY 环境变量向该 API 发送请求:- 在 Linux 或 Mac OS 中:
curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"
- 在 Windows PowerShell 中:
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content
跟踪 API 活动
要跟踪 API 活动,请执行以下操作:
- 在 Endpoints > 服务页面中查看您的 API 的活动图表。
请求可能需要一些时间才能体现在图表中。 - 在“日志浏览器”页面中查看 API 的请求日志。
为 API 创建开发者门户
可使用 Cloud Endpoints 门户创建开发者门户,该门户是一个可用于与示例 API 进行交互的网站。如需了解详情,请参阅 Cloud Endpoints 门户概览。
清除数据
为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用,请删除包含这些资源的项目,或者保留项目但删除各个资源。
确保 gcloud CLI (
gcloud
) 有权访问您在 Google Cloud 上的数据和服务: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-backend
和健康检查espv2-load-balancer-check
的负载均衡器espv2-load-balancer
。转到实例组页面。
删除
load-balancing-espv2-group
转到实例模板页面。
删除
load-balancing-espv2-template
。