部署 Endpoints 配置

OpenAPI | gRPC

在 OpenAPI 文档中配置 Cloud Endpoints 后，您可以对其进行部署，以使 Endpoints 具备管理 API 所需的信息。如需部署 Endpoints 配置，请使用 gcloud endpoints services deploy 命令。此命令会使用 Service Infrastructure，这是 Google 的基础服务平台，供 Endpoints 及其他服务用来创建并管理 API 和服务。本页面介绍如何将 OpenAPI 文档部署到 Endpoints。

前提条件

首先，本页假定您已完成以下操作：

创建一个 Google Cloud 项目，并且您在该项目中拥有 Editor 或 Owner 角色。在初次部署之后，您可以向用户、组或服务账号授予具有更多限制的 Service Config Editor 角色。如需了解详情，请参阅授予和撤消对 API 的访问权限。
配置 Endpoints。
如果您使用的是自定义域名（例如 my-api.example.com），您必须先验证域名，然后才能部署 OpenAPI 文档。

准备 Google Cloud CLI 以进行部署

您可以使用 gcloud 命令行工具来部署配置。如需详细了解相关命令，请参阅 gcloud 参考。

要准备部署，请执行以下操作：

安装并初始化 gcloud CLI。
更新 gcloud CLI：
```
gcloud components update
```
确保 gcloud CLI 有权访问您的数据和服务：
```
gcloud auth login
```
您的浏览器会打开一个新标签页，并提示您选择一个账号。
设置默认项目。请将 [YOUR-PROJECT-ID] 替换为您的 GCP 项目 ID
```
gcloud config set project [YOUR-PROJECT-ID]
```
如果您要将 API 后端部署到 Kubernetes 或 Kubernetes Engine，请运行以下命令，以获取用于应用默认凭据的新用户凭据。需要用户凭据才能授权 kubectl。
```
gcloud auth application-default login
```
浏览器会打开一个新的标签页，并提示您选择账号。

验证 `openapi.json` 语法

OpenAPI 文档文件可以采用 YAML 格式或 JSON 格式。对于 JSON 格式的文件，我们建议您在部署此文件之前先验证语法。如需检查 openapi.json 是否为格式正确的 JSON 文件，您可以使用 JSON 验证文本编辑器（如 vim）、使用在线 JSON linter 服务或使用如下所示的 Python 打开该文件：

python -m json.tool openapi.json

如需提高可读性，您可以输出格式整齐的 JSON 文件：

python -m json.tool input.json > output.json

请将 input.json 替换为 openapi.json 文件的路径。output.json 是格式整齐的 JSON 文件。

验证 OpenAPI 文档

并非所有 OpenAPI 结构目前都受 Cloud Endpoints 支持。您可以在部署前验证 OpenAPI 文档。

要验证 OpenAPI 文档，请执行以下操作：

将目录切换到 OpenAPI 文档所在的位置。
确认要在其中创建服务的 Google Cloud 项目。如果您使用的是自定义域名（例如 myapi.example.com），请务必验证下面的命令返回的项目 ID，以确保不会在错误的项目中创建服务。
```
gcloud config list project
```
如果需要更改默认项目，请运行以下命令并将 [YOUR_PROJECT_ID] 替换为要在其中创建服务的 Google Cloud 项目 ID：
```
gcloud config set project [YOUR_PROJECT_ID]
```
运行以下命令，并将 [YOUR_OPENAPI_DOCUMENT] 替换为描述 API 的 OpenAPI 文档名称：
```
gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT] --validate-only
```

然后，gcloud 命令会调用 Service Management API，以便使用您在 OpenAPI 文档的 host 字段中指定的名称创建托管式服务。如果您指定 --validate-only 标志，系统仍会创建服务，但不会部署配置。如果未创建服务，则无法验证 OpenAPI 文档。您可以删除该服务，但在大约 30 天的时间内，Service Management 将会阻止您创建同名的服务。

部署 OpenAPI 文档

准备好部署 API 时，可运行 Google Cloud CLI，该工具会使用 Service Management 上传 API 配置并创建（或更新）代管式服务。

要部署 OpenAPI 文档，请执行以下操作：

将目录切换到 OpenAPI 文档所在的位置。
验证下面的命令返回的项目 ID，以确保不会在错误的项目中创建服务。
```
gcloud config list project
```
如果需要更改默认项目，请运行以下命令并将 [YOUR_PROJECT_ID] 替换为要在其中创建服务的 Google Cloud 项目 ID：
```
gcloud config set project [YOUR_PROJECT_ID]
```
运行以下命令，并将 [YOUR_OPENAPI_DOCUMENT] 替换为描述 API 的 OpenAPI 文档名称：
```
gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT]
```

首次运行前面这条命令时，Service Management 会在默认项目中创建一项新的 Endpoints 服务，服务名称与您在 OpenAPI 文档的 host 字段中指定的文本一致。

在创建和配置服务时，Service Management 会向终端输出信息。成功完成后，您会看到如下所示的行，其中会显示服务配置 ID 和服务名称：

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

在前面的示例中，2017-02-13r0 是服务配置 ID，echo-api.endpoints.example-project-12345.cloud.goog 是服务名称。

成功部署后，您可以在 Google Cloud 控制台的端点 > 服务页面上查看该 API。

如果您收到错误消息，请参阅排查 Endpoints 配置部署问题。

重新部署

只要您更改了 OpenAPI 文档中的内容，就必须重新进行部署，以确保 Endpoints 采用最新版本的 API 服务配置。如果您之前部署了 ESP 且 rollout 选项设置为 managed，则无需重新部署或重启 ESP。此选项将 ESP 配置为使用最新部署的服务配置。指定此选项后，在部署新的服务配置后，ESP 最多会在 5 分钟内检测到更改并自动开始使用该服务配置。建议您指定此选项，而非让 ESP 使用特定的配置 ID。

在完成初始的 Endpoints 配置部署之后，您可以向用户、服务账号或组授予一个角色，使他们可以重新部署 Endpoints 配置。如需了解详情，请参阅授予和撤消对 API 的访问权限。