Azure Key Vaultでは、バージョン管理された API が使用されます。 アプリケーション、スクリプト、またはインフラストラクチャ テンプレートで古い API バージョンが呼び出された場合、新しい機能を見逃したり、新しいバージョンで変更された動作を使用したり、推奨されなくなったバージョンに依存したりする可能性があります。 この記事では、使用する API バージョンを決定する方法と、現在サポートされているバージョンに移行する方法について説明します。
Important
2026-02-01前のすべてのKey Vaultコントロール プレーン API バージョンは、2027 年 2 月 27 日に廃止されます。 その日以降もキー コンテナーは引き続き存在しますが、管理できるのはコントロール プレーン API バージョン 2026-02-01 以降を使用する場合のみです。 この日付に例外や延長はありません。 この廃止は 、データ プレーン API (キー、シークレット、証明書の操作に使用される API) には影響しません。 詳細については、Key Vaultの既定のアクセス制御モデルとしてのAzure RBAC の計画に関するページを参照してください。
Azure Key Vaultには、それぞれ独自のバージョンを持つ 2 つの独立した API サーフェスがあります。
| API の公開範囲 | 管理対象 | バージョン スキーム | エンドポイントの例 |
|---|---|---|---|
| コントロールプレーン (管理) | キー コンテナー リソース自体: コンテナーの作成、更新、削除、および SKU、ネットワーク 規則、アクセス制御などのプロパティの構成。 | 日付ベース ({YYYY}-{MM}-{DD}) |
https://management.azure.com |
| データ プレーン | コンテナー内のオブジェクト: キー、シークレット、証明書、暗号化操作。 | 日付ベース ({YYYY}-{MM}-{DD}) |
https://<vault-name>.vault.azure.net |
2 つのサーフェスには、バージョン管理とライフサイクルのプラクティスが異なります。 1 つを更新しても、もう一方は更新されません。 ワークロードで両方を使用する場合は、両方を確認します。
この記事で前述したように、コントロール プレーン API のバージョンは廃止できます。
プレビュー データ プレーン API のバージョンは非推奨になる可能性があるため、そのライフサイクルを受け入れない限り、運用環境ではプレビューを使用しないでください。 サポートされているデータ プレーン API のバージョンについては、Azure Key Vault REST API リファレンスを参照してください。
この記事では、API バージョンの識別と更新に重点を置いています。 コントロール プレーン API バージョンを更新する場合、既存のキー コンテナーをアクセス ポリシーから Azure RBAC に移行する必要はありません。 アクセス制御を移行する場合は、「アクセス ポリシーから RBAC をAzureに移行する」を参照してください。 API バージョン 2026-02-01 以降の新しいキー コンテナーに対して導入されたAzure RBAC の既定の動作については、Key Vaultの既定のアクセス制御モデルとしてのAzure RBAC の計画に関するページを参照してください。
現在の API バージョンに移行する理由
- サポートされている機能を使用します。 新しい API バージョンでは、機能の追加、正しい動作、または新しいサービス機能のサポートを行うことができます。
- 運用ワークロードの安定性を維持します。 運用環境のワークロードには、現在の安定した API バージョンを使用します。 プレビュー API のバージョンは評価と早期テスト用であり、Azure サポート SLA はそれらをカバーしていない可能性があります。 プレビュー バージョンは非推奨になる可能性があります。
- ツールとライブラリの互換性を維持します。 Azure CLI、Azure PowerShell、SDK、テンプレート、ポータルでは、さまざまな API バージョンを使用できます。 1 つのクライアントのバージョンを更新しても、他のクライアントは更新されません。
現在のコントロール プレーンのバージョンについては、「 サポートされているコントロール プレーン API のバージョン」を参照してください。 サポートされているデータ プレーンのバージョンについては、Azure Key Vault REST API リファレンスを参照してください。
使用する API のバージョンを決定する
API バージョンは、Key Vaultの呼び出し方法に応じて異なる方法で指定します。 ワークロードで使用する各サーフェスを確認します。
コントロールプレーン（管理）
-
REST API: バージョンは、
?api-version=<control-plane-version>へのリクエストで指定するhttps://management.azure.comクエリ文字列パラメーターです。たとえばapi-versionです。 -
ARM、Bicep、Terraform テンプレート: バージョンは、各
Microsoft.KeyVault/vaultsリソースのapiVersionプロパティです。 Bicepでは、resource kv 'Microsoft.KeyVault/vaults@2026-02-01'など、リソースの種類の宣言の一部です。 -
コントロール プレーン管理 SDK: パッケージバージョンは SDK でサポートされている API バージョンを決定できますが、パッケージのバージョンだけでは、要求で使用される API バージョンが常に識別されるわけではありません。 パッケージのリリース ノートと API リファレンス (
Azure.ResourceManager.KeyVaultやazure-mgmt-keyvaultなど) を確認し、プロジェクトの依存関係マニフェストのパッケージ バージョンと比較します。 言語別の API 参照については、クライアント ライブラリAzure Key Vault参照してください。 -
Azure CLIとAzure PowerShell: Azure CLIまたは
Azモジュールのバージョンによって API のバージョンが決まります。 インストールされているバージョンを az version または Get-InstalledModule -Name Az で確認します。 - Azure ポータル: ポータルは、要求のコントロール プレーン API バージョンを選択します。 そのバージョンを直接設定することはできません。 ポータルではテンプレート、スクリプト、SDK とは異なる API バージョンを使用できます。そのため、ポータルの動作を使用して、自動化で使用されるバージョンを特定しないでください。
- Azure Cloud Shell: Cloud Shellは、現在のAzure CLIとAzure PowerShellバージョンを使用します。 Cloud Shellでスクリプトを実行する場合は、現在サポートされているコントロール プレーン API バージョンと互換性があることを確認します。
データ プレーン
-
REST API: バージョンは、vault エンドポイントへのリクエストで指定する
GET https://<vault-name>.vault.azure.net/secrets/<name>?api-version=<data-plane-version>クエリ文字列パラメーターです。たとえばapi-versionです。 -
データ プレーン SDK: パッケージ バージョンは、SDK でサポートされている API バージョンを決定できますが、パッケージのバージョンだけでは、要求で使用される API バージョンが常に識別されるわけではありません。 パッケージのリリース ノートと API リファレンス (
Azure.Security.KeyVault.Secrets、Azure.Security.KeyVault.Keys、Azure.Security.KeyVault.Certificatesなど) を確認し、プロジェクトの依存関係マニフェストのパッケージ バージョンと比較します。 言語別の API 参照については、クライアント ライブラリAzure Key Vault参照してください。
API のバージョンを更新する
コントロール プレーン API のバージョンを更新する
テンプレートと REST 呼び出しで API バージョンを更新します。
apiVersion(ARM、Bicep、Terraform) またはapi-versionクエリ文字列パラメーター (REST) を、すべてのMicrosoft.KeyVault/vaults定義と管理要求で現在サポートされているコントロール プレーン バージョンに設定します。コントロール プレーン管理 SDK を更新します。 選択したコントロール プレーン API バージョンをサポートするパッケージ バージョンについては、パッケージのリリース ノートと API リファレンスを確認してください。 現在の Key Vault コントロール プレーン バージョンをサポートする言語およびパッケージ バージョン別の API 参照については、クライアント ライブラリとコントロール プレーン SDK リリースAzure Key Vault参照してください。
Note
コントロール プレーン管理 SDK を更新しても、データ プレーン SDK は更新されません。 アプリケーションで両方の API サーフェスを使用している場合は、各 SDK を個別に更新します。
Azure CLIとAzure PowerShellを更新します。 新しいツール バージョンでは、新しい API バージョンが呼び出されます。
Azure CLI を最新バージョンに更新します。 詳細については、「
Azure CLI を参照してください。
- デプロイする前に動作の変更を確認します。 デプロイする前に、API バージョンの変更ログと仕様を読み取ってください。 API バージョン
2026-02-01以降では、新しいキー コンテナーに対してのみ既定のアクセス制御モデルが変更されます。 詳細については、Key Vaultの既定のアクセス制御モデルとしてのAzure RBAC の計画に関するページを参照してください。
データ プレーン API のバージョンを更新する
REST 呼び出しで API バージョンを更新します。
api-versionクエリ文字列パラメーターを、Azure Key Vault REST API リファレンスに記載されている現在サポートされているデータ プレーン バージョンに設定します。データ プレーン SDK を更新します。
Azure.Security.KeyVault.*(または言語に相当する) パッケージを現在の安定したバージョンにアップグレードします。 パッケージのリリース ノートと API リファレンスを確認して、パッケージでサポートされているデータ プレーン API のバージョンを確認します。 言語別の API 参照とパッケージ リンクについては、クライアント ライブラリAzure Key Vault参照してください。
安定したデータ プレーン API バージョンは、現在のコントロール プレーンの提供終了の影響を受けません。 プレビュー データ プレーン API を使用する場合は、サービスのお知らせとそのライフサイクルに関する API リファレンスを確認してください。
データ プレーン REST API の呼び出しの詳細については、「認証、要求、応答」および「Azure Key Vault REST API リファレンス」を参照してください。