API Gateway 和 App Engine 使用入门

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

任务列表

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

  1. 创建或选择 Google Cloud 项目。
  2. 如果您尚未部署自己的 App Engine，请部署一个示例应用。请参阅准备工作。
  3. 启用所需的 API Gateway 服务。
  4. 配置 IAP 来保护应用。请参阅配置 IAP。
  5. 创建描述 API 的 OpenAPI 规范，并配置到您的 App Engine 的路由。请参阅创建 API 配置。
  6. 使用您的 API 配置部署 API Gateway。 请参阅部署 API Gateway。
  7. 跟踪您的应用的活动。请参阅跟踪 API 活动。
  8. 避免向您的 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. 如果您尚未部署自己的 App Engine 应用，请按照与您所用语言对应的 App Engine 快速入门中的步骤操作，使用 Google Cloud CLI 选择或创建一个 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 服务。

配置 IAP 以确保应用安全

为了保护 App Engine 应用，您必须使用 Identity Aware Proxy (IAP) 来确保对请求进行身份验证。此流程包括指定应授予项目所需 IAP-secured Web App User 角色的成员。

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

创建 API 配置

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

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

  1. 创建名为 openapi2-appengine.yaml 的文本文件。（为方便起见，本页面用此文件名指代 OpenAPI 规范；如果愿意，您也可改用其他名称。）
  2. 在 openapi2-appengine.yaml 文件的 paths 部分列出您的每个应用，如下所示： 
    # openapi2-appengine.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with an App Engine backend
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: APP_URL
        jwt_audience: IAP_CLIENT_ID
      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 替换为 App Engine 服务的实际网址（调用的 API 的完整路径）。例如 https://myapp.an.r.appspot.com/hello。

    将 IAP_CLIENT_ID 替换为您在设置 IAP 时创建的 OAuth 客户端 ID。

  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-appengine.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 网关

现在，您可以在 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 发送请求。

输入以下 curl 命令，其中：

  • DEFAULT_HOSTNAME 指定已部署的网关网址的主机名部分。您可以在上面显示的 gateways describe 命令的输出中找到 defaultHostname 的值。
  • hello 是 API 配置中指定的路径。
curl https://DEFAULT_HOSTNAME/hello

例如：

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

您应该会看到以下输出内容：

My-AppEngineApp: Access denied for user gateway-1a2b3c@04d5e6f35FgdsT73dFrty-tp.iam.gserviceaccount.com requesting https://my-project.appspot.com/helloGET. If you should have access, contact myldap@google.com and include the full text of this message.

大功告成！您的网关正在管理对 App Engine 后端服务的访问权限。如需授予对 App Engine 应用的访问权限，您需要为网关配置具有正确权限的服务账号。

跟踪 API 活动

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

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

    转到“API Gateway”页面

    进入“API Gateway”页面后：

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

清理

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

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