使用入门:Cloud Functions 上使用 ESPv2 的 Endpoints

本页面介绍如何在 Cloud Functions 上设置 Cloud Endpoints。Endpoints 使用 Extensible Service Proxy V2 (ESPv2) 作为 API 网关。要为 Cloud Functions 函数提供 API 管理功能,请将预构建的 ESPv2 容器部署到 Cloud Run。然后,使用 Cloud Functions IAM 保护函数,以便 ESPv2 可以调用它们。

通过此设置,ESPv2 会拦截发送给您的函数的所有请求,并在调用函数之前执行所有必要的检查(例如身份验证)。当函数响应时,ESPv2 会收集并报告遥测数据,如下图所示。您可以在 Google Cloud Console 中的 Endpoints > 服务页面上查看函数的指标。

Endpoints 架构

如需大致了解 Cloud Endpoints,请参阅 Endpoints 简介Endpoints 架构

迁移到 ESPv2

以前版本的 Cloud Endpoints 支持在 Cloud Functions 中使用 Extensible Service Proxy(ESP)。 如果您有要迁移到 ESPv2 的现有 API,请参阅迁移到 Extensible Service Proxy V2 了解更多信息。

任务列表

学习本教程时,请使用以下任务列表。完成本教程所需的所有任务

  1. 创建一个 Google Cloud 项目,如果您尚未部署自己的 Cloud Functions 函数,请部署示例后端函数。请参阅准备工作
  2. 为 ESPv2 服务预留 Cloud Run 主机名。请参阅预留 Cloud Run 主机名
  3. 创建描述 API 的 OpenAPI 文档,并配置到 Cloud Functions 函数的路由。请参阅配置 Endpoints
  4. 部署 OpenAPI 文档以创建托管式服务。请参阅部署 Endpoints 配置
  5. 使用您的 Endpoints 服务配置构建新的 ESPv2 Docker 映像。请参阅构建新的 ESPv2 映像
  6. 将 ESPv2 容器部署到 Cloud Run。然后为 ESPv2 授予 Identity and Access Management (IAM) 权限以调用您的服务。请参阅部署 ESPv2 容器
  7. 调用一个函数。请参阅向 API 发送请求
  8. 跟踪您的函数的活动。请参阅跟踪 API 活动
  9. 避免向您的 Google Cloud 帐号收取费用。请参阅清理

准备工作

在使用适用于 Cloud Functions 的 Endpoints 之前,我们建议您:

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

  • 为 Cloud Functions 创建新项目或选择现有项目。

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

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

    转到“管理资源”页面

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

    了解如何启用结算功能

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

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

  5. 下载并安装 Cloud SDK。

    下载 Cloud SDK

  6. 如果您尚未部署自己的后端 Cloud Functions 函数,请按照《快速入门:使用 gcloud 命令行工具》中的步骤操作,选择或创建一个 Google Cloud 项目并部署示例函数。记下部署函数的区域和项目 ID。在本页面的其余部分,此项目 ID 称为 FUNCTIONS_PROJECT_ID

预留 Cloud Run 主机名

您必须为 ESPv2 服务预留 Cloud Run 主机名,才能配置 OpenAPI 文档或 gRPC 服务配置。为了预留主机名,您需要将示例容器部署到 Cloud Run。稍后,您会将 ESPv2 容器部署到相同的 Cloud Run 服务中。

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

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

    Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

    例如,如果将 CLOUD_RUN_SERVICE_NAME 设置为 gateway

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

    在此示例中,https://gateway-12345-uc.a.run.appCLOUD_RUN_SERVICE_URLgateway-12345-uc.a.run.appCLOUD_RUN_HOSTNAME

  4. 记下 CLOUD_RUN_SERVICE_NAMECLOUD_RUN_HOSTNAME。您稍后会将 ESPv2 部署到 CLOUD_RUN_SERVICE_NAME Cloud Run 服务。您可以在 OpenAPI 文档的 host 字段中指定CLOUD_RUN_HOSTNAME

配置 Endpoints

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

  1. 创建名为 openapi-functions.yaml 的文本文件。(为方便起见,本页面用此文件名指代 OpenAPI 文档;如果愿意,您也可改用其他名称。)
  2. 您的每个函数都必须在 openapi-functions.yaml 文件的 paths 部分列出。例如:
    swagger: '2.0'
    info:
      title: Cloud Endpoints + GCF
      description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
      version: 1.0.0
    host: HOST
    schemes:
      - https
    produces:
      - application/json
    paths:
      /hello:
        get:
          summary: Greet a user
          operationId: hello
          x-google-backend:
            address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
            protocol: h2
          responses:
            '200':
              description: A successful response
              schema:
                type: string
    
    缩进对 yaml 格式而言非常重要。例如,host 字段必须与 info 处于同一级别。
  3. x-google-backend 部分的 address 字段中,将 REGION 替换为您的函数所在的 Google Cloud 区域,将 FUNCTIONS_PROJECT_ID 替换为您的 Google Cloud 项目 ID,将 FUNCTIONS_NAME 替换为您的函数名称。例如:
    x-google-backend:
      address: https://us-central1-myproject.cloudfunctions.net/helloGET
    
    如果要通过仅允许 ESPv2 调用 Cloud Functions 函数来保护 Cloud Functions 函数,请确保在未指定jwt_audienceaddress 字段包含函数名称。例如:
    x-google-backend:
      address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
      path_translation: CONSTANT_ADDRESS
    
    如果指定了 jwt_audience,则其值也应包含函数名称。例如:
    x-google-backend:
      address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net
      jwt_audience: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
      path_translation: APPEND_PATH_TO_ADDRESS
    
    ESPv2 在调用 Cloud Functions 函数进行身份验证时生成 ID 令牌。ID 令牌应具有适当的 audience,用于指定函数主机和函数名称。ESPv2 使用 jwt_audience 字段中的值为 ID 令牌设置 audience(如果已指定),否则使用 address 字段。
  4. host 字段中,指定 CLOUD_RUN_HOSTNAME,即上面的预留 Cloud Run 主机名中预留的网址的主机名部分。请勿包含协议标识符 https://。例如:

    swagger: '2.0'
      info:
        title: Cloud Endpoints + GCF
        description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
        version: 1.0.0
      host: gateway-12345-uc.a.run.app
    
  5. 请记下 openapi-functions.yaml 文件中 title 属性的值:

    title: Cloud Endpoints + GCF

    在您部署配置后,title 属性的值会成为 Endpoints 服务的名称。

  6. 保存您的 OpenAPI 文档。

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

