API Gateway 和 Cloud Run 使用入门

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

任务列表

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

  1. 创建或选择 Google Cloud 项目。
  2. 如果您尚未部署自己的 Cloud Run，请部署一个示例服务。请参阅准备工作中的第 7 步。
  3. 启用所需的 API Gateway 服务。
  4. 创建 OpenAPI 规范 用于描述您的 API 以及配置到您 API 的路由， 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. 在 API Gateway 页面上查看 API 的活动图表， Google Cloud 控制台。点击您的 API 以在概览页面上查看其活动图表。请求可能要过一些时间才能反映在图表中。

  2. 在日志浏览器页面上查看 API 的请求日志。指向 日志浏览器页面位于 Google Cloud 控制台。

    转到“API Gateway”页面

    进入“API Gateway”页面后：

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

清理

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

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