Azure SDK documentation update: [AutoPR @azure-arm-azurestackhci]-generated-from-SDK Generation - JS-5978864 は、Azure SDK全体の一括変更ではなく、JavaScript/TypeScript向けの @azure/arm-azurestackhci、つまりAzure Stack HCIの管理用SDKに関する自動生成PRです。影響を受けるのは、Azure Stack HCIをこのSDKで操作しているアプリ、運用スクリプト、管理ツールで、特に3.x系から4.x系またはbeta版へ移行する場合は、型定義・戻り値・プロパティ階層の確認が必要です。PR上ではAPI Version 2026-03-01-preview、SDK Release Type beta、構成ファイル tspconfig.yaml を使った生成として記録されています。(GitHub)
結論から言うと、今すぐ全Azure SDK利用者が対応する必要はありません。ただし、@azure/arm-azurestackhci を使って ArcSetting、Cluster、Extension、一覧取得、長時間実行操作を扱っている場合は、ビルドが通っていても実行時の扱いが変わる可能性があります。まずは package.json ではなくロックファイルまで含めて、実際に入っている @azure/arm-azurestackhci のバージョンを確認してください。
Azure SDK documentation update: JS-5978864で何が更新されたのか
この更新は、PR名から分かるようにAzure SDKの自動生成パイプラインに関連するものです。対象は azure-sdk-for-js リポジトリ内の @azure/arm-azurestackhci で、Azure Stack HCIのResource Manager、つまり管理プレーン向けライブラリです。Azure SDK for JavaScriptの管理ライブラリは、Azureリソースのプロビジョニングや管理に使う @azure/arm- 系パッケージとして説明されています。(GitHub)
PRの初期コメントでは、生成元の構成として specification/azurestackhci/resource-manager/Microsoft.AzureStackHCI/StackHCI/tspconfig.yaml、API Version 2026-03-01-preview、SDK Release Type beta、SpecRepoのCommitSHAが示されています。つまり、単なるREADMEの文言修正ではなく、API仕様からSDKを再生成した結果を含む更新として見るべきです。(GitHub)
一方で、このPRは最終的に「Closed」となっており、コメントでは「modular SDK has already been released」としてクローズされたことが確認できます。また、2026年5月3日には自動生成ブランチの削除履歴が残っています。したがって、2026年5月3日の情報として参照する場合は、「この日に新しい安定版が出た」と短絡せず、PR履歴・ドキュメント更新・既存リリース状況を合わせて確認するのが安全です。(GitHub)
対応が必要な人・不要な人
@azure/arm-azurestackhci を使っていない場合、この更新による直接的なコード修正は基本的に不要です。Azure Storage、Azure OpenAI、Azure Functions、Azure Key Vaultなど別サービスのSDKだけを使っているプロジェクトには直接関係しません。
| 利用状況 | 影響度 | 確認すべきこと |
|---|---|---|
@azure/arm-azurestackhci を使っていない | 低 | 対応不要。Azure SDK全体の更新と誤解しない |
| パッケージは入っているが、コードで呼び出していない | 低〜中 | 不要な依存関係なら削除を検討 |
| Azure Stack HCIのCluster、ArcSetting、Extensionを取得・更新している | 高 | 型変更、戻り値、プロパティ階層を確認 |
3.1.0 以前から4.x系へ移行する | 高 | 破壊的変更を前提に検証環境で移行 |
| beta版を本番で使っている | 高 | 安定版へ寄せるか、beta継続理由を明文化 |
Azure SDK for JavaScriptのリリース一覧では、Azure Stack HCI向け @azure/arm-azurestackhci について、安定版 4.0.0 とbeta版 4.1.0-beta.1 が掲載されています。PR上の分析対象は 4.0.0-beta.4 ですが、実際に採用するバージョンはnpm、Azure SDK Releases、ロックファイルを照合して決める必要があります。(Azure)
重要な変更点は「型」「戻り値」「プロパティの場所」
PR内のBreaking Change Analysisでは、旧SDKが Swagger / AutoRest、API version 2024-04-01、package 3.1.0、新SDKが TypeSpec / @azure-tools/typespec-ts emitter、API version 2026-03-01-preview、package 4.0.0-beta.4 と整理されています。つまり、APIバージョンの更新だけでなく、SDK生成方式の移行も含まれています。(GitHub)
connectivityProperties が自由なオブジェクトから型付きモデルへ
ArcSetting.connectivityProperties と ArcSettingsPatch.connectivityProperties は、従来の Record<string, unknown> から ArcConnectivityProperties へ変更されたと説明されています。これにより、何でも入れられる自由なオブジェクトではなく、enabled や serviceConfigurations など、定義された構造を前提にした扱いになります。(GitHub)
実務上は、次のようなコードを確認してください。
// 旧SDKでありがちな扱い
const raw = arcSetting.connectivityProperties as Record<string, unknown>;
const enabled = raw["enabled"];
// 新SDKでは型付きモデルとして扱う
const enabled = arcSetting.connectivityProperties?.enabled;
const services = arcSetting.connectivityProperties?.serviceConfigurations;型付きになること自体は保守性の向上につながります。ただし、旧コードで任意キーを読み書きしていた場合、TypeScriptのコンパイルエラーや、想定外のプロパティが無視されるリスクがあります。
systemData 系のプロパティはトップレベルではなくネストを確認
Breaking Change Analysisでは、ArcSetting、Cluster、Extension から createdAt、createdBy、createdByType、lastModifiedAt、lastModifiedBy、lastModifiedByType といったトップレベルの重複プロパティがなくなり、Resource.systemData 側で参照する形に変わったと整理されています。(GitHub)
移行時は、以下のように参照先を変えます。
// 旧SDK
const createdAt = cluster.createdAt;
const createdBy = arcSetting.createdBy;
// 新SDK
const createdAt = cluster.systemData?.createdAt;
const createdBy = arcSetting.systemData?.createdBy;ここで失敗しやすいのは、画面表示や監査ログ出力のコードです。リソース作成者や更新日時はUIの端に表示されるだけの項目になりがちなので、主要なCRUD処理だけをテストしていると見落とします。管理画面、CSV出力、監査ログ、通知テンプレートまで検索してください。
Extension の一部プロパティが extensionParameters 配下へ移動
Extension では、publisher、settings、protectedSettings、autoUpgradeMinorVersion、forceUpdateTag、typeHandlerVersion などがトップレベルではなく extensionParameters 配下に移動したと説明されています。(GitHub)
// 旧SDK
const publisher = extension.publisher;
const settings = extension.settings;
const autoUpgrade = extension.autoUpgradeMinorVersion;
// 新SDK
const publisher = extension.extensionParameters?.publisher;
const settings = extension.extensionParameters?.settings;
const autoUpgrade = extension.extensionParameters?.autoUpgradeMinorVersion;この変更は、単純な型エラーだけでなく、undefined の扱いにも注意が必要です。たとえば、旧コードで extension.publisher! のように非nullアサーションを使っていた場合、新SDKでは extension.extensionParameters 自体が未定義になり得るため、画面表示やログ出力で空文字フォールバックを用意した方が安全です。
const publisher =
extension.extensionParameters?.publisher ?? "(publisher未設定)";一覧取得と長時間実行操作の戻り値も確認する
PRの分析では、ArcSettings.create、ArcSettings.get、ArcSettings.update、Extensions.beginUpdate、Extensions.beginUpdateAndWait、Operations.list などで操作シグネチャや戻り値パターンの変更が示されています。また、ArcSettingList、ClusterList、ExtensionList のようなリスト用インターフェースがエクスポートされず、一覧操作は PagedAsyncIterableIterator を返す方向に整理されたとされています。(GitHub)
一覧処理は、配列のように扱っていたコードを見直します。
// 新しいページング形式を前提にした例
for await (const cluster of client.clusters.listByResourceGroup(resourceGroupName)) {
console.log(cluster.name, cluster.systemData?.createdAt);
}長時間実行操作、いわゆるLROは、戻り値の型が変わるとテストコードも壊れやすい箇所です。response.body や独自のレスポンスラッパーを前提にしている場合は、最終的に返るモデル型を確認してください。
const poller = await client.extensions.beginUpdate(
resourceGroupName,
clusterName,
arcSettingName,
extensionName,
parameters
);
const result = await poller.pollUntilDone();
console.log(result.id);ドキュメント上の変更も確認する
このPRのFiles changedでは、CHANGELOG.md、README.md、pnpm-lock.yaml などが変更対象として表示されています。特に CHANGELOG.md は多数の追加・削除があり、READMEにもリンクや説明文の調整が入っています。(GitHub)
READMEの差分では、APIリファレンスのリンクが azure-node-preview を含む参照へ変わり、サンプルへのリンクもパッケージ配下のsamplesへ向けられています。開発チーム内で古いサンプルや外部メモを参照している場合は、公式README・API reference・サンプルのリンクを更新しておくと、移行時の混乱を減らせます。(GitHub)
Microsoft LearnのAzureStackHCI client library for JavaScriptページでは、このパッケージがNode.jsとブラウザの両方で動作する同型SDKであり、npm install @azure/arm-azurestackhci で導入できること、認証には @azure/identity の DefaultAzureCredential や InteractiveBrowserCredential を使う例が示されています。(Microsoft Learn)
移行前に必ず確認する設定
実際に入っているバージョンを確認する
まず、ソースコード上の package.json だけで判断しないでください。CIや本番ビルドでは、package-lock.json、pnpm-lock.yaml、yarn.lock に固定されたバージョンが使われていることがあります。
npm list @azure/arm-azurestackhcipnpmを使っている場合は次のように確認します。
pnpm list @azure/arm-azurestackhciバージョンを明示して検証したい場合は、専用ブランチで固定して試します。
npm install @azure/[email protected]preview機能を試す目的が明確な場合だけ、beta版を固定して検証します。
npm install @azure/[email protected]MicrosoftのJavaScript向けAzure SDKインストールガイドでは、バージョンを指定しないインストールは最新バージョンを取得し、特定バージョンを指定すると依存関係がそのバージョンに固定されると説明されています。また、preview packageは早期アクセス用で、一般リリースほど安定しない可能性があるとされています。(Microsoft Learn)
beta版を本番で使うか判断する
Azure SDK for JavaScriptのREADMEでは、本番準備が必要なコードではstableな非betaパッケージを使うよう注意されています。Azure SDKのリリースポリシーでも、beta版は前のbetaから破壊的変更が入り得ると説明されています。(GitHub)
判断基準はシンプルです。
| 判断項目 | stable版を選ぶべきケース | beta版を検討するケース |
|---|---|---|
| 本番運用 | 業務システム、監視、課金・運用に関わる処理 | 原則避ける |
| preview機能 | 不要 | API preview機能が必須 |
| 変更許容度 | 低い | 高い。破壊的変更を追える |
| テスト体制 | 限定的 | 型テスト・統合テスト・ロールバック手順がある |
「betaの方が新しいから良い」と考えて導入すると、次のbetaやstable化で再修正が必要になることがあります。preview APIが必要な理由が説明できないなら、まずstable版を検証する方が堅実です。
認証と権限を再確認する
@azure/arm-azurestackhci は管理プレーン向けライブラリなので、認証だけでなく権限も重要です。Microsoft LearnのREADMEでは、Azureサブスクリプションが前提であり、@azure/identity を使った認証例が示されています。また、サービスプリンシパルへ適切なロールを割り当てる必要があり、Owner のようなロールだけでは必要な権限を与えない場合があると説明されています。(Microsoft Learn)
移行検証では、以下をセットで確認してください。
| 確認項目 | 見る場所 | 失敗しやすいポイント |
|---|---|---|
| サブスクリプションID | 環境変数、設定ファイル、CI secret | 検証環境と本番環境の取り違え |
| 認証方式 | DefaultAzureCredential、サービスプリンシパル、Managed Identity | ローカルでは通るがCIで失敗する |
| ロール割り当て | Azure Portal、Azure CLI、IaC定義 | Owner相当だと思い込む |
| テナントID | Entra ID設定、CI secret | 複数テナント環境で誤設定する |
| ブラウザ利用 | バンドラー、認証フロー | Node.js前提のコードをそのまま流用する |
実務での移行手順
まずコード検索で影響箇所を洗い出す
型変更はコンパイルで見つかることが多いものの、表示ロジックや任意オブジェクト操作は見落とされがちです。移行前に、以下のような検索を行います。
grep -R "connectivityProperties" src
grep -R "createdAt\|createdBy\|lastModifiedAt\|lastModifiedBy" src
grep -R "publisher\|settings\|protectedSettings\|autoUpgradeMinorVersion" src
grep -R "ArcSettingList\|ClusterList\|ExtensionList" src
grep -R "beginUpdate\|begin.*AndWait\|Operations.list" srcWindows環境ならPowerShellで確認できます。
Select-String -Path .\src\**\*.ts -Pattern "connectivityProperties","createdAt","createdBy","publisher","ArcSettingList","ClusterList","ExtensionList"TypeScriptの型チェックを先に通す
移行では、いきなり統合テストを走らせるより、まず型チェックで差分を拾う方が効率的です。
npx tsc --noEmit型エラーが大量に出る場合は、Extension、systemData、一覧取得、LROの順に直すと進めやすくなります。理由は、これらが複数ファイルにまたがりやすく、後回しにすると同じ修正を何度も繰り返すことになるためです。
ログを有効にして実行時エラーを見る
Microsoft LearnのREADMEでは、HTTP要求と応答のログを確認するために AZURE_LOG_LEVEL を info に設定する方法や、@azure/logger の setLogLevel を使う方法が示されています。移行直後は、認証エラー、権限不足、APIバージョン由来のレスポンス差分を切り分けるためにログが役立ちます。(Microsoft Learn)
AZURE_LOG_LEVEL=info npm testただし、ログにはリソース名、サブスクリプション、リクエスト情報が含まれる可能性があります。CIログや障害調査ログに残す場合は、社内のログ管理ルールに従ってマスキングしてください。
PRレビューで指摘された注意点
このPRでは、管理SDKレビューにより3つの問題が指摘されています。内容は、package.json の autoPublish が true から false に変わったこと、AzureClouds enumが Known プレフィックスを欠き、メンバー名も UPPER_SNAKE_CASE になっていること、AzureSupportedClouds が閉じたtemplate literal typeになっていて拡張性を損ねることです。(GitHub)
これらは、アプリ開発者が直接直すものではありません。ただし、beta版の型名やenum名に強く依存したコードを書くと、後続リリースで修正が入ったときに再度壊れる可能性があります。
実務では、次の方針が安全です。
- enum名やbeta特有の型名を広範囲に直接参照しない
- SDK呼び出し部分を小さなラッパー関数に閉じ込める
- 画面・バッチ・CIがSDK型を直接持たないようにする
- beta版を使う場合は、破壊的変更を追う担当と手順を決める
たとえば、SDKの戻り値をそのまま画面コンポーネントへ渡すのではなく、アプリ内の安定した型へ変換してから使うと、SDK更新時の修正範囲を狭められます。
type ClusterSummary = {
id?: string;
name?: string;
createdAt?: Date;
};
function toClusterSummary(cluster: Cluster): ClusterSummary {
return {
id: cluster.id,
name: cluster.name,
createdAt: cluster.systemData?.createdAt,
};
}よくある失敗と回避策
「ドキュメント更新だからコードに影響しない」と判断する
今回のAzure SDK documentation updateは、READMEだけでなくCHANGELOGや生成されたSDK表面の変更を含むPRです。Files changedでは大きな差分が表示されており、CHANGELOGにも多数の変更が含まれています。(GitHub)
ドキュメント更新という名前だけでスルーせず、利用中パッケージと一致するかを確認してください。
package.json だけ見て移行済みと判断する
package.json に @azure/arm-azurestackhci が書かれていても、実際のインストールバージョンはロックファイルで決まることがあります。特にCIやコンテナビルドでは、ローカルと違うバージョンが入ると、型エラーや実行時エラーの再現が難しくなります。
移行作業では、以下の3点を同じブランチで確認します。
npm list @azure/arm-azurestackhci
npm list @azure/identity
npx tsc --noEmitsystemData の移動をUIだけで見落とす
createdAt や lastModifiedBy は、CRUD処理の中心ではないため、テスト対象から漏れやすい項目です。運用画面、監査ログ、CSVエクスポート、通知メールで使っていないか確認してください。
beta版の型をアプリ全体へ広げる
beta版を使う場合、SDK型をそのままアプリ全体の型として広げると、次の更新で修正範囲が大きくなります。SDK呼び出し層でアプリ独自の型に変換し、画面や業務ロジックはその型だけを見る設計にすると、移行負荷を抑えられます。
確認チェックリスト
移行や設定確認では、次の順番で進めると手戻りを減らせます。
| 順番 | 作業 | 完了条件 |
| -: | ————– | —————————————————————– |
| 1 | 利用有無を確認 | @azure/arm-azurestackhci の実利用箇所が分かっている |
| 2 | 実バージョンを確認 | npm/pnpm/yarnのlist結果とロックファイルが一致している |
| 3 | stable/betaを選択 | 本番は原則stable、preview必須時のみbetaと判断できている |
| 4 | 型変更箇所を検索 | systemData、extensionParameters、connectivityProperties を確認済み |
| 5 | TypeScriptを通す | tsc --noEmit が通る |
| 6 | 統合テストを実施 | 認証、一覧取得、更新、LRO完了まで検証済み |
| 7 | ログと権限を確認 | CI・本番相当の認証で動作確認済み |
| 8 | ロールバックを準備 | 旧バージョンへ戻す手順と影響範囲が明確 |
次に取るべき行動
まず、リポジトリで @azure/arm-azurestackhci の利用有無を確認してください。使っていないなら、このAzure SDK documentation updateは情報として把握するだけで十分です。使っている場合は、npm list とロックファイルで実バージョンを確認し、3.x系から4.x系への移行に該当するかを判断します。
移行対象なら、最初に systemData、extensionParameters、connectivityProperties、一覧取得、LROの5点を検索してください。これらは今回の変更で実害が出やすい場所です。最後に、stable版で足りるか、preview APIのためにbeta版が必要かを決めます。本番運用では、理由なくbeta版へ寄せないことが最も重要です。
コメント