API Gateway 和 Cloud Run 使用入门

本页面介绍如何设置 API Gateway 以管理和保护 Cloud Run 后端服务。

任务列表

学习本教程时,请使用以下任务列表。为您的 Cloud Run 后端服务部署 API Gateway 所需的所有任务。

  1. 创建或选择 Google Cloud 项目。
  2. 如果您尚未部署自己的 Cloud Run,请部署一个示例服务。请参阅准备工作中的第 7 步。
  3. 启用所需的 API Gateway 服务
  4. 创建描述 API 的 OpenAPI 规范,并配置到 Cloud Run 后端服务的路由。请参阅创建 API 配置
  5. 使用您的 API 配置部署 API Gateway。 请参阅部署 API Gateway
  6. 跟踪您的服务的活动。请参阅跟踪 API 活动
  7. 避免向您的 Google Cloud 账号收取费用。请参阅清理

准备工作

  1. 在 Google Cloud 控制台中,转到信息中心页面,然后选择或创建 Google Cloud 项目。

    转到“信息中心”页面

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

    了解如何启用结算功能

  3. 记下要用于本教程的项目 ID。在本页面的其余部分,此项目 ID 称为 PROJECT_ID

  4. 下载并安装 Google Cloud CLI。

    下载 gcloud CLI

  5. 更新 gcloud 组件:

    gcloud components update
  6. 设置默认项目。将 PROJECT_ID 替换为您的 Google Cloud 项目 ID

    gcloud config set project PROJECT_ID

  7. 如果您尚未部署自己的 Cloud Run 服务,请按照快速入门:部署预建的示例容器中的步骤选择或创建 Google Cloud 项目并部署示例后端。记下应用网址以及部署应用的区域和项目 ID。

启用必需服务

API Gateway 要求您启用以下 Google 服务:

名称 标题
apigateway.googleapis.com API Gateway API
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

如需确认已启用必需的服务,请运行以下命令:

gcloud services list

如果您没有看到列出的必需服务,请启用它们:

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

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

创建 API 配置

您需要 API 配置,才能使用 API Gateway 来管理发送到已部署的 Cloud Run 后端的流量。

您可以使用包含专用注释的 OpenAPI 规范来创建 API 配置,以定义所需的 API Gateway 行为。您需要添加一个特定于 Google 的字段,其中包含每个 Cloud Run 应用的网址,以便 API Gateway 获得调用应用所需的信息。

  1. 创建名为 openapi2-run.yaml 的文本文件。(为方便起见,本页面用此文件名指代 OpenAPI 规范;如果愿意,您也可改用其他名称。)
  2. openapi2-run.yaml 文件的 paths 部分列出您的每个应用,如下所示:
    # openapi2-run.yaml
    swagger: '2.0'
    info:
      title: API_ID optional-string
      description: Sample API on API Gateway with a Cloud Run backend
      version: 1.0.0
    schemes:
    - https
    produces:
    - application/json
    x-google-backend:
      address: APP_URL
    paths:
      /assets/{asset}:
        get:
          parameters:
            - in: path
              name: asset
              type: string
              required: true
              description: Name of the asset.
          summary: Assets
          operationId: getAsset
          responses:
            '200':
              description: A successful response
              schema:
                type: string
      /hello:
        get:
          summary: Cloud Run hello world
          operationId: hello
          responses:
            '200':
              description: A successful response
              schema:
                type: string
  3. title 字段中,将 API_ID 替换为您的 API 名称,并将 optional-string 替换为您选择的简要说明。如果您的 API 尚不存在,则创建 API 配置的命令也会使用您指定的名称创建 API。 在创建授予对此 API 访问权限的 API 密钥时,会用到 title 字段的值。请参阅 API ID 要求,了解 API 命名准则。
  4. x-google-backend 部分的 address 字段中,将 APP_URL 替换为 Cloud Run 服务的实际网址(调用的 API 的完整路径)。例如:https://hello-abc1def2gh-uc.a.run.app
  5. 输入以下命令,其中:
    • CONFIG_ID 指定 API 配置的名称。
    • API_ID 指定 API 的名称。如果 API 尚不存在,则此命令会创建该 API。
    • PROJECT_ID 指定您的 Google Cloud 项目的名称。
    • SERVICE_ACCOUNT_EMAIL 指定用于为已配置身份验证的后端的令牌签名的服务帐号。如需了解详情,请参阅创建服务账号
    gcloud api-gateway api-configs create CONFIG_ID \
      --api=API_ID --openapi-spec=openapi2-run.yaml \
      --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

    此操作可能需要几分钟才能完成,因为 API 配置会传播到下游系统。复杂 API 配置的创建最多可能需要 10 分钟才能完成。

  6. 创建 API 配置后,您可以运行以下命令来查看其详细信息:
    gcloud api-gateway api-configs describe CONFIG_ID \
      --api=API_ID --project=PROJECT_ID

部署 API Gateway

现在,您可以在 API Gateway 上部署 API。在 API Gateway 上部署 API 还会定义 API 客户端可用于访问 API 的外部网址。

运行以下命令,将刚创建的 API 配置部署到 API Gateway:

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

其中:

  • GATEWAY_ID 指定网关的名称。
  • API_ID 指定与此网关关联的 API Gateway API 的名称。
  • CONFIG_ID 指定部署到网关的 API 配置的名称。
  • GCP_REGION 是已部署网关的 Google Cloud 区域

  • PROJECT_ID 指定您的 Google Cloud 项目的名称。

完成后,您可以使用以下命令查看有关网关的详细信息:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

请记下此命令输出中的 defaultHostname 属性的值。这是您在下一步中用于测试部署的网关网址的主机名部分。

测试您的 API 部署

现在,您可以使用部署网关时生成的网址向 API 发送请求。

在网络浏览器中输入以下网址,其中:

  • DEFAULT_HOSTNAME 指定已部署的网关网址的主机名部分。
  • hello 是 API 配置中指定的路径。
https://DEFAULT_HOSTNAME/hello

例如:

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

您应该会在浏览器中看到运行应用的 Cloud Run 容器。

成功! 您的 API Gateway 正在管理对 Cloud Run 后端服务的访问权限。

跟踪 API 活动

  1. 在 Google Cloud 控制台的 API Gateway 页面上查看 API 的活动图表。点击您的 API 以在概览页面上查看其活动图表。请求可能要过一些时间才能反映在图表中。

  2. 日志浏览器页面上查看 API 的请求日志。您可以在 Google Cloud 控制台的 API Gateway 页面上找到指向 Logs Explorer 页面的链接。

    转到“API Gateway”页面

    进入“API Gateway”页面后:

    1. 选择要查看的 API。
    2. 点击详情标签页。
    3. 点击日志下的链接。

清理

为避免系统因本快速入门中使用的资源向您的 Google Cloud 账号收取费用,您可以执行以下操作:

或者,您还可以删除本教程中使用的 Google Cloud 项目。