对 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. 使用 gcloud 命令行工具部署 API 配置:

    gcloud endpoints services deploy openapi.yaml
        
  3. 使用上一步中返回的配置 ID 部署 API 后端。如需了解详情,请参阅部署 API 后端

不向后兼容的更改

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

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

  1. 为您需要提供的每个版本创建单独的 OpenAPI 配置文件。此步骤以 openapi-v1.yamlopenapi-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”标志,则需要“x-google-endpoints”。在使用两个 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. 使用 gcloud 命令行工具部署两个 API 配置文件:

    gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml
        
  6. 部署单个后端,该后端使用上一步中返回的配置 ID 提供两个 API 版本。如需了解详情,请参阅部署 API 后端

后续步骤