创建 API 配置

前提条件

在创建 API 配置之前，请确保您已经：

API 配置 ID 要求

下面显示的许多 gcloud 命令都要求您指定 API 配置的 ID，格式为 CONFIG_ID。API Gateway 对 API 配置 ID 实施以下要求：

  • 长度不得超过 63 个字符。
  • 只能包含小写字母、数字或短划线。
  • 不能以短划线开头。
  • 不得包含下划线。

创建 API 配置

使用 Google Cloud CLI 上传 API 定义以创建 API 配置。上传 API 定义时，您需要指定 API 的名称。如果 API Gateway 中不存在此 API，则此命令也会创建它。

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

  1. 将目录更改为包含 API 定义的目录。

    如需详细了解如何为 API 定义创建 OpenAPI 规范，请参阅 OpenAPI 概览和快速入门：在 API Gateway 上部署 API。

    如需详细了解如何为 API 定义创建 gRPC 服务的定义和配置，请参阅配置 gRPC 服务和使用入门：API Gateway 和 Cloud Run for gRPC。

  2. 验证下面的命令返回的项目 ID，以确保不会在错误的项目中创建服务。

    gcloud config list project

    如果需要更改默认项目，请运行以下命令并将 PROJECT_ID 替换为要在其中创建服务的 Google Cloud 项目 ID：

    gcloud config set project PROJECT_ID

  3. 查看 api-configs create 命令的相关帮助：

    gcloud api-gateway api-configs create --help

  4. 运行以下命令以创建 API 配置：

    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

    其中：

    • CONFIG_ID 指定新 API 配置的 ID。
    • API_ID 指定与此 API 配置关联的 API Gateway API 的 ID。如果 API 尚不存在，则此命令会创建该 API。
    • API_DEFINITION 指定包含 API 定义的 OpenAPI 规范的名称。
    • PROJECT_ID 指定 Google Cloud 项目 ID。
    • SERVICE_ACCOUNT_EMAIL 用于指定用于为已配置身份验证的后端签名令牌的服务账号。如需了解更多详情，请参阅配置服务账号。

    在创建 API 和 API 配置时，API Gateway 会将信息输出到终端。此操作可能需要几分钟才能完成，因为 API 配置会传播到下游系统。复杂 API 配置的创建最多可能需要 10 分钟才能完成。创建配置时，请勿尝试为同一 API 创建其他配置。一次只能为任意 API 创建一个配置。

  5. 成功完成后，您可以使用以下命令查看有关新 API 配置的详细信息：

    gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_ID

    此命令会返回以下内容：

    createTime: '2020-02-04T18:33:11.882707149Z'
displayName: CONFIG_ID
gatewayConfig:
  backendConfig:
    googleServiceAccount: 1111111@developer.gserviceaccount.com
labels: ''
name: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
serviceRollout:
  rolloutId: 2020-02-04r2
state: ACTIVE
updateTime: '2020-02-04T18:33:12.219323647Z'

  6. 使用该 API 的托管式服务名称启用该 API。您可以在该 API 着陆页上的 API 的“托管式服务”列中找到此值：

    gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog

    创建该 API 时，您只需运行一次此命令。如果您稍后修改 API，则不需要重新运行命令。

Google Cloud CLI 支持许多选项，包括 gcloud 参考。此外，对于 API Gateway，您可以在创建 API 配置时设置以下选项：

  • --async：立即将控制权归还给终端，而不等待操作完成。
  • --display-name=NAME：指定 API 配置的显示名称，即界面中显示的名称。请勿在名称中使用空格。请改用连字符和下划线。默认值为 CONFIG_ID。
  • --labels=KEY1=VALUE1,KEY2=VALUE2,...：指定与 API 配置关联的标签。

例如：

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 \
  --async --display-name=MyConfig --labels=a=1,b=2

您可以在上面显示的 describe 命令的输出中看到标签，也可以通过添加 --format 选项在 list 命令中查看标签：

gcloud api-gateway api-configs list \
  --api=API_ID --project=PROJECT_ID --format="table(name, labels)"

列出 API 配置

如需列出特定项目的 API 配置，请运行以下命令：

gcloud api-gateway api-configs list --project=PROJECT_ID

此命令会返回以下内容：

NAME                                                                DISPLAY_NAME  ROLLOUT_ID    STATE   CREATE_TIME
projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID  CONFIG_ID     2020-02-04r0  ACTIVE  2020-02-04T16:18:02.369859863Z

如需列出项目中特定 API 的 API 配置，请运行以下命令：

gcloud api-gateway api-configs list --api=API_ID --project=PROJECT_ID

使用项目、API 和配置 ID 获取有关 API 配置的详细信息：

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_ID

更新 API 配置

您无法修改现有 API 配置，只能更新其标签和显示名称。

使用以下 gcloud 更新现有 API 配置：

  • --display-name
  • --update-labels
  • --clear-labels
  • --remove-labels

例如：

gcloud api-gateway api-configs update CONFIG_ID \
  --api=API_ID  --project=PROJECT_ID \
  --update-labels=a=1,b=2

使用以下命令查看所有更新选项：

gcloud api-gateway api-configs update --help

删除 API 配置

使用以下 gcloud 命令删除现有 API 配置：

gcloud api-gateway api-configs delete CONFIG_ID --api=API_ID --project=PROJECT_ID

后续步骤