此页面由 Cloud Translation API 翻译。

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

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

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

目标

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

设置 Google Cloud 项目，安装所需软件，并创建 App Engine 应用。请参阅准备工作。
下载示例代码。请参阅获取示例代码。
配置 openapi-appengine.yaml 文件，该文件用于配置 Endpoints。请参阅配置 Endpoints。
部署 Endpoints 配置以创建 Endpoints 服务。请参阅部署 Endpoints 配置。
将 API 和 ESP 部署到 App Engine。请参阅部署 API 后端。
向 API 发送请求。请参阅向 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.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify 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.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

记下项目 ID，您稍后需要用到。
您需要一个应用来向示例 API 发送请求。
- Linux 和 macOS 用户：本教程提供了一个使用 curl 的示例，它通常已预装在您的操作系统中。如果您没有 curl，可以从 curl 版本和下载页面中下载。
- Windows 用户：本教程提供了一个使用 Invoke-WebRequest 的示例，PowerShell 3.0 及更高版本支持该命令。
下载 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 配置。
选择您要在其中创建 App Engine 应用的区域。运行以下命令以获取区域列表：
```
gcloud app regions list
```
创建 App Engine 应用。将 YOUR_PROJECT_ID 替换为您的 Google Cloud项目 ID，并将 YOUR_REGION 替换为您要在其中创建 App Engine 应用的区域。
```
  gcloud app create \
  --project=YOUR_PROJECT_ID \
  --region=YOUR_REGION
```
如果您的 App Engine 默认服务账号没有 Editor (roles/editor) 角色，请授予以下权限：
- 在服务级别向 App Engine 默认服务账号授予 roles/servicemanagement.serviceConsumer。
- 在项目级层面向 App Engine 默认服务账号授予 roles/servicemanagement.serviceController。
如需了解如何向服务账号授予角色，请参阅使用 Google Cloud 控制台管理访问权限。

获取示例代码

Java

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

示例代码使用 Maven。如果您没有 Maven 3.3.9 或更高版本，请下载并安装。
将示例应用代码库克隆到本地机器：
```
git clone https://github.com/GoogleCloudPlatform/java-docs-samples
```
或者，下载该示例的 zip 文件并将其解压缩。

转到包含示例代码的目录：

cd java-docs-samples/endpoints/getting-started

Python

如需克隆或下载示例 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

PHP

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

将示例应用代码库克隆到本地机器：
```
git clone https://github.com/GoogleCloudPlatform/php-docs-samples
```
或者，下载该示例的 zip 文件并将其解压缩。

转到包含示例代码的目录：

cd php-docs-samples/endpoints/getting-started

Ruby

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

将示例应用代码库克隆到本地机器：
```
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples
```
或者，下载该示例的 zip 文件并将其解压缩。

转到包含示例代码的目录：

cd ruby-docs-samples/endpoints/getting-started

NodeJS

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

将示例应用代码库克隆到本地机器：
```
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples
```
或者，下载该示例的 zip 文件并将其解压缩。

切换到包含示例代码的目录：

cd nodejs-docs-samples/endpoints/getting-started

配置 Endpoints

您必须拥有基于 OpenAPI 2.0 或 OpenAPI 3.x 的 OpenAPI 文档，该文档描述了您的应用的表面和各项身份验证要求。如需了解详情，请参阅支持的 OpenAPI 版本。

您还需要添加包含各应用的网址的 Google 专属字段，以便 ESPv2 获得调用应用所需的信息。如果您刚接触 OpenAPI，请参阅 OpenAPI 概览了解详情。

OpenAPI 2.0

如需使用 OpenAPI 2.0 规范配置 Endpoints，您可以使用下载的示例代码的 dotnet-docs-samples-master\endpoints\getting-started 目录中提供的 openapi-appengine.yaml 文件。

OpenAPI 2.0 规范的内容应类似于以下内容：

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"
consumes:
- "application/json"
produces:
- "application/json"
schemes:
- "https"
paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      security:
      - api_key: []
  "/auth/info/googlejwt":
    get:
      description: "Returns the requests' authentication information."
      operationId: "auth_info_google_jwt"
      produces:
      - "application/json"
      responses:
        200:
          description: "Authentication info."
          schema:
            $ref: "#/definitions/authInfoResponse"
      x-security:
      - google_jwt:
          audiences:
          # This must match the "aud" field in the JWT. You can add multiple
          # audiences to accept JWTs from multiple clients.
          - "echo.endpoints.sample.google.com"
  "/auth/info/googleidtoken":
    get:
      description: "Returns the requests' authentication information."
      operationId: "authInfoGoogleIdToken"
      produces:
      - "application/json"
      responses:
        200:
          description: "Authenication info."
          schema:
            $ref: "#/definitions/authInfoResponse"
      x-security:
      - google_id_token:
          audiences:
          # Your OAuth2 client's Client ID must be added here. You can add
          # multiple client IDs to accept tokens from multiple clients.
          - "YOUR-CLIENT-ID"

definitions:
  echoMessage:
    type: "object"
    properties:
      message:
        type: "string"
  authInfoResponse:
    properties:
      id:
        type: "string"
      email:
        type: "string"

securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
  # This section configures authentication using Google API Service Accounts
  # to sign a json web token. This is mostly used for server-to-server
  # communication.
  google_jwt:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    # This must match the 'iss' field in the JWT.
    x-google-issuer: "jwt-client.endpoints.sample.google.com"
    # Update this with your service account's email address.
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR-SERVICE-ACCOUNT-EMAIL"
  # This section configures authentication using Google OAuth2 ID Tokens.
  # ID Tokens can be obtained using OAuth2 clients, and can be used to access
  # your API on behalf of a particular user.
  google_id_token:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"

在包含 host 字段的行中，将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。

OpenAPI 3.x

如需使用 OpenAPI 3.x 规范配置 Endpoints，您可以替换下载的示例代码的 dotnet-docs-samples-master\endpoints\getting-started 目录中提供的 openapi-appengine.yaml 文件的内容：

在文本编辑器中打开 openapi-appengine.yaml，然后将内容替换为以下内容：

openapi: 3.0.4
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
servers:
  - url: "https://YOUR_PROJECT_ID.appspot.com"
    x-google-endpoint: {}
paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      requestBody:
        description: "Message to echo"
        required: true
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/echoMessage"
      responses:
        "200":
          description: "Echo"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/echoMessage"
      security:
        - api_key: []
  "/auth/info/googlejwt":
    get:
      description: "Returns the requests' authentication information."
      operationId: "auth_info_google_jwt"
      responses:
        "200":
          description: "Authenication info."
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/authInfoResponse"
      security:
        - google_jwt: []
  "/auth/info/googleidtoken":
    get:
      description: "Returns the requests' authentication information."
      operationId: "authInfoGoogleIdToken"
      responses:
        "200":
          description: "Authenication info."
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/authInfoResponse"
      security:
        - google_id_token: []

components:
  schemas:
    echoMessage:
      type: "object"
      properties:
        message:
          type: "string"
    authInfoResponse:
      type: "object"
      properties:
        id:
          type: "string"
        email:
          type: "string"

  securitySchemes:
    # This section configures basic authentication with an API key.
    api_key:
      type: apiKey
      name: key
      in: query
    # This section configures authentication using Google API Service Accounts
    # to sign a json web token. This is mostly used for server-to-server
    # communication.
    google_jwt:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: ""
          scopes: {}
      x-google-auth:
        issuer: "jwt-client.endpoints.sample.google.com"
        jwksUri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR_SERVICE_ACCOUNT_EMAIL"
        # This must match the "aud" field in the JWT. You can add multiple
        # audiences to accept JWTs from multiple clients.
        audiences:
          - "echo.endpoints.sample.google.com"
    # This section configures authentication using Google OAuth2 ID Tokens.
    # ID Tokens can be obtained using OAuth2 clients, and can be used to access
    # your API on behalf of a particular user.
    google_id_token:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: ""
          scopes: {}
      x-google-auth:
        issuer: "https://accounts.google.com"
        jwksUri: "https://www.googleapis.com/oauth2/v1/certs"
        audiences:
          - "YOUR_CLIENT_ID"

保存 openapi.yaml 的新内容。

本教程使用特定于 Google 的 OpenAPI 规范扩展程序，该扩展程序可让您配置服务名称。指定服务名称的方法取决于您使用的 OpenAPI 规范版本。

OpenAPI 2.0

使用 host 字段指定服务名称：

host: YOUR_PROJECT_ID.appspot.com

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

打开 openapi-appengine.yaml 文件。
在 host 字段中，将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。
保存 openapi-appengine.yaml 文件。

OpenAPI 3.x

使用 servers 对象中的 url 字段指定服务名称：

servers:
- url: https://YOUR_PROJECT_ID.appspot.com
  x-google-endpoint: {}

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

打开 openapi-appengine.yaml 文件。
如果您的 openapi-appengine.yaml 文件包含 host 字段，请将其移除。
添加一个 servers 对象，如下所示。
在 url 字段中，将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。
保存 openapi-appengine.yaml 文件。

注意：您必须在 server 对象中包含 x-google-endpoint: {}，才能指定供服务器使用的正确网址。此列表中可以包含其他服务器，但必须有一个服务器具有 x-google-endpoint: {}，以指定正确的服务器。所有其他网址均会被忽略。

部署 Endpoints 配置

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

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

确保您位于 openapi.yaml 配置文件所在的目录中。

上传配置并创建托管式服务：

gcloud endpoints services deploy openapi.yaml

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

在创建和配置服务时，Service Management 会向终端输出信息。您尽可忽略有关 openapi.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.yaml 文件，服务配置 ID 中的修订版本号将递增。您可以在 Google Cloud 控制台中的 Endpoints > 服务页面上查看 Endpoints 服务配置。

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

检查所需服务

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

姓名	标题
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API

在大多数情况下，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 后端提供服务的代码。本部分将逐步介绍如何将示例 API 和 ESP 部署到 App Engine。

要部署 API 后端，请执行以下操作：

将您的服务名称添加到 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