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 値が自動的に含まれます。 その他の考慮事項については、この記事で後述する「 Client SDK とサービス バージョン 」セクションを参照してください。
ほとんどのシナリオでは、サービス クライアントは、必要なすべての機能にアクセスするために、1 つのバージョンのサービスとのみ対話する必要があります。
安定したサービス バージョンは、一般に、新しいバージョンが利用可能になったとしても、長年にわたって利用可能であり、サポートされています。 ほとんどの場合、既存のコード内で新しいサービス バージョンを採用する必要があるのは、新機能を利用することだけです。
安定したバージョン
発行されるほとんどのサービス バージョンは、 テーブル バージョンです。 安定バージョンは下位互換性があります。つまり、1 つのバージョンのサービスに依存するコードを記述すると、正確性や既存の機能を維持するためにコードを変更しなくても、新しい安定したバージョンを採用できます。
破壊的変更バージョン
の変更バージョンサービスの下位互換性はありません。 既存のクライアント コードで破壊的変更バージョンを採用するには、以前のバージョンをターゲットにしたときとまったく同じようにクライアントが動作するようにコードを変更する必要がある場合があります。
破壊的変更バージョンはまれであり、ドキュメントを通じて発表され、通常はプレビュー バージョンの公開が先行します。 破壊的変更バージョンを公開すると、既存の安定バージョンが最終的に廃止される可能性があります。これは、破壊的変更バージョンのリリース後、少なくとも 3 年間は利用可能なままになります。 セキュリティまたはコンプライアンスの問題によって公開された重大な変更の場合、既存の安定したサービス バージョンは、問題の重大度に応じて 1 年間以下使用できる場合があります。
AI の急速なイノベーションと開発により、AI 主導のサービスの可用性が 1 年間以上低下する可能性があります。 各サービスは、破壊的変更ポリシーを発行します。
Microsoft 以外のコンポーネントに依存するすべての Azure サービスは、コンポーネントのポリシーと一致するようにサポート ポリシーを縮小できます。 このための重大な変更は、コンポーネントがサポートされなくなった日付を示すコンポーネント ベンダーのポリシーにリンクされます。
プレビュー バージョン
Microsoft は、提案された変更と新機能に関するフィードバックを収集するために、サービスの preview バージョン を公開することがあります。 プレビュー サービスのバージョンは、api-version内のサフィックス -preview (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 ラベルでマークされ、サポートが制限され、今後のツール バージョンでの潜在的な変更を示す警告が出力されます。