Compute Engine 版本控制指南：API、客户端库和工具

本指南介绍了 Compute Engine 如何跨 REST API、客户端库和 gcloud 命令行工具管理版本。 本文介绍了基于渠道的版本控制 (CBV) 和基于接口的版本控制 (IBV) 之间的区别，但主要侧重于后者。

准备工作

  • 如果您尚未设置身份验证，请进行设置。身份验证用于验证您的身份，以便访问 Google Cloud 服务和 API。如需从本地开发环境运行代码或示例，您可以通过选择以下选项之一向 Compute Engine 进行身份验证：

    选择标签页以了解您打算如何使用本页面上的示例：

    控制台

    当您使用 Google Cloud 控制台访问 Google Cloud 服务和 API 时，无需设置身份验证。

    gcloud

    1. 安装 Google Cloud CLI。 安装完成后，运行以下命令来初始化 Google Cloud CLI： 

      gcloud init

      如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

  • 设置默认区域和可用区。

    • REST

    如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭证。

      安装 Google Cloud CLI。

      如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

    如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

基于渠道的版本控制和基于接口的版本控制

Compute Engine API 支持两种版本控制方案：基于渠道的版本控制 (CBV) 和基于接口的版本控制 (IBV)。

  • 在基于渠道的版本控制中，发布版本具有较长的生命周期，并会接收就地更新。Compute Engine 支持 v1、Beta 版和 Alpha 版渠道。

  • 在基于接口的版本控制中，各个接口、方法和资源都具有版本，并且可以逐步独立地发展。

IBV 取代了 CBV。不过，CBV 的现有实现不受 IBV 的引入和新版本的影响。如果您希望继续使用现有 API 版本，可以继续使用 CBV。

IBV 可帮助您确信 API 的行为及其请求和响应载荷符合预期的 API 版本。您可以通过在请求中使用查询参数或标头指定 API 版本来使用 IBV。如需了解详情，请参阅创建 API 请求。

使用 IBV 具有以下优势：

  • 提高稳定性：IBV 允许您指明服务必须响应的 API 版本，从而保护正在运行的应用免受更改的影响。
  • 对变更采用的控制：借助 IBV，您可以选择哪个版本来处理您的请求。这样，您就可以根据自己的安排升级到新的服务功能。

如需详细了解版本控制策略，请参阅 API 改进提案 185。

基于接口的版本控制政策

Compute Engine IBV API 的每个版本都是一组共享同一服务版本的接口变更，即使接口可能会独立更改版本也是如此。

Compute Engine IBV API 支持稳定版和预览版。

稳定版本

大多数 API 版本都是稳定版本。稳定版本会严格保持兼容性（如 AIP-180 中所定义），这意味着同一版本的新稳定版本不会破坏现有功能，也不需要重写代码。

Compute Engine 使用 YYYY-MM-DD 格式（例如 2026-09-01）的标准日期来标识稳定的 API 版本。日期越晚，表示版本越新。

Compute Engine 在较长时间内支持稳定版本，因此您的生产系统可以保持可靠且不间断地运行。 对于大多数应用，您只需使用一个稳定版本即可执行日常任务。

预览版

Compute Engine 可以发布预览版，以便收集用户对新功能的早期反馈。预览版会在日期后附加 -preview 标记（例如 2026-10-01-preview）。

预览版包含最新稳定版的所有功能，以及新添加的实验性功能。使用预览版时，请注意以下几点：

  • 预览版功能无法保证与之前或未来的版本兼容。
  • 我们不建议在任务关键型生产环境中使用预览版。
  • 在将预览版功能升级为稳定版的过程中，我们可能会更改、改进或移除这些功能。

如果您想试用新功能，请使用预览版，并计划在稳定版发布后更新代码。

在请求中指定 API 版本

如需使用 IBV 进行 API 调用，您的请求应使用查询参数或标头指定目标版本。如需查看有关如何发出 API 请求的示例，请参阅创建 API 请求。

Cloud 客户端库

Cloud 客户端库可减轻构建和解析原始 REST 调用的负担。每个库版本都直接连接到特定的基于日期的 API 版本。

如需使用新功能，请将 Cloud 客户端库软件包更新到最新版本。我们会随新的稳定版和预览版 API 发布更新的 Cloud 客户端库。

我们建议在稳定的 Cloud 客户端库上运行生产应用，同时将预览版库隔离到测试环境中。

Google Cloud CLI (gcloud)

借助 gcloud CLI，您可以管理 Compute Engine 资源，而无需手动跟踪各个 REST 端点。

gcloud CLI 将命令分为两类：

  • 稳定版命令：标准命令（例如 gcloud compute instances create）以稳定版 API 版本为目标。 这些命令完全受支持，可预测，建议用于生产脚本。
  • 预览版命令：抢先体验版功能使用 gcloud preview 群组（例如 gcloud preview compute ...）。这些命令会显示简短的警告，因为合同可能会在最终发布之前发生变化。

Terraform

Google Cloud Terraform 提供程序可抽象化 API 版本控制并管理底层 API 交互。Terraform 配置不会公开或要求手动设置版本标头。

如需使用新功能，请将 Google Cloud Terraform 提供方更新到最新版本。对于预览版功能，请使用 google-beta 提供程序。

常见问题解答

本部分解答了有关 Compute Engine API 版本控制的常见问题。

  • 我是否必须从 v1（CBV）迁移到 IBV？

    不会，现有的 CBV v1 API 请求会继续像以前一样运行。不过，您将无法使用 IBV API 中的新功能。

  • IBV API 版本将支持多长时间？

    稳定版本会根据标准 Google Cloud弃用政策永久维护。

  • 新版 IBV API 的发布频率如何？

    我们计划每季度发布新的 IBV API 版本。预览版可随时发布。

  • 我需要在 Google Cloud 控制台中启用任何内容吗？

    否，IBV API 默认随 Compute Engine API 一起启用。

  • 如果我在请求中未指定版本，会发生什么情况？

    您的请求默认使用 CBV v1 端点。

  • 在哪里可以找到 Cloud Audit Logs 条目中的 API 版本？

    API 版本记录在 protoPayload.requestMetadata.callerSuppliedUserAgent 中以及请求标头或查询参数中。

后续步骤

如需详细了解 Compute Engine API，请参阅以下文档：