部署 Endpoints 配置

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

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

  1. 确保您位于 OpenAPI 文档所在的目录中。
  2. 上传配置并创建托管式服务。

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

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

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

    Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]

    CONFIG_ID 是部署创建的唯一 Endpoints 服务配置 ID。例如:

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

    服务配置 ID 由日期戳后跟一个修订版本号组成。如果您在同一天再次部署 openapi-functions.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 服务

构建新的 ESPv2 映像

将 Endpoints 服务配置构建到新的 ESPv2 Docker 映像中。您稍后会将此映像部署到预留的 Cloud Run 服务。

如需将服务配置构建到新的 ESPv2 Docker 映像中,请执行以下操作:

  1. 将此脚本下载到安装了 gcloud SDK 的本地机器上。

  2. 使用以下命令运行脚本:

    chmod +x gcloud_build_image
    
    ./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
        -c CONFIG_ID -p ESP_PROJECT_ID

    对于 CLOUD_RUN_HOSTNAME,请指定在上文的预留 Cloud Run 主机名中预留的网址的主机名。请勿包含协议标识符 https://

    例如:

    chmod +x gcloud_build_image
    ./gcloud_build_image -s gateway-12345-uc.a.run.app \
        -c 2019-02-01r0 -p your-project-id
  3. 该脚本使用 gcloud 命令下载服务配置,将服务配置构建到新的 ESPv2 映像中,然后将新映像上传到项目 Container Registry 中:脚本会自动使用最新版本的 ESPv2,由输出映像名称中的 ESP_VERSION 表示。输出映像将上传到:

    gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID

    例如:

    gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"

部署 ESPv2 容器

  1. 使用您在上面构建的新映像部署 ESPv2 Cloud Run 服务。将 CLOUD_RUN_SERVICE_NAME 替换为您在上文的预留 Cloud Run 主机名中最初预留主机名时所用的 Cloud Run 服务名称:

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
      --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
      --allow-unauthenticated \
      --platform managed \
      --project=ESP_PROJECT_ID
  2. 如果要将 Endpoints 配置为使用其他 ESPv2 启动选项(例如启用 CORS),您可以在 ESPv2_ARGS 环境变量中传递参数:

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
      --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
      --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
      --allow-unauthenticated \
      --platform managed \
      --project ESP_PROJECT_ID

    如需详细了解如何设置 ESPv2_ARGS 环境变量并获取更多相关示例(包括可用选项的列表以及如何指定多个选项的信息),请参阅 Extensible Service Proxy V2 Beta 版标志

  3. 授予 ESPv2 权限以调用 Service ManagementService Control

    • 在 Cloud Console 中,转到 Cloud Run 页面。
    • 转到 Cloud Run 页面

    • 您可以查看您部署的 Cloud Run 实例以及与其关联的服务帐号。
    • 向服务帐号授予所需权限:
    • gcloud projects add-iam-policy-binding PROJECT_NAME \
         --member "serviceAccount:SERVICE_ACCOUNT" \
         --role roles/servicemanagement.serviceController
    如需了解详情,请参阅什么是角色和权限?
  4. 为 ESPv2 授予权限以调用您的函数。对每个函数运行以下命令。在以下命令中:

    • FUNCTION_NAME 替换为函数的名称,并将 FUNCTION_REGION 替换为函数部署到的地区。如果您使用的是快速入门:使用 gcloud 命令行工具中创建的函数,则使用 helloGET 作为名称。
    • ESP_PROJECT_NUMBER 替换为您针对 ESPv2 创建的项目的编号。要找到此编号,一种方法是转到 Cloud Console 中的 IAM 页面并查找默认计算机服务帐号,即 member 标志中使用的服务帐号。
    gcloud functions add-iam-policy-binding FUNCTION_NAME \
       --region FUNCTION_REGION \
       --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
       --role "roles/cloudfunctions.invoker" \
       --project FUNCTIONS_PROJECT_ID
    

如需了解详情,请参阅通过 IAM 管理访问权限

向 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 实例

后续步骤