使用入门:App Engine 柔性环境中使用 ESP 的 Cloud Endpoints


本教程介绍如何配置和部署在 App Engine 柔性环境中的实例上运行的示例 API 和 Extensible Service Proxy (ESP)。示例代码的 REST API 使用 OpenAPI 规范进行描述。本教程还介绍如何创建 API 密钥,以及在向 API 发送请求时如何使用此密钥。

如需大致了解 Cloud Endpoints,请参阅关于 EndpointsEndpoints 架构

目标

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

  1. 设置一个 Google Cloud 项目,安装所需软件,并创建 App Engine 应用。请参阅准备工作
  2. 下载示例代码。请参阅获取示例代码
  3. 配置 openapi-appengine.yaml 文件,该文件用于配置 Endpoints。请参阅配置 Endpoints
  4. 部署 Endpoints 配置以创建 Endpoints 服务。请参阅部署 Endpoints 配置
  5. 将 API 和 ESP 部署到 App Engine。请参阅部署 API 后端
  6. 向 API 发送请求。请参阅向 API 发送请求
  7. 跟踪 API 活动。请参阅跟踪 API 活动
  8. 避免系统向您的 Google Cloud 账号收费。请参阅清理

费用

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

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

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

准备工作

  1. 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手,请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. 确保您的 Google Cloud 项目已启用结算功能

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

    Go to project selector

  5. 确保您的 Google Cloud 项目已启用结算功能

  6. 记下项目 ID,您稍后需要用到。
  7. 您需要一个应用来向示例 API 发送请求

    • Linux 和 macOS 用户:本教程提供了一个使用 curl 的示例,它通常已预装在您的操作系统中。如果您没有 curl,可以从 curl 版本和下载页面中下载。
    • Windows 用户:本教程提供了一个使用 Invoke-WebRequest 的示例,PowerShell 3.0 及更高版本支持该命令。
  8. 下载 Google Cloud CLI
  9. 更新 gcloud CLI 并安装端点 组件。
    gcloud components update
  10. 确保 Google Cloud CLI (gcloud) 有权访问您在 Google Cloud 上的数据和服务:
    gcloud auth login
    在浏览器打开的新标签页中,选择一个账号。
  11. 将默认项目设置为您的项目 ID。
    gcloud config set project YOUR_PROJECT_ID

    YOUR_PROJECT_ID 替换为项目 ID。如果您有其他 Google Cloud 项目,并且想使用 gcloud 来管理这些项目,请参阅管理 gcloud CLI 配置

  12. 选择您要在其中创建 App Engine 应用的区域。运行以下命令以获取区域列表:
    gcloud app regions list
  13. 创建 App Engine 应用。将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID,并将 YOUR_REGION 替换为您要在其中创建 App Engine 应用的区域。
      gcloud app create \
      --project=YOUR_PROJECT_ID \
      --region=YOUR_REGION
    

获取示例代码

Java

如需克隆或下载示例 API,请执行以下操作:

  1. 示例代码使用 Maven。如果您没有 Maven 3.3.9 或更高版本,请下载安装
  2. 将示例应用代码库克隆到本地机器:
    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

    或者,下载该示例的 zip 文件并将其解压缩。

  3. 转到包含示例代码的目录:
    cd java-docs-samples/endpoints/getting-started
Python

如需克隆或下载示例 API,请执行以下操作:

  1. 将示例应用代码库克隆到本地机器:
    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    或者,下载该示例的 zip 文件并将其解压缩。

  2. 转到包含示例代码的目录:
    cd python-docs-samples/endpoints/getting-started
Go

如需克隆或下载示例 API,请执行以下操作:

  1. 确保已设置 GOPATH 环境变量
  2. 将示例应用代码库克隆到本地机器:
    go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
  3. 转到包含示例代码的目录:
    cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
PHP

如需克隆或下载示例 API,请执行以下操作:

  1. 将示例应用代码库克隆到本地机器:
    git clone https://github.com/GoogleCloudPlatform/php-docs-samples

    或者,下载该示例的 zip 文件并将其解压缩。

  2. 转到包含示例代码的目录:
    cd php-docs-samples/endpoints/getting-started
Ruby

如需克隆或下载示例 API,请执行以下操作:

  1. 将示例应用代码库克隆到本地机器:
    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    或者,下载该示例的 zip 文件并将其解压缩。

  2. 转到包含示例代码的目录:
    cd ruby-docs-samples/endpoints/getting-started
NodeJS

如需克隆或下载示例 API,请执行以下操作:

  1. 将示例应用代码库克隆到本地机器:
    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

    或者,下载该示例的 zip 文件并将其解压缩。

  2. 切换到包含示例代码的目录:
    cd nodejs-docs-samples/endpoints/getting-started

