Azure 服务、SDK 和 CLI 工具的版本控制策略

  • 项目

大多数 Azure 服务都允许使用 REST API 以编程方式控制和管理其资源。 服务通过具有不同协定的新发布的 API 版本来发展，这些协定会添加新功能和/或修改其行为。

本文概述了 Azure 服务、SDK 和 CLI 团队用于对 Azure REST API 进行版本控制的策略。 虽然 Azure 团队尽一切努力遵守此策略，但有时会发生偏差。

服务版本控制

API 的每个已发布版本都由格式的日期值YYYY-MM-DD标识，称为 <a0/>。 较新版本的日期较晚。

所有 API 操作都需要客户端通过 api-version URL 中的查询字符串参数为服务指定有效的 API 版本。 例如：https://management.azure.com/subscriptions?api-version=2020-01-01。 客户端 SDK 和工具会自动包含 api-version 该值。 有关更多注意事项，请参阅 本文后面的客户端 SDK 和服务版本 部分。

通常，已发布的服务版本在很多年内仍可用且受支持，即使较新版本可用也是如此。 在大多数情况下，在现有代码中采用新服务版本的唯一时间是利用新功能。

稳定版本

发布的大多数服务版本都是 稳定的版本。 稳定版本向后兼容，这意味着你编写的依赖于一个服务版本的任何代码都可以采用较新的稳定版本，而无需任何代码更改来保持正确性或现有功能。

中断性变更版本

服务 中断性变更版本 不向后兼容。 在现有客户端代码中采用中断性变更版本可能需要更改代码，以确保客户端的行为与针对以前的版本时的行为完全相同。

中断性变更版本很少见，通过文档宣布，通常先于发布预览版。 发布中断性变更版本可能会促使现有稳定版本最终停用，在中断性变更版本发布后，该版本将持续至少三年。 对于因安全或符合性问题而发布的中断性变更，现有的稳定服务版本可能会保留一年或更短的时间，具体取决于问题的严重性。

由于 AI 的快速创新和开发，AI 驱动的服务可能缩短了一年的最低可用性。 每个服务都会发布其中断性变更策略。

依赖于非 Microsoft 组件的任何 Azure 服务都可以收缩其支持策略，以匹配组件的策略。 由于此原因导致的任何中断性变更都将链接到组件供应商的策略，其中显示了不再支持组件时的日期。

预览版

有时，Microsoft 会发布 服务的预览版本 ，以收集有关建议的更改和新功能的反馈。 预览服务版本使用后api-version缀-preview进行标识，例如2022-07-07-preview。

除非明确打算从以前的稳定版本引入中断性变更，否则新的预览版本包括最新稳定版本的所有功能，并添加新的预览功能。 但是，在预览版本之间，服务可能会中断任何新添加的预览功能。

预览版不适用于长期使用。 每当新的稳定版本或预览版服务可用时，现有预览版本可能早在新版本的可用 90 天后就不可用。 仅在你主动针对新服务功能进行开发的情况下使用预览版本，并且你准备在发布后不久采用新的非预览版本。 如果预览版中的某些功能以新的稳定版本发布，则剩余功能仍以预览版发布，通常将在新的预览版本中发布。

客户端 SDK 和服务版本

Azure SDK 旨在消除编写代码时服务版本控制的问题。 每个 SDK 由客户端库组成，每个服务各有一个，每个客户端库版本面向它依赖的服务的单个版本。

使用 SDK 访问 Azure 服务时，利用新版本和功能通常需要升级应用程序使用的客户端库版本。 新的稳定版本的服务伴随着客户端库的新点版本。 对于新的中断性变更版本，新的客户端库作为点发布版本或主要发布版本发布。 发布类型取决于服务更改的性质以及库能够容纳它的方式。 仅 beta 版本客户端库使用预览服务版本。

SDK 客户端库支持手动重写服务版本。 重写客户端库的默认服务版本是一种高级方案，可能会导致意外行为。 如果使用此功能，请彻底测试应用程序，以确保它按预期工作。

Azure 命令行工具

与 SDK 一样，Azure 命令行工具（包括 Azure CLI 和 Azure PowerShell）旨在允许在不考虑版本的情况下使用 Azure 管理服务。 访问新的服务功能通常需要新版本的工具。 每月发布新的向后兼容工具版本。 具有重大更改的版本每年大约发布两次，或根据需要修复关键安全问题。

Azure 命令行工具偶尔可能会公开预览功能。 这些命令标有 Preview 标签，并输出一条警告，指示将来工具版本中的支持有限和潜在更改。

后续步骤