「Azure SDK documentation update: [AutoPR azure-mgmt-azurestackhci]-generated-from-SDK Generation – Python-5836689」は、Azure SDK全体の汎用的な告知ではなく、Python向け Azure Stack HCI 管理ライブラリ azure-mgmt-azurestackhci の自動生成SDK更新として確認すべき内容です。結論から言うと、Azure Stack HCIをPythonで作成・更新・運用しているチームは、azure-mgmt-azurestackhci==8.0.0、API Version 2026-02-01、TypeSpec由来の新しい生成レイアウト、モデルと操作メソッドの破壊的変更を確認する必要があります。特に、モデルを辞書化して使っているコード、publishers 操作グループを使っていたコード、expand を位置引数で渡していたコードは、早めにテスト環境で動作確認してください。
2026年5月3日にこの更新情報を見た場合でも、対応の中心は「5月3日に新機能が突然追加された」というより、2026年3月31日にマージされ、PyPIでは2026年4月1日に公開された stable 8.0.0 の内容を整理することです。GitHub PRでは、対象設定ファイルが specification/azurestackhci/resource-manager/Microsoft.AzureStackHCI/StackHCI/tspconfig.yaml、API Versionが 2026-02-01、SDK Release Typeが stable、SpecRepo側のCommitSHAが 2daa450f8eaef939165415ce90178334568eacfd とされています。PR自体は2026年3月31日にマージされ、関連ブランチの削除が2026年5月3日に記録されています。(GitHub)
このAzure SDK documentation updateの位置づけ
この更新は、Python用のAzure SDK管理ライブラリのうち、Azure Stack HCIを扱う azure-mgmt-azurestackhci に関するものです。Azure SDK for Pythonの管理ライブラリは、azure-mgmt- で始まるパッケージとして提供され、Azureリソースの作成、構成、管理に使われます。(Microsoft Learn)
今回の対象は、次のように整理できます。
| 確認項目 | 内容 | 実務上の見方 |
|---|---|---|
| 対象パッケージ | azure-mgmt-azurestackhci | Azure Stack HCIをPythonで管理するコードが対象 |
| リリース種別 | stable | 本番利用候補として扱う。ただし破壊的変更の確認は必須 |
| 公開バージョン | 8.0.0 | PyPI上では2026年4月1日公開 |
| API Version | 2026-02-01 | 既存コードが古いAPI前提ならレスポンス構造の差分に注意 |
| 生成方式 | TypeSpec / Python Code Generator由来 | AutoRest時代のレイアウトやモデル挙動と異なる可能性がある |
| 主な影響 | クライアント初期化、モデル、操作メソッド、enum、operation group | 単純な pip install -U だけで本番反映しない |
PyPIでは azure-mgmt-azurestackhci 8.0.0 が2026年4月1日にリリースされ、Python 3.9以上が必要とされています。また、Development StatusはProduction/Stableです。(PyPI)
対応すべき人と、様子見でよい人
この更新で最も注意すべきなのは、Azure Stack HCIの管理処理をPythonスクリプトや自動化ジョブに組み込んでいるチームです。単にAzure PortalでAzure Stack HCIを管理しているだけなら、Python SDKの破壊的変更が直接影響する可能性は高くありません。
| 対象者 | 対応優先度 | 理由 |
|---|---|---|
azure-mgmt-azurestackhci を使った運用スクリプトを持つチーム | 高 | モデル構造・操作メソッド・operation groupの変更で実行時エラーが起きる可能性がある |
| Azure Stack HCIの作成、拡張、更新、リモートサポート、Arc設定をPythonで自動化しているチーム | 高 | 新しいプロパティや操作が追加される一方、既存コードの引数指定が壊れる可能性がある |
SDKの戻り値を .as_dict() や .serialize() で加工しているチーム | 高 | Hybrid Model移行により辞書アクセスやキー形式の扱いが変わる |
| ソブリンクラウドや独自エンドポイントを使うチーム | 中〜高 | cloud_setting 対応により設定方法を見直せる |
| Azure Stack HCIを使っているがPython SDKを使っていない管理者 | 低 | 直接影響は小さい。ただし今後自動化を始めるなら新バージョン前提で設計する |
| .NET、Java、JavaScript、GoのSDK利用者 | 中 | 今回のPRはPython対象だが、同じAPI Version由来の変更が各言語SDKにも波及する可能性がある |
判断に迷う場合は、まずリポジトリ内で azure.mgmt.azurestackhci を検索してください。該当があるなら、SDK更新の影響確認対象です。
grep -R "azure.mgmt.azurestackhci" .
grep -R "AzureStackHCIClient" .Windows PowerShellなら次のように確認できます。
Select-String -Path .\* -Pattern "azure.mgmt.azurestackhci","AzureStackHCIClient" -Recurseまず確認すべき主な変更点
azure-mgmt-azurestackhci 8.0.0 では、クライアント、モデル、operation group、メソッドに複数の追加があります。PyPIのリリース履歴では、AzureStackHCIClient に cloud_setting パラメーター、send_request メソッド、edge_device_jobs と validated_solution_recipes のoperation groupが追加されたことが示されています。(PyPI)
cloud_setting が追加された
cloud_setting は、Azure Public Cloud以外のクラウドやARMエンドポイント解決を意識する環境で重要です。今回のクライアント実装では、cloud_setting または現在のAzure cloud設定からARM endpointとcredential scopesを解決する流れになっています。(GitHub)
ソブリンクラウド対応では、Microsoftのドキュメントでも cloud_setting 機能はAzure SDK管理ライブラリに順次展開されており、対応有無はクライアントコンストラクターの cloud_setting パラメーターで確認すると説明されています。(Microsoft Learn)
通常のAzure Public Cloudだけを使っている場合は、無理に指定する必要はありません。一方、Azure China CloudやAzure US Governmentなどを扱う場合は、認証のauthority、ARM endpoint、credential scopesの整合性を確認してください。
import os
from azure.identity import DefaultAzureCredential
from azure.core import AzureClouds
from azure.mgmt.azurestackhci import AzureStackHCIClient
subscription_id = os.environ["AZURE_SUBSCRIPTION_ID"]
client = AzureStackHCIClient(
credential=DefaultAzureCredential(),
subscription_id=subscription_id,
cloud_setting=AzureClouds.AZURE_PUBLIC_CLOUD,
)ソブリンクラウドでは、DefaultAzureCredential 側のauthority設定も合わせて確認します。cloud_setting だけを追加しても、認証先とリソースマネージャーのエンドポイントがずれていると認証やAPI呼び出しで失敗します。
send_request が追加された
send_request は、SDKクライアントのパイプラインを通して任意のHTTPリクエストを送れるメソッドです。プレビュー的なAPI検証や、SDKでまだ薄くラップされていない呼び出しを試す場面で便利です。
ただし、実装コメントでは send_request はレスポンスのエラーハンドリングを行わないとされています。つまり、HTTP 4xx/5xxをアプリ側で確認しないと、失敗を正常処理のように扱ってしまう危険があります。(GitHub)
from azure.core.rest import HttpRequest
request = HttpRequest(
"GET",
"{endpoint}/subscriptions/{subscription_id}/providers/Microsoft.AzureStackHCI/operations?api-version=2026-02-01",
)
response = client.send_request(request)
if response.status_code >= 400:
raise RuntimeError(f"Azure Stack HCI API failed: {response.status_code} {response.text()}")本番運用では、通常のoperation groupで提供されているメソッドを優先し、send_request は例外的に使うのが安全です。
新しいoperation groupとモデルが追加された
8.0.0では、edge_device_jobs、validated_solution_recipes、EdgeDeviceJobsOperations、ValidatedSolutionRecipesOperations などが追加されています。また、ArcSettingsOperations.begin_reconcile や ClustersOperations.begin_update_secrets_locations といったメソッドも追加されています。(PyPI)
実務上は、次のような場面で使い道があります。
| 追加要素 | 想定される活用シーン |
|---|---|
edge_device_jobs | Edge Deviceに対するログ収集やリモートサポート系ジョブの管理 |
validated_solution_recipes | 検証済み構成やソリューションレシピ情報の参照 |
begin_reconcile | Arc設定の再同期・整合性回復を自動化する処理 |
begin_update_secrets_locations | シークレット保存先の変更や運用設定更新 |
新機能をすぐ使わない場合でも、既存コードの戻り値に新しいプロパティが含まれる可能性があります。JSON比較テストやスナップショットテストを使っている場合は、レスポンス差分でテストが失敗することがあります。
破壊的変更で壊れやすいポイント
この更新はstableですが、「stableだから既存コードが必ずそのまま動く」という意味ではありません。PyPIのリリース履歴では、8.0.0にBreaking Changesが明記されています。特に、新しいHybrid Model、操作メソッドの引数変更、削除またはリネームされた要素に注意が必要です。(PyPI)
Hybrid Modelによりモデルの扱いが変わる
新しいHybrid Modelは、モデルでありながら辞書のようにも扱える構造です。Microsoftの移行ガイドでは、as_dict() の引数変更、辞書出力のキー形式変更、複数階層のflattened property削除、additional_properties の扱い変更、serialize() / deserialize() の削除などが破壊的変更として整理されています。(aka.ms)
壊れやすいコード例は次のようなものです。
# 旧コードで壊れやすい例
data = cluster.as_dict(keep_readonly=True)
print(data["provisioning_state"])
payload = model.serialize()
model2 = SomeModel.deserialize(payload)
custom = SomeModel(additional_properties={"x": "y"})見直し後は、REST APIの構造に近い camelCase キーやネスト構造を前提にします。
# 新しい設計に合わせた考え方
data = cluster.as_dict(exclude_readonly=False)
# 必要に応じてREST APIに近いキーを確認
print(data.get("properties", {}).get("provisioningState"))
# 追加プロパティは辞書のように扱う
model = SomeModel()
model["customKey"] = "customValue"特に注意したいのは、テストコードです。本体コードは属性アクセスで動いていても、テスト側で as_dict() の戻り値を厳密比較していると、snake_case から camelCase への変化で落ちることがあります。
操作メソッドの一部引数がkeyword-onlyになる
操作メソッドの移行ガイドでは、クエリパラメーターやヘッダーパラメーターが位置引数からキーワード専用引数に変わるケースが示されています。位置引数で渡していたコードは TypeError になる可能性があります。(aka.ms)
今回のリリース履歴でも、OffersOperations.get、OffersOperations.list_by_cluster、OffersOperations.list_by_publisher、SkusOperations.get、SkusOperations.list_by_offer の expand パラメーターが positional_or_keyword から keyword_only に変わったとされています。(PyPI)
# 旧コード: expandを位置引数で渡していると壊れやすい
sku = client.skus.get(resource_group_name, cluster_name, publisher_name, offer_name, sku_name, "SomeExpand")# 新コード: expandはキーワード引数で渡す
sku = client.skus.get(
resource_group_name,
cluster_name,
publisher_name,
offer_name,
sku_name,
expand="SomeExpand",
)検索するときは、expand= なしで offers や skus を呼んでいる箇所を重点的に探します。
grep -R "offers\..*(.*expand" .
grep -R "skus\..*(.*expand" .単純なgrepで拾いにくい場合は、テストで全API呼び出しを一度走らせる方が確実です。
publishers 関連の削除・リネームに注意する
8.0.0のBreaking Changesでは、AzureStackHCIClient.publishers、Publisher、PublishersOperations が削除またはリネームされた項目として挙げられています。(PyPI)
次のようなコードがある場合は、置き換え先を確認してください。
publishers = client.publishers.list_by_cluster(...)更新後は、該当機能が offers や別のoperation groupに整理されていないか、APIリファレンスとリリース履歴を確認します。単純に名前だけを変えるのではなく、取得したいデータの意味が変わっていないかを見てください。
モデルのプロパティが properties 配下へ移動している
Breaking Changesでは、ArcIdentityResponse、ClusterIdentityResponse、DeploymentSetting、ExtensionPatch、SecuritySetting などの一部インスタンス変数が properties 配下へ移動したことも示されています。(PyPI)
例えば、旧コードで次のように直接プロパティを参照していた場合は注意が必要です。
# 旧コードの例
state = deployment_setting.provisioning_state新しいモデル構造では、次のようにネストされたプロパティ参照が必要になる可能性があります。
# 新しい構造を想定した例
state = deployment_setting.properties.provisioning_stateここは型ヒントだけで判断せず、実際にAPIから取得したレスポンスをログに出して確認するのがおすすめです。Azure Stack HCIのリソース状態は、環境やAPI Versionによって含まれるプロパティが変わることがあるためです。
移行前に実施したい確認手順
本番環境でいきなり pip install -U するのは避けてください。特に管理系SDKは、リソース作成・削除・更新の自動化に直結します。次の順序で確認すると、影響範囲を絞り込みやすくなります。
現在の利用バージョンを確認する
まず、現在使っているバージョンを確認します。
python -m pip show azure-mgmt-azurestackhciPython側から確認する場合は次のようにします。
python - <<'PY'
from azure.mgmt.azurestackhci._version import VERSION
print(VERSION)
PYCI/CDやAzure Functions、コンテナ、踏み台サーバーなど複数の実行環境がある場合は、ローカルPCだけでなく実行環境ごとに確認してください。requirements.txt では固定されていても、実行環境側で別バージョンが入っていることがあります。
テスト用仮想環境で8.0.0を固定して入れる
本番と分けた仮想環境で、対象バージョンを明示してインストールします。
python -m venv .venv-hci-8
source .venv-hci-8/bin/activate
python -m pip install --upgrade pip
python -m pip install "azure-mgmt-azurestackhci==8.0.0" azure-identityWindows PowerShellでは次のように実行します。
py -m venv .venv-hci-8
.\.venv-hci-8\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install "azure-mgmt-azurestackhci==8.0.0" azure-identityパッケージのREADMEでも、azure-mgmt-azurestackhci と azure-identity のインストール、DefaultAzureCredential を使った認証例が示されています。認証では AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET、AZURE_SUBSCRIPTION_ID などの環境変数が関係します。(PyPI)
破壊的変更に関係するコードを検索する
次の文字列が見つかったら、移行確認の優先度を上げてください。
grep -R "\.serialize()" .
grep -R "\.deserialize(" .
grep -R "additional_properties" .
grep -R "keep_readonly" .
grep -R "as_dict(" .
grep -R "client.publishers" .
grep -R "PublishersOperations" .
grep -R "if_match\|if_none_match" .特に as_dict() は便利なため、ログ出力、監査、JSON保存、テスト比較で使われがちです。アプリの主要処理だけでなく、周辺の監視・通知・レポート生成コードも確認してください。
API Versionをむやみに上書きしていないか確認する
8.0.0のクライアント設定では、既定のAPI Versionが 2026-02-01 になっています。また、既定値を上書きするとサポート外の挙動になる可能性がある旨がコード上の説明に含まれています。(GitHub)
次のようなコードがある場合は、なぜ指定しているのかを確認します。
client = AzureStackHCIClient(
credential=credential,
subscription_id=subscription_id,
api_version="古いバージョン",
)過去の不具合回避のためにAPI Versionを固定していた場合、8.0.0への更新で不要になることもあります。逆に、古いAPI前提のリソースやテストデータがある場合は、固定を外すことでレスポンス構造が変わる可能性があります。
読み取り系、更新系、削除系の順でテストする
Azure Stack HCI管理SDKのテストは、いきなり作成・削除操作を走らせない方が安全です。おすすめの順番は次の通りです。
| 順番 | テスト内容 | 確認ポイント |
| -: | —————- | ——————————————— |
| 1 | importとクライアント初期化 | Python 3.9以上、認証、subscription_id、cloud_setting |
| 2 | list / get系 | 戻り値のモデル構造、as_dict() のキー、null許容 |
| 3 | 既存リソースに影響しない検証系 | keyword-only引数、LROのpolling、例外処理 |
| 4 | 更新系 | properties 配下の構造、etagや条件付き更新 |
| 5 | 作成・削除系 | 本番と同じ権限、ロールバック手順、監査ログ |
更新系や削除系のテストでは、検証用リソースグループや検証用クラスタを使ってください。SDKの動作確認で本番クラスタの設定を変更しないよう、実行対象のsubscription、resource group、cluster nameを環境変数で分離しておくと安全です。
設定確認で見落としやすいポイント
Python 3.8以下の環境では使えない
azure-mgmt-azurestackhci 8.0.0 はPython 3.9以上が必要です。古い運用サーバーやコンテナイメージでPython 3.8以前を使っている場合、SDK更新前に実行環境の更新が必要です。(PyPI)
確認コマンドは次の通りです。
python --version古いPython環境を使い続ける必要がある場合は、SDKを8.0.0へ上げる前に、実行基盤の更新計画を立ててください。依存パッケージだけを無理に上げても、インストール時点で失敗する可能性があります。
認証情報と権限不足をSDK変更と混同しない
SDK更新後に失敗した場合、原因がSDKの破壊的変更とは限りません。DefaultAzureCredential は環境変数、Managed Identity、Azure CLIログインなど複数の認証経路を順番に試すため、ローカルでは動くのにCI/CDでは失敗することがあります。
最低限、次を確認してください。
| 確認項目 | 典型的な失敗 |
|---|---|
AZURE_TENANT_ID | 別テナントの資格情報で認証している |
AZURE_CLIENT_ID | サービスプリンシパルやManaged Identityが違う |
AZURE_CLIENT_SECRET | シークレット期限切れ |
AZURE_SUBSCRIPTION_ID | 想定外のサブスクリプションを見に行く |
| RBAC | 読み取りはできるが更新・削除が失敗する |
| cloud_setting / authority | ソブリンクラウドで認証先とARM endpointが一致しない |
自動生成コードの内部モジュールに依存しない
今回のPR概要では、古いAutoRest風のレイアウトから新しいcodegenレイアウトへ移行し、operations、models、enum、serialization utilitiesなどが更新されたと整理されています。(GitHub)
次のような内部モジュールへの直接依存は避けてください。
# 避けたい例
from azure.mgmt.azurestackhci.models._azure_stack_hci_client_enums import Status
from azure.mgmt.azurestackhci.operations._publishers_operations import PublishersOperations基本は公開されたパッケージルート、models、operations経由でインポートします。内部ファイル名は生成方式の変更で変わりやすく、SDK更新のたびに壊れるリスクがあります。
# 望ましい例
from azure.mgmt.azurestackhci import AzureStackHCIClient
from azure.mgmt.azurestackhci import models本番反映の判断基準
8.0.0へ移行するかどうかは、「新機能を使いたいか」だけでなく、「今後のAPI Versionと生成方式に追随できる状態にするか」で判断します。Azure Stack HCIの管理自動化を継続するなら、検証したうえでstableへ寄せる価値はあります。
本番反映前には、次の条件を満たしているか確認してください。
| 判断基準 | 合格ライン |
|---|---|
| バージョン固定 | requirements.txt やロックファイルで azure-mgmt-azurestackhci==8.0.0 を明示している |
| Python環境 | すべての実行環境がPython 3.9以上 |
| 認証 | ローカル、CI/CD、本番ジョブで同じ方式の認証確認が済んでいる |
| モデル移行 | .as_dict()、.serialize()、additional_properties、properties 配下移動を確認済み |
| 操作メソッド | expand などkeyword-only化した引数を修正済み |
| 削除要素 | publishers、Publisher、PublishersOperations 依存がない |
| ロールバック | 旧バージョンに戻す手順と依存関係の復元方法がある |
| 実行ログ | 失敗時にHTTP status、request id、対象resource idを追える |
本番反映後は、少なくとも初回実行時に対象リソース、操作名、HTTPステータス、Azure側のrequest idをログに残してください。管理SDKの更新では、コードが成功しても意図したリソースと違う対象に対して操作しているケースが最も危険です。
この記事のまとめと次にやること
今回のAzure SDK documentation updateは、Python向けAzure Stack HCI管理SDK azure-mgmt-azurestackhci のstable更新として見るべきものです。対応の軸は、8.0.0、API Version 2026-02-01、cloud_setting、send_request、新しいoperation group、Hybrid Model、keyword-only引数、削除・リネームされた publishers 関連の確認です。
次に取るべき行動はシンプルです。まず自分のコードに AzureStackHCIClient があるか検索し、ある場合はテスト用仮想環境で azure-mgmt-azurestackhci==8.0.0 を固定して実行してください。そのうえで、as_dict()、serialize()、additional_properties、client.publishers、expand の位置引数指定を重点的に直します。Azure Stack HCIの管理操作は本番影響が大きいため、読み取り系から順に検証し、更新・削除系は検証用リソースで確認してから本番へ反映するのが安全です。
コメント