Azure 服務、SDK 和 CLI 工具的版本控制原則

發行項
12/13/2023

大部分的 Azure 服務可讓您以程式設計方式使用 REST API 來控制和管理其資源。服務會隨著其 API 的新發行版本而演進，並使用不同的合約來新增功能和/或修改其行為。

本文概述 Azure 服務、SDK 和 CLI 小組用來建立 Azure REST API 版本的原則。雖然 Azure 小組會盡一切努力遵守此原則，但可能會偶爾發生偏差。

服務版本控制

每個已發布的 API 版本都會以格式的日期值 YYYY-MM-DD 來識別，稱為 api-version。較新的版本有較新版本的日期。

所有 API 作業都需要用戶端透過 api-version URL 中的查詢字串參數，為服務指定有效的 API 版本。例如： https://management.azure.com/subscriptions?api-version=2020-01-01 。用戶端 SDK 和工具會自動包含 api-version 值。如需詳細資訊，請參閱本文稍後的用戶端 SDK 和服務版本一節。

通常，即使有較新版本可供使用，已發佈的服務版本仍可供使用且支援多年。在大部分情況下，您唯一應該在現有程式代碼內採用新的服務版本，就是利用新功能。

穩定版本

大部分發行的服務版本都是 穩定的版本。穩定版本回溯相容，這表示您撰寫的任何依賴一個服務版本的程式代碼都可以採用較新的穩定版本，而不需要任何程式代碼變更來維護正確性或現有功能。

重大變更版本

服務 的重大變更版本 與回溯相容。在現有用戶端程式代碼中採用重大變更版本可能需要變更程式代碼，以確保客戶端的行為與以舊版為目標時的行為完全相同。

重大變更版本很少見，可透過檔宣告，且通常會在發行預覽版本之前。發行重大變更版本可能會促使現有穩定版本最終淘汰，在重大變更版本發行之後，至少三年內仍可使用。針對因安全性或合規性問題而發佈的重大變更，根據問題的嚴重性，現有的穩定服務版本可能會持續一年或更少。

由於 AI 的快速創新和開發，AI 驅動服務可能降低一年的最低可用性。每個服務都會發佈其重大變更原則。

任何相依於非 Microsoft 元件的 Azure 服務，都可以壓縮其支持原則，以符合元件的原則。由於此原因的任何中斷性變更都會連結到元件廠商的原則，其中顯示不再支援元件的日期。

預覽版本

有時候，Microsoft 會 發佈服務的預覽版本 ，以收集有關建議變更和新功能的意見反應。預覽服務版本會以其中的後綴-preview來識別，例如 2022-07-07-preview。api-version

除非明確打算從舊版引進重大變更，否則新的預覽版本會包含最新穩定版本的所有功能，並新增預覽功能。不過，在預覽版本之間，服務可能會中斷任何新增的預覽功能。

預覽不適用於長期使用。每當服務有新的穩定或預覽版本可供使用時，現有的預覽版本可能會從新版本的可用性起起 90 天就無法使用。只有在您主動針對新的服務功能進行開發，且準備在發行后不久採用新的非預覽版本時，才使用預覽版本。如果預覽版本中的某些功能以新的穩定版本發行，其餘功能仍處於預覽狀態，通常會以新的預覽版本發佈。

用戶端 SDK 和服務版本

Azure SDK 的目標是在撰寫程式代碼時排除服務版本設定作為考慮。每個 SDK 都由用戶端連結庫組成，每個服務各有一個，而每個用戶端連結庫版本是以它依賴的單一服務版本為目標。

當您使用 SDK 來存取 Azure 服務時，利用新版本和功能通常需要升級應用程式所使用的用戶端連結庫版本。新的穩定服務版本伴隨著客戶端連結庫的新點版本。針對新的重大變更版本，新的用戶端連結庫會發佈為點版本或主要版本。發行類型取決於服務變更的性質，以及連結庫能夠容納它的方式。只有 beta-version 用戶端連結庫會使用預覽服務版本。

SDK 用戶端連結庫支援手動覆寫服務版本。覆寫客戶端連結庫的預設服務版本是進階案例，並可能導致非預期的行為。如果您使用這項功能，請徹底測試您的應用程式，以確保它如預期般運作。

Azure 命令行工具

如同 SDK，Azure 命令行工具（包括 Azure CLI 和 Azure PowerShell）的設計目的是允許使用 Azure 管理服務，而不考慮版本。存取新的服務功能通常需要新版本的工具。每月發行新的回溯相容工具版本。具有重大變更的版本大約會每年發行兩次，或視需要修正重大安全性問題。

Azure 命令行工具偶爾可能會公開預覽功能。這些命令會標示為 Preview 標籤，並輸出警告，指出未來工具版本中的支援有限和潛在變更。

共用方式為