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 网关。 请参阅部署 API 网关。
  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 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 获得调用应用所需的信息。

如需详细了解支持的 OpenAPI 扩展程序，请参阅以下内容：

如需创建 API 配置，请执行以下操作：

  1. 创建名为 openapi-run.yaml 的文本文件。为方便起见，本页面用此文件名指代 OpenAPI 说明，但如果您愿意的话，也可以改用其他名称。
  2. 将以下文件的内容复制到您的 openapi-run.yaml 文件中：

    OpenAPI 2.0

    # openapi-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
    • 在 title 字段中，将 API_ID 替换为您的 API 名称，并将 optional-string 替换为您选择的简要说明。如果您的 API 尚不存在，则创建 API 配置的命令也会使用您指定的名称创建 API。 在创建授予对此 API 访问权限的 API 密钥时，会用到 title 字段的值。请参阅 API ID 要求，了解 API 命名准则。
    • 在 x-google-backend 部分的 address 字段中，将 APP_URL 替换为 Cloud Run 服务的实际网址（调用的 API 的完整路径）。例如：https://hello-abc1def2gh-uc.a.run.app。

    OpenAPI 3.x

    # openapi-run.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Cloud Run backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backends:
    cloudrun_backend:
      address: APP_URL
      deadline: 30.0
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: cloudrun_backend
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        "200":
          description: A successful response
          content:
            application/json:
              schema:
                type: string
    • 在 title 字段中，将 API_ID 替换为您的 API 名称，并将 optional-string 替换为您选择的简要说明。如果您的 API 尚不存在，则创建 API 配置的命令也会使用您指定的名称创建 API。 在创建授予对此 API 访问权限的 API 密钥时，会用到 title 字段的值。请参阅 API ID 要求，了解 API 命名准则。
    • 在 address 字段中，将 APP_URL 替换为 Cloud Run 服务的实际网址（调用的 API 的完整路径）。例如：https://hello-687541448612.us-central1.run.app。
  3. 输入以下命令，其中：
    • 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 分钟才能完成。

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

部署 API 网关

现在，您可以在 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-687541448612.us-central1.run.app/hello

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

大功告成！您的网关正在管理对 Cloud Run 后端服务的访问权限。

跟踪 API 活动

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

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

    进入“API Gateway”页面后：

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

清理

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

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