Azure SDK documentation updateとして、Azure Key VaultのPython向けSDKに関する更新が2026年5月5日に公開・更新されました。結論から言うと、今回の中心はKey Vault Keys SDKとAdministration SDKをAPI version 2025-07-01向けに再生成し、既定のAPIバージョンを更新する変更です。PR上では「AdministrationとKeys SDKに新機能は追加されない」と説明されていますが、Administration SDKでは継続トークンの互換性に注意が必要です。(GitHub)
特に確認すべきなのは、azure-keyvault-keysまたはazure-keyvault-administrationをPythonアプリで使っている開発者、Managed HSMのバックアップ・復元やRBAC操作を自動化している運用担当者、SDKの生成元であるTypeSpecやazure-rest-api-specsを追跡しているチームです。PyPI上では、確認時点でazure-keyvault-keysの最新は4.11.0、azure-keyvault-administrationの最新は4.6.0であり、PRに含まれる4.11.1/4.7.0相当の変更はリリース状況を確認してから適用する必要があります。(PyPI)
今回のAzure SDK documentation updateで何が変わるのか
今回の変更は、Azure SDK for PythonリポジトリのPR「[Key Vault] Regenerated Keys and Administration SDK with new folder structure and API version 2025-07-01」によるものです。対象は主に次の2パッケージです。
| 対象パッケージ | 主な用途 | 今回の変更で見るべき点 |
|---|---|---|
azure-keyvault-keys | Key Vaultのキー作成、取得、更新、削除、暗号化操作など | API version 2025-07-01対応、既定APIバージョンの更新、生成コード・モデル・サンプル・テストの更新 |
azure-keyvault-administration | Managed HSMのRBAC、バックアップ、復元、設定管理など | API version 2025-07-01対応、既定APIバージョンの更新、azure-core最小バージョン更新、継続トークン互換性の注意 |
Microsoft Learnでは、Azure Key Vault向けPython SDKの4.x系ライブラリとして、Administration、Certificates、Keys、Secretsが案内されています。今回のPRで直接対象になっているのは、KeysとAdministrationです。(Microsoft Learn)
重要なのは、「API versionが新しくなる＝アプリに新機能が増える」とは限らないことです。PRの説明では、Administration SDKとKeys SDKについて、この新しいAPIバージョンには新機能が含まれないとされています。つまり、多くの利用者にとっては「機能追加」よりも「既定APIバージョン変更」「生成コード更新」「依存関係やテスト環境の確認」が主な対応ポイントになります。(GitHub)
API version 2025-07-01が既定になる影響
今回の更新では、Keys SDKとAdministration SDKの両方で2025-07-01がKey Vault APIの既定バージョンとして扱われます。PRの変更ファイルでは、両パッケージのメタデータにapiVersion: 2025-07-01が追加され、クライアント基盤側でもDEFAULT_VERSION = ApiVersion.V2025_07_01となっています。(GitHub)
通常、SDK利用者は明示的にAPIバージョンを指定せず、次のようにクライアントを作成します。
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
credential = DefaultAzureCredential()
client = KeyClient(
vault_url="https://<your-vault-name>.vault.azure.net/",
credential=credential,
)このようなコードでは、SDK側の既定APIバージョンが変わると、送信されるリクエストのapi-versionも変わる可能性があります。今回の更新後は、明示的に別バージョンを指定していない限り、2025-07-01が使われる前提でテストすべきです。
ただし、すべてのアプリが急いでコードを書き換える必要があるわけではありません。確認すべきなのは、次のようなケースです。
| 利用状況 | 対応優先度 | 理由 |
|---|---|---|
KeyClientでキー作成、取得、更新、削除だけを行っている | 中 | 大きな機能差は想定しにくいが、APIバージョン変更後のレスポンスや権限エラーを確認したい |
CryptographyClientで署名、検証、ラップ、アンラップを本番利用している | 高 | 暗号化・署名処理は業務影響が大きいため、回帰テストが必須 |
| Managed HSMのバックアップ・復元をAdministration SDKで自動化している | 高 | 継続トークン互換性の注意があるため、アップグレードタイミングを誤ると再開処理に影響する可能性がある |
| SDK生成やTypeSpec参照パスをCIで追跡している | 高 | 新しいフォルダー構造により、参照先パスの変更が必要になる場合がある |
azure-keyvault-secretsやazure-keyvault-certificatesのみ利用している | 低〜中 | 今回のPython PRの直接対象ではない。ただしKey Vault全体のAPI更新を追っている場合は別途確認する |
新しいフォルダー構造とは何か
今回のPRでは「new folder structure」として、SDK生成元のTypeSpec参照先がKey Vaultのdata-plane配下に整理されています。具体的には、Keysはspecification/keyvault/data-plane/Keys、Administrationはspecification/keyvault/data-plane/Administrationを参照します。(GitHub)
これは、一般的なアプリ開発者がimport文を変更するような話ではありません。影響を受けやすいのは、次のようなチームです。
- Azure SDKの生成コードを社内で検証している
azure-rest-api-specsのTypeSpecパスをCI/CDで固定参照している- SDK更新時に
_generated配下の差分をレビューしている - APIViewや自動生成メタデータを使って変更検知している
たとえば、これまで古い仕様パスを前提にCIで差分確認していた場合、今回の構造変更後は「API仕様が消えた」と誤検知する可能性があります。CIで仕様ファイルを直接参照している場合は、PR内のtsp-location.yamlに合わせて参照先を見直してください。
Keys SDKで確認すべき変更点
azure-keyvault-keysでは、Changelog上で4.11.1 (Unreleased)としてAPI version 2025-07-01のサポート追加と、Key Vault API version 2025-07-01が既定になることが記載されています。パッケージ定義ではPython 3.9以降、azure-core>=1.37.0、cryptography>=44.0.2などの依存関係が示されています。(GitHub)
Keys SDKを使っている場合、まず次の操作をテストしてください。
| テスト対象 | 具体的な確認内容 |
|---|---|
| キー作成 | create_key、create_rsa_key、create_ec_keyが期待どおり動くか |
| キー取得 | get_keyで既存キーとバージョン指定キーを取得できるか |
| キー更新 | update_key_propertiesで有効・無効、タグ、属性変更が反映されるか |
| キー削除・復旧 | 論理削除、復旧、パージ保護の運用手順に問題がないか |
| 暗号化操作 | 署名、検証、暗号化、復号、ラップ、アンラップが業務データで成功するか |
| 非同期処理 | azure.keyvault.keys.aioを使っている場合、同期版とは別に確認する |
特にCryptographyClientを使って署名やキーラップを行っているシステムでは、単にSDKをインストールして起動確認するだけでは不十分です。実際のアルゴリズム、キー種別、Managed HSM利用有無を含めて、代表的な本番パターンをテストしてください。
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
credential = DefaultAzureCredential()
key_client = KeyClient(
vault_url="https://<your-vault-name>.vault.azure.net/",
credential=credential,
)
key = key_client.get_key("<key-name>")
print(key.name)
print(key.properties.version)このような基本操作に加えて、アプリが依存しているレスポンス項目を確認します。たとえば、キーのidやkid、バージョン、属性、タグを独自DBに保存している場合は、値の形式や欠損がないかをログで確認してください。
Administration SDKで最も注意すべき点
azure-keyvault-administrationでは、API version 2025-07-01対応に加えて、azure-coreの最小バージョンが1.38.0に更新されています。また、Changelogでは継続トークン形式の変更がBreaking Changesとして明記されています。(GitHub)
これは、Managed HSMのバックアップ・復元のような長時間操作を、途中で中断して後から再開する仕組みに影響します。
たとえば、次のような運用をしている場合は注意が必要です。
begin_backupやbegin_restoreのPollerから継続トークンを取得してDBに保存している- バックアップ・復元ジョブをキューやバッチ処理で再開している
- アプリ再起動後に保存済みトークンから処理状態を復元している
- SDKアップグレードとManaged HSMの復元処理が同じメンテナンス時間帯に重なる
この場合、SDK更新前に進行中のバックアップ・復元処理を完了させるのが安全です。保存済みの継続トークンを新バージョンでそのまま使える前提でアップグレードすると、再開処理が失敗する可能性があります。
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient
credential = DefaultAzureCredential()
client = KeyVaultBackupClient(
vault_url="https://<your-managed-hsm-name>.managedhsm.azure.net/",
credential=credential,
)Administration SDKは、通常のKey VaultではなくManaged HSM向けの管理操作を扱うライブラリです。PyPIの説明でも、AdministrationライブラリはManaged HSMでのみ動作し、Key Vaultを対象にした機能は失敗すると明記されています。(PyPI)
Managed HSMのRBACとバックアップ運用で確認すること
Administration SDKを使うチームは、単なるSDK更新ではなく「運用手順の更新」として扱うべきです。特にManaged HSMでは、ロール定義、ロール割り当て、バックアップ、復元、セキュリティドメイン関連の操作が運用に直結します。
Microsoft Learnの2025-07-01 REST APIドキュメントでは、Managed HSMのロール定義作成・更新APIがapi-version=2025-07-01で示されており、スコープについてはManaged HSMでは/のみがサポートされると説明されています。(Microsoft Learn)
確認すべき観点は次のとおりです。
| 観点 | 確認内容 | 失敗しやすいポイント |
|---|---|---|
| RBAC | カスタムロール定義、ロール割り当ての作成・取得・削除 | 権限不足をSDK不具合と誤認する |
| バックアップ | フルバックアップ、事前チェック、保存先認証 | SASトークンやManaged Identityの権限切れ |
| 復元 | フル復元、選択的復元、事前チェック | 旧SDKの継続トークンを新SDKで再利用する |
| 非同期処理 | azure.keyvault.administration.aio利用時の処理完了確認 | 同期版だけテストして本番の非同期処理を見落とす |
| 監査 | 操作ログ、失敗時のHTTPステータス、対象HSM名 | 403、404、409の原因切り分けが遅れる |
特にバックアップ・復元は、日常的に実行しないためテストが後回しになりがちです。しかし、障害時に初めて復元を試す運用ではリスクが高すぎます。SDK更新後は、少なくとも検証用Managed HSMでバックアップ開始、ステータス確認、復元前チェックまでを確認しておくべきです。
「新機能なし」でもテストが必要な理由
今回のPRでは、AdministrationとKeys SDKに新機能は含まれないと説明されています。それでもテストが必要なのは、SDK更新では次のような部分が変わるためです。(GitHub)
- 既定の
api-version - 自動生成されたクライアントやモデル
- サンプルコードやテストコード
- 依存パッケージの最小バージョン
- API仕様の参照パス
- 非同期処理や暗号ライブラリ周辺の互換性
実務では「メソッド名が変わっていないから安全」と判断すると失敗します。たとえば、レスポンスモデルの型ヒントが変わっただけでも、厳格な型チェック、独自のJSON変換、監査ログ出力、テストのスナップショット比較でエラーになることがあります。
特にPythonでは、CIでmypyやpyright、pylintを使っているプロジェクトほど、生成コードや型定義の更新による影響を受けやすくなります。PR内でもMyPy、PyLint、Snippets、テスト更新が含まれているため、SDK利用側でも型チェックとサンプル相当の動作確認を行うのが現実的です。(GitHub)
移行前に確認するチェックリスト
SDKを更新する前に、次の順番で確認すると失敗を減らせます。
| 手順 | 確認内容 | 判断基準 |
| -: | ———————————- | ———————————————————– |
| 1 | PRがマージ済みか、PyPIに新バージョンが公開済みか確認する | GitHub PRだけでなく、実際の配布パッケージを確認する |
| 2 | 利用中パッケージを棚卸しする | azure-keyvault-keys、azure-keyvault-administrationの有無を見る |
| 3 | 明示的なAPIバージョン指定があるか確認する | api_versionを指定している場合、既定変更の影響は限定的 |
| 4 | Administration SDKの継続トークン保存有無を確認する | DB、キュー、ジョブ管理テーブルに保存していないか |
| 5 | 依存関係を確認する | Python 3.9以降、azure-core、cryptographyなどの制約を満たすか |
| 6 | 検証環境で代表操作を実行する | キー操作、暗号化操作、Managed HSM管理操作が成功するか |
| 7 | 本番反映のタイミングを決める | 長時間バックアップ・復元処理の実行中を避ける |
依存関係は、アプリ本体だけでなく、Dockerイメージ、CIのPythonバージョン、ロックファイル、社内ミラーにあるパッケージにも影響します。requirements.txtやpoetry.lock、uv.lock、pip-toolsの制約ファイルを使っている場合は、SDKだけを上げても依存関係が解決できないことがあります。
すぐ使える確認コマンド
現在のインストール状況は、次のコマンドで確認できます。
python -m pip show azure-keyvault-keys
python -m pip show azure-keyvault-administration
python -m pip show azure-core
python -m pip show cryptography
python --version依存関係の矛盾を確認するには、次のコマンドも有効です。
python -m pip checkSDK更新を検証環境で試す場合は、まずロックファイルを更新し、アプリの通常テストに加えてKey Vault連携テストを実行します。
python -m pip install --upgrade azure-keyvault-keys azure-keyvault-administration
python -m pip check
pytestただし、PR段階の変更をそのまま本番導入するのは避けるべきです。PyPIの最新バージョン、GitHubのリリースノート、Azure SDKのリリースページを確認し、正式に公開されたパッケージとして取得できることを確認してから更新してください。
APIバージョンを一時的に固定したい場合
既定APIバージョンの変更後に問題が出た場合、原因切り分けとして一時的に旧APIバージョンを明示する方法があります。たとえば、既存環境で7.6を使い続けたい場合は、クライアント作成時にapi_versionを指定する構成を検討します。
from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
client = KeyClient(
vault_url="https://<your-vault-name>.vault.azure.net/",
credential=DefaultAzureCredential(),
api_version="7.6",
)これは恒久対応ではなく、切り分けや段階移行のための手段と考えるべきです。新しいSDKで旧APIバージョンを使う場合でも、サポート対象のバージョンであること、アプリの操作に必要な機能が含まれていることを確認してください。
よくある誤解と注意点
Key Vaultの設定変更が必ず必要になるわけではない
今回の更新はSDK側の再生成と既定APIバージョン更新が中心です。通常のKey VaultやManaged HSMのリソース設定を一律で変更する必要はありません。
ただし、実際のリクエストで使われるapi-versionが変わるため、ネットワーク制御、監査ログ、独自プロキシ、API Gateway、テストの期待値でapi-versionを見ている場合は影響があります。
SecretsやCertificatesのPython SDK更新と混同しない
PR名にKey Vaultが含まれているため、SecretsやCertificatesも同時に変更されたように見えますが、今回のPython SDK PRで直接再生成されているのはKeysとAdministrationです。SecretsやCertificatesを使っている場合は、それぞれのChangelogやリリースノートを別途確認してください。
Administration SDKは通常のKey Vault向けではない
Administration SDKはManaged HSMのRBACやバックアップ・復元を扱うライブラリです。通常のKey Vaultでシークレットや証明書を扱う場合は、azure-keyvault-secretsやazure-keyvault-certificatesを使います。Administration SDKを通常のKey Vault管理用と誤解すると、対象リソース違いでエラーになります。(PyPI)
継続トークンを保存していないなら影響は限定的
Administration SDKの継続トークン互換性は重要ですが、すべての利用者に影響するわけではありません。バックアップや復元を開始して、その場で完了まで待機するだけの処理であれば、保存済みトークンの再利用リスクは限定的です。
一方で、ジョブを分割して後から再開する設計では影響が大きくなります。該当する場合は、SDK更新前に進行中ジョブを完了させ、更新後に新しいトークン形式で運用を再開するのが安全です。
実務でのおすすめ対応
今回のAzure SDK documentation updateは、慌てて本番コードを書き換えるタイプの更新ではありません。まずは、利用中のパッケージと運用パターンを確認し、影響の大きい箇所から検証するのが現実的です。
優先順位は次のとおりです。
azure-keyvault-administrationでManaged HSMのバックアップ・復元を自動化している環境azure-keyvault-keysで本番の暗号化・署名・キーラップを行っている環境- SDK生成元のTypeSpecパスやAPI仕様をCIで参照している環境
- 通常のキー作成・取得・更新のみを行うアプリ
まず、現在のPyPI公開バージョンとPRのマージ状況を確認します。そのうえで、検証環境にSDKを導入し、キー操作、暗号化操作、Managed HSM管理操作を実行してください。Administration SDKで継続トークンを保存している場合は、アップグレード前に進行中の長時間操作を完了させるか、旧トークンを新SDKに持ち越さない運用に変更することが重要です。
今回の変更を安全に取り込むポイントは、「API version 2025-07-01対応そのもの」よりも、「既定APIバージョン変更後に自社の運用コードが同じように動くか」を確認することです。SDKの更新は小さく見えても、Key VaultやManaged HSMは認証、暗号化、バックアップに関わる重要領域です。パッケージ更新、依存関係、継続トークン、代表操作のテストをセットで確認してから本番反映しましょう。
コメント