配置 Endpoints

示例代码包括 OpenAPI 配置文件 openapi-appengine.yaml,该文件基于 OpenAPI 规范 v2.0

要配置 Endpoints,请执行以下操作:
  1. 在示例代码目录中,打开 openapi-appengine.yaml 配置文件。

    Java
    swagger: "2.0"
    info:
      description: "A simple Google Cloud Endpoints API example."
      title: "Endpoints Example"
      version: "1.0.0"
    host: "YOUR-PROJECT-ID.appspot.com"
    Python
    swagger: "2.0"
    info:
      description: "A simple Google Cloud Endpoints API example."
      title: "Endpoints Example"
      version: "1.0.0"
    host: "YOUR-PROJECT-ID.appspot.com"
    Go
    swagger: "2.0"
    info:
      description: "A simple Google Cloud Endpoints API example."
      title: "Endpoints Example"
      version: "1.0.0"
    host: "YOUR-PROJECT-ID.appspot.com"
    PHP
    swagger: "2.0"
    info:
      description: "A simple Google Cloud Endpoints API example."
      title: "Endpoints Example"
      version: "1.0.0"
    host: "YOUR-PROJECT-ID.appspot.com"
    Ruby
    swagger: "2.0"
    info:
      description: "A simple Google Cloud Endpoints API example."
      title: "Endpoints Example"
      version: "1.0.0"
    host: "YOUR-PROJECT-ID.appspot.com"
    NodeJS
    swagger: "2.0"
    info:
      description: "A simple Google Cloud Endpoints API example."
      title: "Endpoints Example"
      version: "1.0.0"
    host: "YOUR-PROJECT-ID.appspot.com"

    请注意以下事项:

    • 配置示例显示了 host 字段附近的几行,您需要修改该字段。要将 openapi-appengine.yaml 部署到 Endpoints,您需要完整的 OpenAPI 文档。
    • 示例 openapi-appengine.yaml 包含用于配置身份验证的部分(本教程不需要)。您无需使用 YOUR-SERVICE-ACCOUNT-EMAILYOUR-CLIENT-ID 配置这些行。
    • OpenAPI 是一种与语言无关的规范。为方便起见,每种语言的 GitHub 代码库中的 getting-started 示例均包含相同的 openapi-appengine.yaml 文件。
  2. 在包含 host 字段的行中,将 YOUR-PROJECT-ID 替换为您的 Google Cloud 项目 ID。例如:
    host: "example-project-12345.appspot.com"

Endpoints 使用 host 字段中配置的文本作为服务名称。将 API 部署到 App Engine 后端时,系统会自动创建名称格式为 YOUR-PROJECT-ID.appspot.com 的 DNS 条目。

如需了解 OpenAPI 文档中 Endpoints 所需的字段,请参阅配置 Endpoints

部署 Endpoints 配置

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

如需部署 Endpoints 配置,请执行以下操作:

  1. 确保您位于 endpoints/getting-started 目录中。
  2. 上传配置并创建托管式服务:
    gcloud endpoints services deploy openapi-appengine.yaml
    

然后,gcloud 命令会调用 Service Management API,以便使用您在 openapi-appengine.yaml 文件的 host 字段中指定的名称创建托管式服务。Service Management 会根据 openapi-appengine.yaml 文件中的设置来配置服务。如果您对 openapi-appengine.yaml 做出更改,则必须重新部署该文件才能更新 Endpoints 服务。

在创建和配置服务时,Service Management 会向终端输出信息。您尽可忽略有关 openapi-appengine.yaml 文件中的路径未要求使用 API 密钥的警告。完成服务配置后,Service Management 将显示如下所示的消息,其中包含服务配置 ID 和服务名称:

Service Configuration [2017-02-13r0] uploaded for service [example-project-12345.appspot.com]

在上面的示例中,2017-02-13r0 是服务配置 ID,example-project-12345.appspot.com 是 Endpoints 服务。服务配置 ID 由日期戳后跟一个修订版本号组成。如果您在同一天再次部署 openapi-appengine.yaml 文件,服务配置 ID 中的修订版本号将递增。您可以在 Google Cloud 控制台中的 Endpoints > Services 页面上查看 Endpoints 服务配置。

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

部署 API 后端

到目前为止,您已将 OpenAPI 文档部署到 Service Management,但尚未部署为 API 后端提供服务的代码。本部分将逐步介绍如何将示例 API 和 ESP 部署到 App Engine。

