适用于 App Engine 标准环境的 Endpoints 使用入门

本页面介绍了如何为 App Engine 设置 Cloud Endpoints。Endpoints 使用 Extensible Service Proxy (ESP) 作为 API 网关。为了向 App Engine 提供 API 管理功能,请将预构建的 ESP 容器部署到 Cloud Run。然后,使用 Identity Aware Proxy (IAP) 保护应用,以便 ESP 可调用它们。通过此设置,ESP 会拦截发送给您的应用的所有请求,并在调用应用之前执行所有必要检查(例如身份验证)。在应用作出响应时,ESP 会收集并报告遥测数据。您可以在 Google Cloud Console 中的 Endpoints > 服务页面上查看应用的指标。

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

任务列表

学习本教程时,请使用以下任务列表。要让 Endpoints 管理您的应用,您必须完成所有这些任务。

  1. 创建一个 Google Cloud 项目,如果您尚未部署自己的 App Engine,请部署一个示例应用。请参阅准备工作
  2. 配置 IAP 来保护应用。请参阅配置 IAP
  3. 将 ESP 容器部署到 Cloud Run。请参阅部署 ESP
  4. 创建描述 API 的 OpenAPI 文档,并配置到您的 App Engine 的路由。请参阅配置 Endpoints
  5. 部署 OpenAPI 文档以创建托管式服务。请参阅部署 Endpoints 配置
  6. 配置 ESP,使其能够找到您的服务的配置。请参阅配置 ESP
  7. 调用应用。请参阅向 API 发送请求
  8. 跟踪您的应用的活动。请参阅跟踪 API 活动
  9. 避免向您的 Google Cloud 帐号收取费用。请参阅清理

准备工作

由于适用于 App Engine 的 Endpoints 目前是 Alpha 版,我们建议您采取以下做法:

  • 新建一个 Google Cloud 项目,以便在将 ESP 容器部署到 Cloud Run 时使用。

  • 为 App Engine 创建新项目或选择一个现有项目。

如需进行设置,请执行以下操作:

  1. 在 Cloud Console 中,转到管理资源页面并创建一个项目。

    转到“管理资源”页面

  2. 确保您的项目已启用结算功能。

    了解如何启用结算功能

  3. 请记下项目 ID,您稍后需要用到它。在本页面的其余部分,此项目 ID 称为 ESP_PROJECT_ID

  4. 请记下项目编号,您稍后会用到它。在本页面的其余部分,此项目编号称为 ESP_PROJECT_NUMBER

  5. 下载并安装 Cloud SDK。

    下载 Cloud SDK

  6. 如果您尚未部署自己的 App Engine,请按照与您所用语言对应的 App Engine 快速入门中的步骤操作,使用 gcloud 命令行工具选择或创建一个 Google Cloud 项目并部署示例应用。记下部署应用的区域和项目 ID。在本页面的其余部分,此项目 ID 称为 APP_PROJECT_ID

配置 IAP 以确保应用安全

为了保护 App Engine 应用,您必须使用 Identity Aware Proxy (IAP) 来确保对请求进行身份验证。

按照启用 IAP 中的步骤操作,确保您能够登录到您的应用。

此外,在配置 OAuth 客户端时,请记下 OAuth client_id(在本快速入门中称为 IAP_CLIENT_ID)。

部署 ESP

