创建 API 配置

本页介绍了如何创建要在 API Gateway 上部署的 API 配置。

准备工作

在创建 API 配置之前，请执行以下操作：

按照配置开发环境中的说明准备开发环境。
创建 API 定义作为 OpenAPI 规范。
如果使用 Google Cloud CLI，可以选择创建 API。如果 API 不存在，则创建 API 配置会创建该 API。

注意：使用 Google Cloud 控制台时，API 和 API 配置会在将 API 部署到网关时创建。

API 配置 ID 要求

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

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

创建 API 配置

通过上传 API 定义来创建 API 配置。

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

Google Cloud 控制台

在将 API 部署到网关时创建 API 配置。

Google Cloud CLI

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

切换到包含 API 定义的目录。

如需详细了解如何为 API 定义创建 OpenAPI 规范，请参阅 OpenAPI 概览和快速入门：使用 gcloud CLI 保护服务的流量安全。

如需详细了解如何为 API 定义创建 gRPC 服务的定义和配置，请参阅配置 gRPC 服务和使用入门：API Gateway 和 Cloud Run for gRPC。
验证下面的命令返回的项目 ID，以确保不会在错误的项目中创建服务。
```
gcloud config list project
```
如果需要更改默认项目，请运行以下命令并将 PROJECT_ID 替换为要在其中创建服务的 Google Cloud 项目 ID：
```
gcloud config set project PROJECT_ID
```
查看 api-configs create 命令的相关帮助：
```
gcloud api-gateway api-configs create --help
```
运行以下命令以创建 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 规范的名称。
- SERVICE_ACCOUNT_EMAIL 指定用于为配置了身份验证的后端对令牌进行签名的服务账号。如需了解详情，请参阅配置用于创建 API 配置的服务账号。
在创建 API 和 API 配置时，API Gateway 会将信息输出到终端。此操作可能需要几分钟才能完成，因为 API 配置会传播到下游系统。复杂 API 配置的创建最多可能需要 10 分钟才能成功完成。创建配置时，请勿尝试为同一 API 创建其他配置。一次只能为任意 API 创建一个配置。

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

gcloud api-gateway api-configs describe CONFIG_ID \
      --api=API_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'

使用该 API 的代管式服务名称启用该 API。您可以在该 API 着陆页上的 API 的“托管式服务”列中找到此值：
```
gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
```
创建该 API 时，您只需运行一次此命令。如果您稍后修改 API，则不需要重新运行命令。

gcloud CLI 接受许多选项，包括 Google Cloud CLI 参考中所述的选项。此外，对于 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 \
  --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 --format="table(name, labels)"

列出 API 配置

列出已部署在 Google Cloud 项目中的所有 API 网关。

Google Cloud 控制台

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

在 Google Cloud 控制台中，前往 API Gateway 页面。

前往 API Gateway
点击所需的 API。
点击配置标签页。

您会在页面上看到可用 API 配置的列表。

Google Cloud CLI

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

gcloud api-gateway api-configs list

此命令会返回以下内容：

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

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

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

更新 API 配置

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

Google Cloud 控制台

在 Google Cloud 控制台中，前往 API Gateway 页面。

前往 API Gateway
点击所需的 API。
点击配置标签页。
点击所需的 API 配置。
依次点击修改修改。
修改显示名称或标签。
点击保存。

Google Cloud CLI

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

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

例如：

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

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

gcloud api-gateway api-configs update --help

删除 API 配置

在删除正在使用的 API 配置之前，您必须执行以下操作之一：

将其他 API 配置部署到网关。
删除网关。

如需了解详情，请参阅将 API 部署到网关。

Google Cloud 控制台

在 Google Cloud 控制台中，前往 API Gateway 页面。

前往 API Gateway
点击所需的 API。
点击配置标签页。
点击更多图标，然后点击删除以删除所选的 API 配置。

Google Cloud CLI

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

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

后续步骤

将 API 部署到网关