要部署 API 后端,请执行以下操作:

  1. 将您的服务名称添加到 app.yaml 文件:

    Java

    打开 endpoints/getting-started/src/main/appengine/app.yaml 文件。

    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed

    Python

    打开 endpoints/getting-started/app.yaml 文件。

    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed

    Go

    打开 endpoints/getting-started/app.yaml 文件。

    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed

    PHP

    打开 endpoints/getting-started/app.yaml 文件。

    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
      # previously run the deploy command, you can list your existing configuration
      # ids using the 'configs list' command as follows:
      #
      #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
      #
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed

    Ruby

    打开 endpoints/getting-started/app.yaml 文件。

    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed

    NodeJS

    打开 endpoints/getting-started/app.yaml 文件。

    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed

    ENDPOINTS-SERVICE-NAME 替换为 Endpoints 服务的名称。该名称与您在 OpenAPI 文档的 host 字段中配置的名称相同。例如:

    endpoints_api_service:
      name: example-project-12345.appspot.com
      rollout_strategy: managed

    rollout_strategy: managed 选项可将 ESP 配置为使用最新部署的服务配置。指定此选项后,在部署新的服务配置后,ESP 最多会在 5 分钟内检测到更改并自动开始使用该服务配置。建议您指定此选项,而非让 ESP 使用特定的配置 ID。

  2. 保存 app.yaml 文件。
  3. 由于 endpoints_api_service 部分包含在 app.yaml 文件内,因此 gcloud app deploy 命令会将单独容器中的 ESP 部署到您的 App Engine 柔性环境中,并在该环境中对 ESP 进行配置。所有请求流量均通过 ESP 路由。ESP 会将请求和响应代理到运行后端服务器代码的容器,或从运行后端服务器代码的容器代理请求和响应。

  4. 确保您位于 endpoints/getting-started 目录中。 这是 openapi-appengine.yaml 配置文件的存储位置。
  5. 运行以下命令将示例 API 和 ESP 部署到 App Engine:
  6. Java

    使用 Maven 部署:

    mvn appengine:stage
    gcloud app deploy target/appengine-staging
    
    Python
    gcloud app deploy
    Go
    gcloud app deploy
    PHP
    gcloud app deploy
    Ruby
    gcloud app deploy
    NodeJS
    gcloud app deploy

    gcloud app deploy 命令会创建 YOUR_PROJECT_ID.appspot.com 格式的 DNS 记录,您在向 API 发送请求时会用到它。建议您等待几分钟,在 App Engine 完全初始化后向 API 发送请求。

如果您收到错误消息,请参阅排查 App Engine 柔性部署问题

如需了解详情,请参阅部署 API 后端

向 API 发送请求

现在服务正在 App Engine 上运行,您可以向其发送请求。

创建 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..."

发送请求

Linux 或 Mac OS

  1. 为 App Engine 项目网址创建环境变量。将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID:

    export ENDPOINTS_HOST=https://YOUR_PROJECT_ID.appspot.com

  2. 使用之前设置的 ENDPOINTS_HOSTENDPOINTS_KEY 环境变量发送 HTTP 请求:

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

在上面的 curl 中:

  • --data 选项用于指定要发布到 API 的数据。
  • --header 选项用于指定数据采用 JSON 格式。

PowerShell

  1. 为 App Engine 项目网址创建环境变量。将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID:

    $Env:ENDPOINTS_HOST="https://YOUR_PROJECT_ID.appspot.com"

  2. 使用之前设置的 ENDPOINTS_HOSTENDPOINTS_KEY 环境变量发送 HTTP 请求:

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

在上面的示例中,前两行以反引号结束。将示例粘贴到 PowerShell 中时,请确保反引号后面没有空格。 如需了解示例请求中使用的选项,请参阅 Microsoft 文档中的 Invoke-WebRequest

第三方应用

您可以使用第三方应用(如 Chrome 浏览器扩展程序 Postman)发送请求:

  • 选择 POST 作为 HTTP 谓词。
  • 对于标头,请选择键 content-type 和值 application/json
  • 对于正文,请输入以下内容:
    {"message":"hello world"}
  • 在网址中,使用实际的 appspot.com 地址和 API 密钥,而不是环境变量。例如:
    https://example-project-12345.appspot.com/echo?key=AIza...

API 会回显您向其发送的消息,并以如下内容作为响应:

{
  "message": "hello world"
}

如果未成功收到响应,请参阅排查响应错误

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

跟踪 API 活动

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

    转到“Endpoints 服务”页面

    请求可能需要一些时间才能体现在图表中。

  2. 在“日志浏览器”页面中查看 API 的请求日志。

    转到“日志浏览器”页面

为 API 创建开发者门户

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

清除数据

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

如需了解如何停止本教程使用的服务,请参阅删除 API 和 API 实例

后续步骤