Azure サービス、SDK、CLI ツールのバージョン管理ポリシー
ほとんどの Azure サービスでは、REST API を使用してリソースをプログラムで制御および管理できます。 サービスは、新しい機能を追加したり動作を変更したりするさまざまなコントラクトを使用して、公開された新しいバージョンの API を通じて進化します。
この記事では、Azure サービス、SDK、CLI チームが Azure REST API のバージョン管理に使用するポリシーについて説明します。 Azure チームは、このポリシーに準拠するためにあらゆる努力をしていますが、逸脱が発生することがあります。
サービスのバージョン管理
API の発行された各バージョンは、日付値によって形式api-versionでYYYY-MM-DD識別されます。 新しいバージョンには、後の日付があります。
すべての API 操作では、クライアントが URL のクエリ文字列パラメーターを使用してサービスの api-version 有効な API バージョンを指定する必要があります。 (例: https://management.azure.com/subscriptions?api-version=2020-01-01)。 クライアント SDK とツールには、値が自動的に api-version 含まれます。 その他の考慮事項については、この記事で後述する 「クライアント SDK とサービスの バージョン」セクションを参照してください。
通常、公開されたサービス バージョンはメイン新しいバージョンが利用可能になったとしても、長年にわたって利用可能であり、サポートされています。 ほとんどの場合、既存のコード内で新しいサービス バージョンを採用する必要があるのは、新機能を利用することだけです。
安定したバージョン
発行されるほとんどのサービス バージョンは、 安定したバージョンです。 安定バージョンは下位互換性があります。つまり、1 つのバージョンのサービスに依存するコードを記述すると、コードの変更を必要とせずに、新しい安定したバージョンを採用メイン、既存の機能を維持できます。
破壊的変更バージョン
サービスの 破壊的変更バージョン には下位互換性がありません。 既存のクライアント コードで破壊的変更バージョンを採用するには、以前のバージョンをターゲットにしたときとまったく同じようにクライアントが動作するようにコードを変更する必要がある場合があります。
破壊的変更バージョンはまれであり、ドキュメントを通じて発表され、通常はプレビュー バージョンの公開が先行します。 破壊的変更バージョンを公開すると、既存の安定したバージョンが最終的に廃止される可能性があります。これはメイン破壊的変更バージョンのリリース後、少なくとも 3 年間利用可能になります。 セキュリティまたはコンプライアンスの問題によって公開された重大な変更については、既存の安定したサービス バージョンがメイン問題の重大度に応じて 1 年間以下使用できる場合があります。
AI の急速なイノベーションと開発により、AI 主導のサービスの可用性が 1 年間以上低下する可能性があります。 各サービスは、破壊的変更ポリシーを発行します。
Microsoft 以外のコンポーネントに依存するすべての Azure サービスは、コンポーネントのポリシーと一致するようにサポート ポリシーを縮小できます。 このための重大な変更は、コンポーネントがサポートされなくなった日付を示すコンポーネント ベンダーのポリシーにリンクされます。
プレビュー バージョン
Microsoft は、提案された変更や新機能に関するフィードバックを収集するために、サービスのプレビュー バージョンを公開することがあります。 プレビュー サービスのバージョンは、サフィックス -preview api-version で識別されます (例: 2022-07-07-preview.
以前の安定バージョンからの破壊的変更を明示的に導入することを意図していない限り、新しいプレビュー バージョンには、最新の安定バージョンのすべての機能が含まれており、新しいプレビュー機能が追加されます。 ただし、プレビュー バージョン間では、新しく追加されたプレビュー機能のいずれかがサービスによって中断される可能性があります。
プレビューは、長期的な使用を目的としたものではありません。 サービスの新しい安定バージョンまたはプレビュー バージョンが利用可能になると、既存のプレビュー バージョンは、新しいバージョンの可用性から 90 日以内に使用できなくなる可能性があります。 プレビュー バージョンは、新しいサービス機能に対して積極的に開発していて、リリース後すぐに新しいプレビュー以外のバージョンを採用する準備ができている場合にのみ使用してください。 プレビュー バージョンの一部の機能が新しい安定バージョンでリリースされた場合、再メインプレビュー段階の機能は通常、新しいプレビュー バージョンで公開されます。
クライアント SDK とサービス のバージョン
Azure SDK は 、 コードを記述する際の懸念事項としてサービスのバージョン管理を排除することを目的とします。 各 SDK は、サービスごとに 1 つずつクライアント ライブラリで構成され、各クライアント ライブラリ バージョンは、依存しているサービスの 1 つのバージョンを対象とします。
SDK を使用して Azure サービスにアクセスする場合、新しいバージョンと機能を利用するには、通常、アプリケーションで使用されるクライアント ライブラリのバージョンをアップグレードする必要があります。 新しい安定バージョンのサービスには、クライアント ライブラリの新しいポイント リリースが伴います。 新しい破壊的変更バージョンの場合、新しいクライアント ライブラリは、ポイント リリース バージョンまたはメジャー リリース バージョンとして発行されます。 リリースの種類は、サービスの変更の性質と、ライブラリがそれに対応する方法によって異なります。 プレビュー サービス バージョンを使用するのは、ベータバージョンのクライアント ライブラリのみです。
SDK クライアント ライブラリでは、サービス バージョンの手動オーバーライドがサポートされます。 クライアント ライブラリの既定のサービス バージョンをオーバーライドすることは高度なシナリオであり、予期しない動作につながる可能性があります。 この機能を利用する場合は、アプリケーションを十分にテストして、必要に応じて動作することを確認します。
Azure コマンド ライン ツール
SDK と同様に、Azure コマンド ライン ツール (Azure CLI と Azure PowerShell を含む) は、バージョンに関係なく Azure 管理サービスを使用できるように設計されています。 新しいサービス機能にアクセスするには、多くの場合、新しいバージョンのツールが必要です。 下位互換性のある新しいツール バージョンは、毎月リリースされます。 重大な変更が加わるバージョンは、年に約 2 回、または重要なセキュリティの問題を修正するために必要に応じてリリースされます。
Azure コマンド ライン ツールでは、プレビュー機能が公開されることがあります。 これらのコマンドはラベルで Preview マークされ、サポートが制限され、今後のツール バージョンでの潜在的な変更を示す警告が出力されます。