使用入门：Compute Engine 上使用 ESPv2 的 Cloud Endpoints

创建 Compute Engine 实例

要创建 Compute Engine 实例，请执行以下操作：

1. In the Google Cloud console, go to the Create an instance page.

   Go to Create an instance

2. 在防火墙部分，选择 允许 HTTP 流量和允许 HTTPS 流量。
3. 如需创建虚拟机，请点击创建。



实例启动需要您稍等片刻。准备就绪后，该实例将在虚拟机实例页面上列出，并显示绿色状态图标。

4. 确保您可以连接到虚拟机实例。
   1. In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.
   2. 现在，您可以使用终端在 Debian 实例上运行 Linux 命令。
   3. 输入 exit 以断开与该实例的连接。
5. 请记下实例名称、地区和外部 IP 地址，以供稍后使用。

下载示例代码

将示例代码下载到本地机器。

配置 Endpoints

示例代码包括 OpenAPI 配置文件 openapi.yaml，该文件基于 OpenAPI 规范 v2.0。您可以在本地机器上配置和部署 openapi.yaml。 要配置 Endpoints，请执行以下操作：

1. 在示例代码目录中，打开 openapi.yaml 配置文件。
   Java

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Python

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Go

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   PHP

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Ruby

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   NodeJS

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   请注意以下事项：

   • 配置示例显示了 host 字段附近的几行内容，您需要修改这些内容。如需将 openapi.yaml 文件部署到 Endpoints，您需要完整的 OpenAPI 文档。
   • 示例 openapi.yaml 文件包含用于配置身份验证的部分（本教程不需要）。您无需使用 YOUR-SERVICE-ACCOUNT-EMAIL 和 YOUR-CLIENT-ID 配置这些行。
   • OpenAPI 是一种与语言无关的规范。为方便起见，每种语言的 GitHub 存储库中的 getting-started 示例均包含相同的 openapi.yaml 文件。

2. 将 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 配置，请执行以下操作：

1. 确保您位于 endpoints/getting-started 目录中。
2. 上传配置并创建托管式服务：

   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 中的修订版本号将递增。您可以在 Google Cloud 控制台中的 Endpoints > Services 页面上查看 Endpoints 服务配置。

如果您收到错误消息，请参阅排查 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

同时启用 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 后端

到目前为止，您已将 OpenAPI 文档部署到 Service Management，但尚未部署为 API 后端提供服务的代码。本部分逐步介绍了如何在虚拟机实例上安装 Docker，以及如何在 Docker 容器中运行 API 后端代码和 ESPv2。

检查所需权限

• 在 Google Cloud 控制台中，前往 Compute Engine 实例页面。

  转到 Compute Engine 页面

• 从列表中选择实例。
• 您可以看到关联的服务账号及其拥有的权限。

• 向服务账号授予所需权限：

  gcloud projects add-iam-policy-binding PROJECT_NAME \
    --member "serviceAccount:SERVICE_ACCOUNT" \
    --role roles/servicemanagement.serviceController
  

  如需了解详情，请参阅什么是角色和权限？

在虚拟机实例上安装 Docker

如需在虚拟机实例上安装 Docker，请执行以下操作：

1. 运行以下命令，为项目设置地区：

   gcloud config set compute/zone YOUR_INSTANCE_ZONE
   

   将 YOUR_INSTANCE_ZONE 替换为运行实例的地区。

2. 使用以下命令连接到实例：

   gcloud compute ssh INSTANCE_NAME
   

   将 INSTANCE_NAME 替换为虚拟机实例的名称。

3. 如需设置 Docker 代码库，请参阅 Docker 文档。请务必按照与虚拟机实例的版本和架构相对应的步骤进行操作：
   • Jessie 或更高版本
   • x86_64/amd64

在 Docker 容器中运行 API 和 ESPv2

ESPv2 是一种基于 Envoy 的代理，位于后端代码的前面。它可处理传入的流量，以提供身份验证、API 密钥管理、日志记录和其他 Endpoints API 管理功能。 如需在 Docker 容器中安装和运行示例 API 和 ESPv2，请执行以下操作：

1. 自行创建名为 esp_net 的容器网络。

   sudo docker network create --driver bridge esp_net
   

2. 运行为示例 API 提供服务的示例 Echo 服务器：
   Java

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-java:1.0
   

   Python

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-python:1.0
   

   前往

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-go:1.0
   

   PHP

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-php:1.0
   

   Ruby

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-ruby:1.0
   

   NodeJS

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-node:1.0
   

3. 运行预封装的公共 ESPv2 Docker 容器。在 ESPv2 启动选项中，将 SERVICE_NAME 替换为您的服务名称。该名称与您在 OpenAPI 文档的 host 字段中配置的名称相同。

   sudo docker run \
       --detach \
       --name=esp \
       --publish=80:9000 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:2 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --listener_port=9000 \
       --backend=http://echo:8080
   

   --rollout_strategy=managed 选项可将 ESPv2 配置为使用最新部署的服务配置。如果指定此选项，则 ESPv2 会在您部署新服务配置后的一分钟内检测到更改并自动开始使用该服务配置。建议您指定此选项，而不是提供特定配置 ID 供 ESPv2 使用。如需了解以上所使用的其他 ESPv2 选项，请参阅 ESPv2 启动选项。

如果您收到错误消息，请参阅排查 Compute Engine 上的 Endpoints 问题。 如需了解详情，请参阅部署 API 后端。

使用 IP 地址发送请求

在 Compute Engine 实例上运行示例 API 和 ESPv2 后，您可以从本地机器向 API 发送请求。

创建 API 密钥并设置环境变量

示例代码需要 API 密钥。为简化请求，请为 API 密钥设置环境变量。

1. 在您用于 API 的同一 Google Cloud 项目中，在 API 凭据页面上创建 API 密钥。如果要在其他 Google Cloud 项目中创建 API 密钥，请参阅在 Google Cloud 项目中启用 API。

   转到“凭据”页面

2. 点击创建凭据，然后选择 API 密钥。
3. 将密钥复制到剪贴板。
4. 点击关闭。
5. 在本地计算机上，粘贴 API 密钥以将其分配给环境变量：
   • 在 Linux 或 macOS 中：export ENDPOINTS_KEY=AIza...
   • 在 Windows PowerShell 中：$Env:ENDPOINTS_KEY="AIza..."

发送请求

curl --request POST \
   --header "content-type:application/json" \
   --data '{"message":"hello world"}' \
   "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content

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，请执行以下操作：

1. 打开 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"

2. 在 name 属性中，将 YOUR_PROJECT_ID 替换为您的项目 ID。
3. 在 target 属性中，将 IP_ADDRESS 替换为您向示例 API 发送请求时使用的 IP 地址。
4. 将更新后的 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 发送请求

• 在 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 活动，请执行以下操作：

1. 在 Endpoints > 服务页面中查看您的 API 的活动图表。
   

   转到“Endpoints 服务”页面

   
   请求可能需要一些时间才能体现在图表中。
2. 在“日志浏览器”页面中查看 API 的请求日志。
   

   转到“日志浏览器”页面

为 API 创建开发者门户

可使用 Cloud Endpoints 门户创建开发者门户，该门户是一个可用于与示例 API 进行交互的网站。如需了解详情，请参阅 Cloud Endpoints 门户概览。