配置开发环境

本文档介绍如何配置 API Gateway 开发环境。

前提条件

在 API Gateway 上创建 API 之前,请确保您已经:

  • 创建一个 Google Cloud 项目,并且您在该项目中拥有 EditorOwner 角色。在初次部署之后,您可以向用户、组或服务账号授予具有更多限制的服务配置编辑者角色。

  • 按照下文所述准备了 Google Cloud CLI

  • 下文所述,启用必需 Google 服务。

  • 下文所述,配置用于创建 API 配置的服务账号。

准备 Google Cloud CLI 以进行部署

如需为部署准备 gcloud,请执行以下操作:

  1. 安装并初始化 gcloud CLI
  2. 更新 gcloud CLI:
    gcloud components update
  3. 确保 gcloud CLI 有权访问您的数据和服务:
    gcloud auth login

    您的浏览器会打开一个新标签页,并提示您选择一个账号。

  4. 设置默认项目。将 PROJECT_ID 替换为您的 Google Cloud 项目 ID:
    gcloud config set project PROJECT_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,创建或更新 API 配置或网关的用户需要拥有该服务账号对象的 iam.serviceAccounts.actAs 权限。此权限包含在 Service Account User 角色中。

您可以使用以下命令将角色和权限添加到用户的服务账号:

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
  --member user:USER_EMAIL \
  --role roles/iam.serviceAccountUser

其中:

  • SERVICE_ACCOUNT_EMAIL 是服务账号的电子邮件地址,格式为 SA_NAME@PROJECT_ID.iam.gserviceaccount.com
  • USER_EMAIL 是用户的电子邮件地址。

例如:

gcloud iam service-accounts add-iam-policy-binding my-service-account@my-project.iam.gserviceaccount.com \
  --member user:myemail@email.com \
  --role roles/iam.serviceAccountUser

此外,网关服务账号需要具备访问后端服务所需的权限。例如:

  • 对于 Cloud Function 后端,必须为服务账号分配 Cloud Functions Invoker 角色。
  • 对于 Cloud Run 后端,必须为服务账号分配 Cloud Run Invoker 角色。
  • 对于 App Engine 后端,您必须按照设置 IAP 访问权限中的步骤,向与您的网关关联的服务账号授予 IAP-secured Web App User 角色。

通过限制与 API 配置关联的权限,您可以更好地保护后端系统。如需了解详情,请参阅 Identity and Access Management (IAM) 文档

创建服务账号后,请在创建 API 配置时使用 --backend-auth-service-account 选项指定该服务账号的电子邮件地址:

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION --project=PROJECT_ID \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

如需详细了解如何创建 API 配置,请参阅创建 API

使用默认服务账号

某些 GCP 产品定义了默认服务账号。例如,如果您使用 Compute Engine 并为项目启用了 Compute Engine API,则系统会为您创建默认 Compute Engine 服务账号。通过电子邮件地址可识别默认服务账号:

PROJECT_NUMBER-compute@developer.gserviceaccount.com

如果您为默认服务账号分配了必要的权限,可以省略 --backend-auth-service-account 选项:

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION --project=PROJECT_ID

如需了解详情,请参阅使用 Compute Engine 默认服务账号

使用 OpenID Connect

从 API Gateway 到后端服务的请求可能会使用身份验证。这些请求使用由网关的服务账号签名的 OpenID Connect (OIDC) 令牌进行保护。您应确认您的后端服务已正确配置为接受使用 OIDC 令牌进行身份验证和授权。Cloud Run 函数、Cloud Run 和 Identity Aware Proxy (IAP) 提供此选项。

后续步骤