「Microsoft Azure documentation update: Migrate Kusto to autorest v4」は、Kusto自体のデータ分析機能やKQLの仕様変更ではなく、主にAzure PowerShellのAz.KustoモジュールをAutoRest.PowerShell v3生成からv4生成へ移行する更新です。結論として、Azure Data Explorer／Kustoクラスター、データベース、データ接続、権限設定をPowerShellで自動化している管理者・開発者は、Az.Kusto更新前にスクリプトのパラメーターセット、モデル型、-PassThru、ID関連パラメーター、JSON入力方式を確認する必要があります。
公式PR「Migrate Kusto to autorest v4」は2026年5月20日にAzure PowerShellリポジトリのmainブランチへマージされました。関連する事前告知PRでは、Az v16.0.0／2026年5月リリースに向けた破壊的変更のプレビュー通知が追加されており、単なるドキュメント整備ではなく、運用スクリプトに影響し得る移行として扱うべき更新です。(GitHub)
Microsoft Azure documentation update: Migrate Kusto to autorest v4の要点
今回の更新で押さえるべきポイントは、Az.Kustoのコマンドレットを生成する仕組みがAutoRest v4系へ移ることです。AutoRestはAzure PowerShellモジュールのコードやヘルプを生成するために使われるツールで、生成方式が変わると、同じKusto管理操作でもPowerShell上の構文、パラメーターセット、型名、ヘルプ表示が変わる場合があります。
| 確認項目 | 何が変わる可能性があるか | 実務での確認ポイント |
|---|---|---|
| コマンドレットの構文 | 既存のパラメーターセットが整理され、利用できる組み合わせが変わる可能性 | Get-Command <cmdlet> -Syntaxで現行スクリプトと比較する |
| JSON入力 | -JsonFilePathや-JsonStringを使うパラメーターセットが追加される場合 | 複雑な設定値をJSON化して渡す運用に切り替えられるか検討する |
| モデル型・名前空間 | APIバージョン付きの型参照が整理される可能性 | Microsoft.Azure.PowerShell.Cmdlets.Kusto.Models.Api20240413のような直参照を検索する |
| ID関連パラメーター | AutoRest v4生成モジュールではID指定方式が明示的なパラメーターへ変わる場合 | -IdentityTypeなどを使っていないか確認する |
-PassThru | 出力があるコマンドレットに誤って付いていた-PassThruが削除される場合 | -PassThru前提で成功判定しているスクリプトを見直す |
| 読み取り専用パラメーター | 入力として使うべきでない読み取り専用プロパティが削除される場合 | サービス側に無視されていたパラメーターを指定していないか確認する |
Microsoft LearnのAutoRest.PowerShell v4移行に関する説明では、IDパラメーターの変更、パラメーターセットの削除、配列とListの扱い、プリミティブ型への変更、-PassThruや読み取り専用パラメーターの削除が、生成モジュールで発生し得る破壊的変更として整理されています。すべてがAz.Kustoに一律で適用されるとは限りませんが、確認観点としてはそのまま使えます。(Microsoft Learn)
影響を受けやすい利用者
影響が大きいのは、Azureポータルで手作業している利用者ではなく、Az.Kustoを使ってKustoリソースを自動管理しているチームです。特に次のような環境では、更新を通常のモジュールアップデートとして流さず、事前検証を入れるべきです。
| 利用シーン | 影響度 | 理由 |
|---|---|---|
Azure DevOpsやGitHub ActionsでAz.Kustoを実行している | 高 | モジュール更新でパイプラインが突然失敗する可能性がある |
| Kustoクラスター、DB、データ接続をPowerShellで作成・更新している | 高 | New-*、Update-*系はパラメーターセット変更の影響を受けやすい |
| PowerShellスクリプト内でKustoモデル型を直接指定している | 高 | 名前空間や型名変更で型解決に失敗する可能性がある |
一時的な運用作業でGet-AzKustoClusterなどを使うだけ | 低〜中 | 構文変更の影響は比較的小さいが、ヘルプ確認は必要 |
| AzureポータルやARM/Bicep中心で管理している | 低 | Az.Kustoに依存していなければ直接影響は限定的 |
Az.Kustoモジュールは、Kustoクラスター、データベース、データ接続、プリンシパル割り当て、マネージドプライベートエンドポイント、スクリプトなど、多くの管理系コマンドレットを提供しています。単一のコマンドだけでなく、リソース作成から権限付与、削除、開始・停止までを一連のPowerShellで自動化している場合は、影響範囲を広めに見積もるのが安全です。(Microsoft Learn)
具体的な変更点：パラメーターセットとJSON入力の追加
実際のAz.Kustoヘルプでは、たとえばNew-AzKustoDatabaseにCreateViaJsonFilePathとCreateViaJsonStringのパラメーターセットが追加されています。これにより、従来のように個別パラメーターを並べる方法に加え、JSONファイルやJSON文字列で作成内容を渡す選択肢が増えています。(GitHub)
たとえば、これまで次のように個別パラメーターでデータベースを作成していた場合があります。
New-AzKustoDatabase `
-ResourceGroupName "testrg" `
-ClusterName "testnewkustocluster" `
-Name "mykustodatabase" `
-Kind "ReadWrite" `
-Location "East US"AutoRest v4移行後は、コマンドレットによってはJSON入力のパラメーターセットも選択肢になります。
New-AzKustoDatabase `
-ResourceGroupName "testrg" `
-ClusterName "testnewkustocluster" `
-Name "mykustodatabase" `
-JsonFilePath ".\kusto-database.json"JSON入力は、設定値が多いリソースや、環境ごとにパラメーターをテンプレート化したい場合に便利です。一方で、既存スクリプトを急いでJSON化する必要はありません。まずは現在使っている構文が新しいヘルプ上で有効かを確認し、複雑な設定だけJSON化するのが現実的です。
モデル型を直接使っているコードは特に注意
PowerShellだけで完結しているスクリプトでは、Kustoモデル型を直接意識しないことも多いです。しかし、次のような書き方をしている場合は注意が必要です。
[Microsoft.Azure.PowerShell.Cmdlets.Kusto.Models.Api20240413.IDatabasePrincipal]AutoRest v4移行では、モデル参照からAPIバージョン固有の名前空間が整理される可能性があります。PRのレビュー概要でも、APIバージョン固有の名前空間の削除や、テストファイルのモデル名前空間更新が変更点として示されています。(GitHub)
現在のヘルプでは、Add-AzKustoDatabasePrincipalの-Value型がMicrosoft.Azure.PowerShell.Cmdlets.Kusto.Models.IDatabasePrincipal[]として示され、IKustoIdentityもAPIバージョンなしの名前空間で表示されています。型を直接指定している場合は、APIバージョン付きの型名に依存せず、ハッシュテーブルや更新後の型名に置き換える方が保守しやすくなります。(GitHub)
管理者・開発者が最初に確認すべきコマンド
本番環境でモジュールを更新する前に、まず検証環境で現在のAz.Kustoと更新後のAz.Kustoを比較します。特にCI/CDやAzure Automationで使っている場合は、「手元では動くが実行環境では別バージョン」という事故が起きやすいため、実行環境側のバージョン確認を優先してください。
Get-Module -ListAvailable Az.Kusto |
Sort-Object Version -Descending |
Select-Object Name, Version, Pathインストール済みのAz全体も確認します。
Get-Module -ListAvailable Az |
Sort-Object Version -Descending |
Select-Object Name, Version, Path使っているコマンドレットの構文を確認します。
Get-Command New-AzKustoDatabase -Syntax
Get-Command Add-AzKustoDatabasePrincipal -Syntax
Get-Command Update-AzKustoDataConnection -Syntaxスクリプト内に古い型名や変更影響を受けやすい指定がないか検索します。
Get-ChildItem . -Recurse -Include *.ps1,*.psm1,*.psd1,*.cs |
Select-String -Pattern `
'Api20240413',
'Microsoft\.Azure\.PowerShell\.Cmdlets\.Kusto\.Models\.Api',
'IdentityType',
'PassThru'検索にヒットした場合は、単純に文字列置換するのではなく、該当コマンドレットの最新ヘルプを確認してから修正します。特に-PassThruは、削除しても処理結果の判定方法を変えないと、成功・失敗の検知ロジックが壊れることがあります。
移行時に失敗しやすいポイント
モジュールのリリース時期とGitHub上のmainブランチを混同しない
2026年5月20日のPRマージは、Azure PowerShellリポジトリ上のmainブランチへの反映です。実際にPowerShell Gallery、Cloud Shell、Azure Automation、コンテナイメージなどで利用できるタイミングは、Azモジュールのリリースサイクルや各環境の更新タイミングに依存します。
PowerShell Gallery上では、Az 15.6.1にAz.Kusto 2.4.1が含まれ、リリースノート上は破壊的変更の事前告知が記載されています。一方、5月20日の移行PRはその後のmainブランチ更新として扱われるため、手元の環境にすぐ反映されているとは限りません。(GitHub)
そのため、確認時は「公式PRがマージされたか」だけでなく、「自分の実行環境でどのバージョンのAz.Kustoが読み込まれているか」を必ず見ます。
Update-Moduleを本番ジョブで無条件に実行しない
CI/CDの先頭で次のような処理を入れている場合、ある日突然、新しいAz.Kustoが入り、同じスクリプトが失敗する可能性があります。
Update-Module -Name Az -Force本番ジョブでは、少なくとも移行検証が終わるまでバージョンを固定する方が安全です。
Install-Module -Name Az.Kusto -RequiredVersion "2.4.1" -Repository PSGallery -Scope CurrentUser -Forceただし、ここで指定するバージョンは自社で検証済みのものにします。最新版が常に最適とは限りません。更新を急ぐより、検証済みバージョンを明示して再現性を確保することが重要です。
ヘルプの更新だけを見て「動作は変わらない」と判断しない
今回の更新では、ヘルプファイル、例、テスト、生成メタデータ、モジュールマニフェストなど広い範囲に変更が入っています。PRのファイル一覧でも、docs、help、examples、test、generate-info.json、Az.Kusto.psd1などが対象に含まれています。(GitHub)
ヘルプが更新されたということは、実際のコマンドレット構文やパラメーターセットも更新されている可能性があります。公開前の確認では、ドキュメント差分だけでなく、実際にPowerShellでGet-Command -SyntaxとPesterテストを走らせるのが確実です。
安全に展開するための移行手順
Az.Kustoを使うチームでは、次の順序で進めるとリスクを抑えられます。
| 手順 | 作業 | 判断基準 |
|---|---|---|
| 1 | 利用中のAz.Kustoコマンドレットを洗い出す | Get-ChildItemとSelect-StringでAzKustoを検索 |
| 2 | 現行バージョンを記録する | Get-Module -ListAvailable Az.Kustoの結果を保存 |
| 3 | 検証環境で新バージョンを入れる | 本番と同じPowerShell、OS、実行ユーザーで試す |
| 4 | Get-Command -Syntaxを比較する | 使っているパラメーターセットが残っているか確認 |
| 5 | 型名・-PassThru・ID関連指定を修正する | エラーが出た箇所だけでなく、検索ヒット箇所を全確認 |
| 6 | CI/CDやAzure Automationでリハーサルする | 手元の端末ではなく実行基盤で成功することを確認 |
| 7 | 本番反映時はバージョンを固定する | ロールバックできるよう旧バージョンの手順も残す |
特に重要なのは、手順4と手順6です。PowerShellモジュールの変更は、ローカルPCでは成功しても、Azure Automationやビルドエージェントでは別のモジュールが読み込まれて失敗することがあります。$env:PSModulePathやモジュールのインストール場所も含めて確認してください。
既存スクリプトの修正例
APIバージョン付きモデル型を避ける
型を直接指定している場合は、可能であればハッシュテーブルで渡します。
$value = @(
@{
Name = "Some User"
Role = "Admin"
Type = "User"
Email = "[email protected]"
}
)
Add-AzKustoDatabasePrincipal `
-ResourceGroupName "testrg" `
-ClusterName "testnewkustocluster" `
-DatabaseName "mykustodatabase" `
-Value $valueこの書き方なら、内部のモデル型変更に直接引きずられにくくなります。
-PassThru前提の成功判定を見直す
削除系や開始・停止系で-PassThruを使って成功判定している場合は、実行後に対象リソースの状態を取得して判定する方が堅実です。
Stop-AzKustoCluster -ResourceGroupName "testrg" -Name "testnewkustocluster"
$cluster = Get-AzKustoCluster -ResourceGroupName "testrg" -Name "testnewkustocluster"
$cluster.State-PassThruの戻り値に依存するより、最終状態を確認する方が、モジュール変更にも運用トラブルにも強くなります。
まとめ：まずはAz.Kusto依存の自動化を棚卸しする
「Migrate Kusto to autorest v4」は、Kustoのサービス仕様そのものよりも、Azure PowerShellでKustoを管理する自動化に影響する更新です。まず確認すべきことは、Az.Kustoを使っているスクリプト、CI/CD、Azure Automation Runbook、自作モジュールの棚卸しです。
次に、Get-Command -Syntaxで実際の構文を確認し、Api20240413のような型名、-IdentityType、-PassThruへの依存を検索します。問題がある箇所は、最新ヘルプに沿ってパラメーターセットを修正し、検証環境と本番と同じ実行基盤の両方でテストしてください。
本番展開では、Update-Module任せにせず、検証済みのAz.Kustoバージョンを明示することが重要です。今回の更新は、早く追従するよりも「どの環境で、どのバージョンの、どの構文を使うか」を固定してから進めるのが安全です。
コメント