如需将 ESP 容器部署到 Cloud Run,请执行以下操作:

  1. 确保 Cloud SDK 有权访问您的数据和服务:
  2. 登录。
    gcloud auth login
  3. 在打开的新浏览器标签页上,选择一个帐号,该帐号在您为将 ESP 部署到 Cloud Run 而创建的 Google Cloud 项目中具有 EditorOwner 角色。
  • 设置区域。Cloud Run 目前仅支持 us-central1
    gcloud config set run/region us-central1
  • 将 ESP 部署到 Cloud Run。将 CLOUD_RUN_SERVICE_NAME 替换为您要使用的服务名称。
    gcloud beta run deploy CLOUD_RUN_SERVICE_NAME \
        --image="gcr.io/endpoints-release/endpoints-runtime-serverless:1.30.0" \
        --allow-unauthenticated \
        --project=ESP_PROJECT_ID
    

    成功完成上述操作后,该命令将显示如下所示的消息:

    Service [gateway] revision [gateway-00001] has been deployed and is serving
    traffic at https://gateway-12345-uc.a.run.app

    在前面的示例中,gateway 是 Cloud Run 服务的名称。

  • 记下网址中的主机名,因为稍后您需要在 OpenAPI 文档的 host 字段中指定主机名。
  • 您的 Cloud Run 服务在互联网上是公开的。如果要添加身份验证功能,建议您使用 Endpoints 支持的某种身份验证方法
  • 配置 Endpoints

    您必须拥有基于 OpenAPI 规范 2.0 的 OpenAPI 文档,该文档描述了您的应用的表面和各项身份验证要求。您还需要添加包含各应用的网址的 Google 专属字段,以便 ESP 获得调用应用所需的信息。如果您刚接触 OpenAPI,请参阅 OpenAPI 概览了解详情。

    1. 创建名为 openapi-appengine.yaml 的文本文件。(为方便起见,本页面用此文件名指代 OpenAPI 文档;如果愿意,您也可改用其他名称。)
    2. 您的每个应用都必须在 openapi-appengine.yaml 文件的 paths 部分列出。例如:
        swagger: '2.0'
        info:
          title: Cloud Endpoints + App Engine
          description: Sample API on Cloud Endpoints with an App Engine backend
          version: 1.0.0
        host: HOST
        schemes:
          - https
        produces:
          - application/json
        x-google-backend:
          address: https://APP_PROJECT_ID.REGION.r.appspot.com
          jwt_audience: IAP_CLIENT_ID
        paths:
          /hello:
            get:
              summary: Greet a user
              operationId: hello
              responses:
                '200':
                  description: A successful response
                  schema:
                    type: string
      
    3. x-google-backend 部分的 address 字段中,将 APP_PROJECT_ID 替换为您的 Google Cloud 项目 ID,将 REGION 替换为您部署 App Engine 的 GCP 区域,将 IAP_CLIENT_ID 替换为您在设置 IAP 时创建的 OAuth 客户端 ID。
    4. host 字段中,添加 Cloud Run 为 ESP 创建的服务网址的主机名。请勿包含协议标识符 https://。例如:
      swagger: '2.0'
        info:
          title: Cloud Endpoints + App Engine
          description: Sample API on Cloud Endpoints with an App Engine backend
          version: 1.0.0
        host: gateway-12345-uc.a.run.app
      

      Endpoints 使用您在 host 字段中配置的名称作为您的服务名称。

    5. 保存您的 OpenAPI 文档。

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

    部署 Endpoints 配置

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

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

    1. 确保您位于 OpenAPI 文档所在的目录中。

    2. 上传配置并创建托管式服务。

      gcloud endpoints services deploy openapi-appengine.yaml \
        --project ESP_PROJECT_ID
      

      这将创建一个新的 Endpoints 服务,其名称是您在 openapi-appengine.yaml 文件的 host 字段中指定的名称。该服务会根据您的 OpenAPI 文档进行配置。

    在创建和配置服务时,Service Management 会向终端输出信息。部署完成后,系统将显示如下所示的消息:

    Service Configuration [2019-02-01-r0] uploaded for service [gateway-12345-uc.a.run.app]
    

    在前面的示例中,2019-02-01-r0 是服务配置 ID,gateway-12345-uc.a.run.app 是 Endpoints 服务名称。服务配置 ID 由日期戳后跟一个修订版本号组成。如果您在同一天再次部署 openapi-appengine.yaml,则服务配置 ID 中的修订号会递增。您可以在 Cloud Console 中的 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 Console 中的 Endpoints 页面。服务名称列下显示了可能的 ENDPOINTS_SERVICE_NAME 列表。

    • 对于 OpenAPI,ENDPOINTS_SERVICE_NAME 是您在 OpenAPI 规范的 host 字段中指定的值。对于 gRPC,ENDPOINTS_SERVICE_NAME 是您在 gRPC Endpoints 配置的 name 字段中指定的值。

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

    配置 ESP

    配置 ESP,使其能够找到您的 Endpoints 服务的配置。然后为 ESP 授予 Cloud IAM 权限以调用您受到 IAP 保护的应用。

    要配置 ESP,请执行以下操作:

    1. 设置 Endpoints 服务名称,使 ESP 能够找到并加载 Endpoints 配置。在以下命令中:

      • YOUR_SERVICE_NAME 替换为 Endpoints 服务的名称。这是您在 OpenAPI 文档的 host 字段中指定的名称。
      • CLOUD_RUN_SERVICE_NAME 替换为您的 Cloud Run 服务的名称。
      gcloud beta run services update CLOUD_RUN_SERVICE_NAME \
         --set-env-vars ENDPOINTS_SERVICE_NAME=YOUR_SERVICE_NAME \
         --project ESP_PROJECT_ID
      
    2. 如果要将 Endpoints 配置为使用其他 ESP 启动选项(例如启用 CORS),您可以在 ESP_ARGS 环境变量中传递参数:

      gcloud beta run services update CLOUD_RUN_SERVICE_NAME \
         --set-env-vars="^|^ENDPOINTS_SERVICE_NAME=YOUR_SERVICE_NAME|ESP_ARGS=--rollout_strategy=managed,--cors_preset=basic" \
         --project ESP_PROJECT_ID
      

      您必须添加 ENDPOINTS_SERVICE_NAME--rollout_strategy

    3. 向 ESP 授权,使其能够调用您受到 IAP 保护的应用。请运行以下命令。在此命令中:

      • APP_PROJECT_ID 替换为您的 App Engine 项目 ID 的名称。
      • ESP_PROJECT_NUMBER 替换为您为 ESP 创建的项目的编号。要找到此编号,一种方法是转到 IAM 控制台并查找默认计算机服务帐号,即 member 标志中使用的服务帐号。
      gcloud projects add-iam-policy-binding APP_PROJECT_ID \
          --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
          --role "roles/iap.httpsResourceAccessor"
      

    向 API 发送请求

    本部分介绍如何向 API 发送请求。

    1. 为 Endpoints 服务名称创建环境变量。这是您在 OpenAPI 文档的 host 字段中指定的名称。例如:
      • Linux 或 macOS

        export ENDPOINTS_HOST=gateway-12345-uc.a.run.app

      • Windows PowerShell

        $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

    Linux 或 macOS

    通过您在上一步中设置的 ENDPOINTS_HOST 环境变量,使用 curl 发送一个 HTTP 请求。

    curl --request GET \
       --header "content-type:application/json" \
       "https://${ENDPOINTS_HOST}/hello"

    PowerShell

    通过您在上一步中设置的 ENDPOINTS_HOST 环境变量,使用 Invoke-WebRequest 发送一个 HTTP 请求。

    (Invoke-WebRequest -Method GET `
        -Headers @{"content-type"="application/json"} `
        -URI "https://$Env:ENDPOINTS_HOST/hello").Content
    

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

    第三方应用

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

    • 选择 GET 作为 HTTP 谓词。
    • 对于标头,请选择键 content-type 和值 application/json
    • 使用实际的网址而不是环境变量,例如:

      https://gateway-12345-uc.a.run.app/hello
      

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

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

    跟踪 API 活动

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

      查看 Endpoints 活动图表

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

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

      查看 Endpoints 请求日志

    为 API 创建开发者门户

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

    清理

    为避免系统因本快速入门中使用的资源向您的 Google Cloud 帐号收取费用,请按照以下步骤操作。

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

    后续步骤