Azure SDK documentation update: [AutoPR @azure-arm-datafactory]-generated-from-SDK Generation - JS-6014612 は、単なるドキュメント差し替えとして流し読みしない方がよい更新です。結論から言うと、Azure Data Factory 向け JavaScript/TypeScript SDKである @azure/arm-datafactory を使っている開発者は、APIバージョンの変更ではなく、SDK生成方式の変更に伴う型定義・メソッド名・戻り値の変化を確認する必要があります。
特に、begin* / begin*AndWait 系メソッド、ActivityUnion や DatasetUnion などのUnion型、KnownXxx 系の列挙型、ページング処理、Node.js実行環境を使っているプロジェクトは影響を受けやすい領域です。一方で、Azure Data FactoryのREST APIバージョンは 2018-06-01 のままであり、PR内の分析でもAPIバージョンアップ起因の破壊的変更は0件とされています。つまり、サービスAPIそのものよりも、SDKの型・生成物・呼び出しコードの互換性確認が実務上の焦点です。(GitHub)
Azure SDK documentation updateで確認すべき結論
今回の更新は、Azure SDK for JavaScriptリポジトリ上の @azure/arm-datafactory に関する自動生成PRです。PR本文には、生成元として specification/datafactory/resource-manager/Microsoft.DataFactory/DataFactory/tspconfig.yaml、API Version 2018-06-01、SDK Release Type stable、SpecRepo側のCommitSHAが記載されています。(GitHub)
ただし、ここで重要なのは「stableと書かれているから、すぐにnpmの安定版として導入済み」と判断しないことです。PR自体は2026年4月28日にクローズされ、2026年5月3日に自動生成ブランチが削除された記録があります。公開済みパッケージとして利用するかどうかは、npm、Microsoft Learnのパッケージ一覧、プロジェクトのロックファイルを見て判断する必要があります。(GitHub)
Microsoft LearnのJavaScript向けAzure SDKパッケージ一覧では、Data Factoryの安定版として 19.0.0、プレビュー系として 20.0.0-beta.1 が掲載されています。したがって、実務では「PR内の生成候補」と「実際に導入されているnpmパッケージ」を分けて確認するのが安全です。(Microsoft Learn)
| 確認項目 | 内容 | 実務で見るべきポイント |
|---|---|---|
| 対象パッケージ | @azure/arm-datafactory | Azure Data FactoryをJS/TSから管理しているか |
| 対象領域 | Azure SDK for JavaScript / TypeScript | アプリ本体、管理ツール、IaC補助スクリプト、運用自動化 |
| API Version | 2018-06-01 | サービスAPIのバージョンアップではない |
| 生成方式 | Swagger / AutoRest から TypeSpec / emitter への移行として分析 | 型定義・メソッド・戻り値が変わりやすい |
| PR状態 | closed | そのままリリース済みと決めつけない |
| 優先確認 | begin*、Union型、列挙型、ページング、Node.js要件 | TypeScriptのビルドで検出しやすい |
影響を受ける可能性が高い人
今回のAzure SDK documentation updateで最も注意すべきなのは、Azure Data Factoryの管理操作をJavaScriptまたはTypeScriptで直接呼び出しているプロジェクトです。たとえば、Data Factory、Pipeline、Dataset、Linked Service、Trigger、Integration RuntimeをSDKから作成・更新・取得・開始・停止している場合は、型定義とメソッド呼び出しの確認が必要です。
| 利用状況 | 影響度 | 確認すべき理由 |
|---|---|---|
@azure/arm-datafactory をTypeScriptで利用している | 高 | 型定義変更によりコンパイルエラーが出る可能性がある |
beginStartAndWait など begin* 系を使っている | 高 | PR内分析で旧LROメソッドの削除が示されている |
ActivityUnion、DatasetUnion、LinkedServiceUnion を明示的に使っている | 高 | discriminator変更がUnion型や操作シグネチャに波及する |
SDKの戻り値から .value を直接読む一覧処理を書いている | 中〜高 | 一覧系が PagedAsyncIterableIterator<T> へ寄る可能性がある |
npmのバージョンを ^ で広く許可している | 中 | 将来の20系導入時に意図せず型変更を受ける可能性がある |
| Azure PortalやADF Studioだけを使っている | 低 | SDK呼び出しコードがなければ直接影響は小さい |
「Azure SDKの更新」と聞くと、Azure側のサービス仕様変更を想像しがちです。しかし今回の焦点は、Data Factoryサービスの挙動変更というより、SDKの生成物が変わることで、既存コードの型や呼び出し方が変わる可能性にあります。
何が変わったのか
APIバージョンは変わっていない
PR内のBreaking Change Analysisでは、旧SDKと新SDKのAPI Versionはいずれも 2018-06-01 であり、API Version Upgrade起因の破壊的変更は0件とされています。これは重要です。APIバージョンが変わっていないため、Azure Data Factory REST APIの新旧差分を最初に疑うより、SDK生成方式の差分を先に確認すべきです。(GitHub)
実務では、次のように切り分けます。
| 症状 | まず疑うべき原因 |
|---|---|
| TypeScriptで型エラーが出る | SDKの型定義変更 |
beginStartAndWait が存在しない | LROメソッドの変更 |
.value がない、または戻り値の扱いが違う | ページング戻り値の変更 |
| Azure側の実行結果が変わった | SDKではなくサービス・権限・入力値も含めて確認 |
| npm install後にCIだけ失敗する | Node.js、lockfile、依存解決、TypeScript設定 |
TypeSpec / emitter移行に伴う破壊的変更が中心
PR内の分析では、Swagger / AutoRestからTypeSpec / emitterへの移行により、合計180件の破壊的変更が発生したと整理されています。内訳には、discriminator typeの変更、Union型の変更、操作シグネチャの変更、begin* メソッドの削除、List/Collectionインターフェイスの削除、型エイリアスや列挙型の削除などが含まれます。(GitHub)
ここでいう「破壊的変更」は、必ずしもAzure Data Factoryの機能が壊れるという意味ではありません。多くは、TypeScriptコード上で次のような変更として現れます。
- 以前の型名をimportできない
- 戻り値の型が変わり、
.value前提の処理が通らない begin*AndWaitが見つからない- Union型の絞り込み条件が変わる
- enumの名前やメンバー名に依存したコードが崩れる
つまり、ランタイム障害よりも先に、TypeScriptのコンパイルエラーやテスト失敗として検出できる変更です。これは悪いことばかりではありません。移行前にCIで拾いやすいので、確認手順を決めておけば影響範囲を限定できます。
特に注意すべき変更点
begin* / begin*AndWait 系メソッドの削除
PR内の分析では、古い begin* / begin*AndWait 操作が削除され、新しいLROスタイルのメソッドに置き換わるとされています。例として、DataFlowDebugSessionの beginCreate / beginCreateAndWait は create()、IntegrationRuntimeObjectMetadataの beginRefresh / beginRefreshAndWait は refresh()、IntegrationRuntimesの beginStart / beginStop は start() / stop() に置き換わる形で示されています。(GitHub)
旧コードのイメージは次のようなものです。
await client.triggers.beginStartAndWait(
resourceGroupName,
factoryName,
triggerName
);移行時は、単純に begin を削るだけでなく、戻り値がPoller系か、即時完了系か、利用中の型定義で確認してください。LROとしてPollerを返す場合は、次のような考え方になります。
const poller = await client.triggers.start(
resourceGroupName,
factoryName,
triggerName
);
await poller.pollUntilDone();実際の引数や戻り値は、導入している @azure/arm-datafactory のバージョンに含まれる型定義で確認してください。ここで失敗しやすいのは、メソッド名だけを置換して、待機処理を落としてしまうケースです。TriggerやIntegration Runtimeの開始・停止は運用フローに直結するため、処理完了を待つ必要があるかを必ず見直しましょう。
一覧系の戻り値が直接ページングされる可能性
PR内の分析では、List/Collectionインターフェイスが削除され、操作が PagedAsyncIterableIterator<T> を直接返す方向の変更が示されています。(GitHub)
以前のSDKでは、次のようにレスポンスの value を読むコードを書いている場合があります。
const result = await client.datasets.listByFactory(
resourceGroupName,
factoryName
);
for (const dataset of result.value ?? []) {
console.log(dataset.name);
}ページングイテレーターを返す形では、次のように for await...of で処理する方が自然です。
const datasets = client.datasets.listByFactory(
resourceGroupName,
factoryName
);
for await (const dataset of datasets) {
console.log(dataset.name);
}この変更は、コード量を減らせる一方で、既存の .value 前提の処理を壊します。特に、Data Factory内のDatasets、Pipelines、LinkedServices、Triggersを一覧取得して棚卸しする運用スクリプトは、移行時に見落としやすい箇所です。
discriminator typeとUnion型の変更
PR内の分析では、Activity.type、Dataset.type、LinkedService.type、DataFlow.type、Trigger.type など、多くのdiscriminator typeが string または名前付き型へ変更されるとされています。これにより、ActivityUnion、DatasetUnion、LinkedServiceUnion などのUnion型や、操作シグネチャにも変更が波及します。(GitHub)
影響を受けやすいのは、次のようなコードです。
function handleActivity(activity: ActivityUnion) {
if (activity.type === "Copy") {
// Copy activityとして処理
}
}移行後は、型名やdiscriminatorの型が変わっている可能性があります。対策としては、ActivityUnion などの旧型を前提にした関数を洗い出し、SDKの新しい型定義に合わせてimportと型ガードを修正します。
実務では、次の検索が有効です。
grep -R "ActivityUnion\|DatasetUnion\|LinkedServiceUnion\|TriggerUnion" src
grep -R "\.type ===" src
grep -R "Known[A-Za-z].*" srcポイントは、型エラーを一括で潰そうとしないことです。まず「Data Factoryのどのリソースに関する型か」を分けると、修正の優先度が見えます。PipelinesやTriggersのように本番ジョブに直結する箇所を先に直しましょう。
列挙型と型エイリアスの削除・命名変更
PR内の分析では、24件の型エイリアス削除と23件の列挙型削除が示されています。たとえば、CopyBehaviorType、CompressionCodec、SqlWriteBehaviorEnum、KnownCompressionCodec、KnownSqlWriteBehaviorEnum などが削除対象として列挙されています。(GitHub)
またレビューコメントでは、AzureClouds enumがAzure SDKの命名規則に沿っておらず、KnownAzureClouds のような Known* プレフィックスやPascalCaseメンバー名が望ましいと指摘されています。AzureSupportedClouds についても、閉じたtemplate literal unionではなく、将来互換性のため string と既知値のenumを組み合わせる形が望ましいとされています。(GitHub)
この領域での実務的な判断基準はシンプルです。
| 既存コードの書き方 | 移行時の注意 |
|---|---|
| enumをimportして固定値として使う | 新しい Known* 名や文字列型に変わっていないか確認 |
| 型エイリアスを関数引数に使う | 削除されていれば string や新しい型へ置換 |
| enumメンバー名を文字列化して保存 | メンバー名変更で保存値とズレないか確認 |
as any で回避 | 後続のADF定義変更を検出できなくなるため避ける |
列挙型の変更は、コンパイルだけでなく設定ファイルにも影響します。たとえば、社内ツールで CopyBehaviorType などを設定値として保持している場合、UI側・JSONスキーマ側・SDK呼び出し側の3か所を合わせて確認してください。
Resource 基底型のプロパティ削除
PR内の分析では、Resource 基底型から eTag、location、tags がなくなる変更も挙げられています。(GitHub)
この変更で注意すべきなのは、Data Factoryリソースや関連モデルから常に location や tags が取れると仮定しているコードです。特に、棚卸しや監査レポートで次のような処理を書いている場合は確認しましょう。
console.log(factory.location);
console.log(factory.tags?.env);移行後の型でこれらが取得できない場合、Azure Resource Managerの別の操作で取得する、または対象モデル固有のプロパティに存在するかを確認する必要があります。型定義にないプロパティへ無理にアクセスすると、TypeScriptではエラーになり、JavaScriptでは実行時に undefined になる可能性があります。
Node.js要件の確認
PR内の生成された package.json では、@azure/arm-datafactory のバージョンが 20.0.0、engines.node が >=20.0.0 とされています。また、sdk-type は mgmt です。(GitHub)
現在の公式ドキュメントでは、@azure/arm-datafactory はNode.js LTSや主要ブラウザーの最新バージョンをサポート対象として案内していますが、生成物としてNode.js 20以上が求められる場合、CI/CDや運用サーバーのNode.jsバージョンが問題になります。(Microsoft Learn)
確認コマンドは次の通りです。
node -v
npm ls @azure/arm-datafactory
npm ls @azure/identityDockerを使っている場合は、node:18 ベースのイメージを使い続けていないか確認してください。Azure Functions、GitHub Actions、Azure DevOps PipelineなどでNode.jsバージョンを明示している場合も同様です。
移行前に実行すべき確認手順
まずは、プロジェクトが今回の更新に本当に影響を受けるかを確認します。PRの内容だけを見てコードを変更するのではなく、実際に導入しているSDKバージョン、lockfile、CIの解決結果を確認することが重要です。
| 手順 | コマンド・確認内容 | 判断基準 | |
|---|---|---|---|
| SDK導入有無を確認 | npm ls @azure/arm-datafactory | パッケージがなければ直接影響は小さい | |
| lockfileを確認 | package-lock.json / pnpm-lock.yaml / yarn.lock | 意図せず20系に上がる余地がないか | |
| package.jsonを確認 | dependencies の指定 | ^ 指定で大きく上がらないか | |
| TypeScriptビルド | npx tsc --noEmit | 型変更を早期検出 | |
| 旧LROメソッド検索 | grep -R "begin[A-Z].*AndWait\ | begin[A-Z]" src | 該当があれば優先修正 | |
| Union型検索 | grep -R "Union" src | Data Factory関連の型を重点確認 | |
| ページング処理検索 | grep -R "\\.value" src | list系レスポンス前提を確認 | |
| Node.js確認 | node -v | Node 20以上が必要になる可能性を考慮 | |
| 実行テスト | ADF作成・更新・開始・停止・一覧取得 | 型だけでなく運用動作を確認 |
CIでは、skipLibCheck に頼りすぎないことも大切です。skipLibCheck: true はライブラリ型定義の問題を見えにくくします。すぐに無効化できない場合でも、移行検証用のジョブだけは厳しめのTypeScript設定で回すと、SDK更新の影響を見つけやすくなります。
変更確認で見るべきコード例
TriggerやIntegration Runtimeの開始・停止
Data Factoryの運用でよくあるのが、TriggerやIntegration RuntimeをSDKから開始・停止するスクリプトです。今回の更新では、旧 begin* 系メソッドの置き換えが示されているため、まずここを確認します。(GitHub)
検索例です。
grep -R "beginStart\|beginStop\|beginSubscribeToEvents\|beginUnsubscribeFromEvents" src scripts見つかった場合は、次の観点で修正します。
| 確認点 | 理由 |
|---|---|
| 新メソッド名が存在するか | start()、stop() などへ変わる可能性がある |
| 戻り値がPollerか | 完了待ちが必要な処理で待機漏れを防ぐ |
| エラーハンドリングが残っているか | LROの途中失敗を検出する |
| 運用ログに状態を出しているか | 開始・停止の結果確認が必要 |
一覧取得スクリプト
Data Factory内のPipelinesやDatasetsを棚卸しするコードでは、ページング処理の変更が問題になりやすいです。
grep -R "listByFactory" src scripts
grep -R "\.value" src scripts修正後は、for await...of で1件ずつ処理する形を基本にします。
for await (const pipeline of client.pipelines.listByFactory(
resourceGroupName,
factoryName
)) {
console.log(pipeline.name);
}この形にすると、件数が多いData Factoryでもページングを意識せず処理できます。ただし、すべての結果を配列化してから処理していたコードでは、メモリ使用量やソート処理の場所を見直してください。
型名を直接importしているコード
次のように、SDKのモデル型を多数importしているコードは移行時に影響を受けやすいです。
import {
ActivityUnion,
DatasetUnion,
LinkedServiceUnion,
KnownCompressionCodec
} from "@azure/arm-datafactory";この場合は、SDK更新後にimportエラーが出る型を1つずつ修正します。まとめて any に置き換えると、ADFの設定ミスを検出できなくなるため避けてください。
修正の優先順位は次の通りです。
- 本番ジョブの作成・更新に使う型
- TriggerやPipelineの開始・停止に関わる型
- 監査・棚卸し・レポート用途の型
- サンプルや開発用スクリプトの型
本番影響のある処理から直すことで、移行作業のリスクを下げられます。
すぐにアップデートすべきか
現時点で安易に「すぐアップデートすべき」とは言い切れません。PRは自動生成された候補であり、レビューコメントでは autoPublish: false がstable releaseとして問題視されていました。自動npm公開を有効にするには autoPublish が true であるべき、という指摘です。(GitHub)
そのため、実務では次の判断が現実的です。
| 状況 | 推奨対応 |
|---|---|
現在 19.0.0 で安定稼働している | すぐ本番更新せず、検証環境で差分確認 |
20.0.0-beta.1 を試している | TypeScriptエラーとLRO変更を重点確認 |
^19.0.0 のように範囲指定している | lockfileで実際の解決バージョンを固定確認 |
| Data Factory管理SDKを社内ツールで深く使っている | 移行チェックリストを作って段階検証 |
| JavaScriptで型チェックなしに使っている | 実行時テストを増やす。可能ならTypeScript化も検討 |
Azure SDKは依存関係として見えにくい場所で使われることがあります。たとえば、ADFの棚卸しスクリプト、夜間バッチのTrigger制御、運用自動化ツール、管理画面のバックエンドなどです。アプリ本体だけでなく、scripts/、tools/、infra/、ops/ 配下も検索してください。
失敗しやすいポイント
「stable」と「公開済み」を混同する
PR本文にSDK Release Type stable と書かれていても、それは生成・リリース準備上の種別を示している可能性があります。実際の利用可否は、npmの配布状況、Microsoft Learnのパッケージ一覧、GitHub上のリリースタグを合わせて確認してください。Microsoft Learnの一覧では、Data Factoryの安定版は 19.0.0、プレビューとして 20.0.0-beta.1 が掲載されています。(Microsoft Learn)
APIバージョンが同じだから安全だと思い込む
API Versionが 2018-06-01 のままでも、SDKの型定義やメソッド名は変わります。今回のPR内分析では、API Version Upgrade起因ではなく、TypeSpec / emitter移行起因の破壊的変更が180件とされています。(GitHub)
つまり、「Azure側のAPIが変わっていないからコードも変えなくてよい」と判断すると、TypeScriptビルドで詰まります。
any で型エラーを消す
移行時に最も避けたいのは、as any を大量に入れて型エラーを消すことです。Data Factoryの設定は、Pipeline、Dataset、Linked Service、Triggerなどが複雑に関係します。型エラーは、設定ミスや将来の仕様差分を早期に見つける手がかりです。
一時的に回避する場合でも、次のように期限と対象を限定してください。
// TODO: @azure/arm-datafactory v20移行時に型を再確認する
const dataset = rawDataset as unknown as Dataset;ただし、このような暫定対応は本番運用コードでは最小限にしましょう。
Node.jsバージョンをCIだけ見落とす
ローカルではNode.js 20、CIではNode.js 18という構成はよくあります。PR内の生成package.jsonではNode.js >=20.0.0 が指定されているため、将来20系を導入する場合はCI/CDの実行環境を先に確認してください。(GitHub)
GitHub Actionsなら、次のように明示します。
- uses: actions/setup-node@v4
with:
node-version: 20Azure DevOps Pipelineでも同様に、Node.jsのバージョン指定を確認してください。
実務向けチェックリスト
公開情報を見た段階で、まず次のチェックリストを実行してください。
| チェック | 完了基準 |
|---|---|
@azure/arm-datafactory の導入有無を確認 | npm ls で利用箇所を把握 |
| npm・Microsoft Learn・GitHubのバージョンを確認 | PR内容と実配布を混同しない |
begin* / begin*AndWait を検索 | 該当コードを一覧化 |
.value 前提の一覧処理を検索 | for await...of 移行候補を抽出 |
| Union型・Known enumのimportを検索 | 削除・名称変更の影響を確認 |
tsc --noEmit を実行 | 型エラーを移行タスク化 |
| Node.jsバージョンを確認 | Node 20以上が必要になる可能性を評価 |
| ADF操作の統合テストを実行 | Pipeline、Dataset、Trigger、Integration Runtimeを重点確認 |
| 本番反映前にlockfileを固定 | 意図しないSDK更新を防ぐ |
このチェックリストは、今回のPRだけでなく、Azure SDK for JavaScriptの管理系ライブラリ更新全般にも使えます。特に管理系SDKは、アプリ利用者向け機能ではなく運用自動化に組み込まれていることが多いため、影響が見えにくい点に注意が必要です。
まとめ：次に取るべき行動
今回のAzure SDK documentation updateは、Azure Data Factory向け @azure/arm-datafactory の生成更新に関する情報です。API Versionは 2018-06-01 のままで、PR内分析でもAPIバージョンアップ起因の破壊的変更はないとされています。一方で、TypeSpec / emitter移行により、型定義、Union型、begin* 系メソッド、ページング、列挙型、Node.js要件に影響が出る可能性があります。(GitHub)
最初にやるべきことは、コードを修正することではありません。まず、プロジェクトで @azure/arm-datafactory を使っているか、実際にどのバージョンが入っているか、begin* やUnion型を使っているかを確認してください。そのうえで、検証環境でTypeScriptビルドとADF操作テストを実行し、必要な箇所だけを段階的に移行するのが安全です。
特に本番のPipelineやTriggerを制御しているコードでは、メソッド名の置換だけで終わらせず、処理完了の待機、エラーハンドリング、ログ出力まで確認しましょう。
コメント