对 API 进行版本控制

本页面详细介绍了有关更改 API 版本号的配置和部署步骤。您使用的具体步骤取决于您对 API 的更改是否向后兼容。

  • 如果您的新 API 版本包含向后兼容的更改，例如您添加了新的字段或方法，请参阅向后兼容的更改。
  • 如果您的新 API 对某现有方法进行了更改，而所做更改会导致客户的客户端代码无法正常工作，请参阅不向后兼容的更改。

如需了解更多信息和最佳做法，请参阅 API 生命周期管理。

向后兼容的更改

如果您对 API 进行的更改向后兼容现有客户端代码，那么您最好在部署新版本之前增加 API 的次要版本号。虽然 Cloud Endpoints 一次只运行一个 API 次要版本，但 Endpoints > 服务中的图表和日志会显示版本号。如果在部署之前增加次要版本号，则图表和日志便会在部署记录上添加一个标记。

要增加次要版本号，请执行以下操作：

  1. 在 openapi.yaml 中，增加 info.version 字段的次要版本号。例如，如果当前版本为 1.1，请将 info.version 设置为 1.2：

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.2"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

  2. 使用 Google Cloud CLI 部署 API 配置：

    gcloud endpoints services deploy openapi.yaml

  3. 使用上一步中返回的配置 ID 部署 API 后端。如需了解详情，请参阅部署 API 后端。

不向后兼容的更改

如果您对 API 进行的更改会导致客户的客户端代码无法正常运行，那么您最好增加 API 的主要版本号。Endpoints 可以并行运行 API 的多个主要版本。提供两个 API 版本后，您的客户便可在迁移到新版本时选择要使用和控制的版本。

要并行运行 API 的现有版本和新版本，请执行以下操作：

  1. 为您需要提供的每个版本创建单独的 OpenAPI 配置文件。此步骤以 openapi-v1.yaml 和 openapi-v2.yaml 作为示例文件名。

  2. 将 openapi-v1.yaml 的内容复制到 openapi-v2.yaml。

  3. 在 openapi-v1.yaml 中配置以下内容：

    • 将 info.version 字段设置为现有版本号。
    • 保持 basePath 字段不变。

    例如：

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.1"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v1"

  4. 在 openapi-v2.yaml 中配置以下内容：

    • 进行不向后兼容的更改。
    • 将 info.version 字段设置为新版本号。
    • 设置 basePath 字段以包含新的主要版本号。
    • 移除 x-google-endpoints 部分。如果要指定 DNS IP 地址或 allowCors 标志，则需要本部分。使用两个 yaml 配置文件部署两个版本的 API 时，其中只有一个可以具有 x-google-endpoints，但它的配置将应用于两个版本。

    例如：

    info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "2.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v2"

  5. 使用 Google Cloud CLI 部署两个 API 配置文件：

    gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml

  6. 部署单个后端，该后端使用上一步中返回的配置 ID 同时提供两个 API 版本提供。如需了解详情，请参阅部署 API 后端。

后续步骤