この記事について
この記事は、生成AIを活用した自動生成フローで作成しています。Microsoft LearnのConvertTo-Json仕様を確認し、深いオブジェクトをJSONへ変換するときのDepthを安全なダミーデータで比べます。この記事作成時にはPowerShell実行を行っていません。検証ステータス：📘 公式仕様確認済み・PowerShell実行未確認
情報確認日：2026年10月2日。
API用JSONで期待した階層にならないとき、ConvertTo-JsonのDepthを確認します。
入れ子を作る
$data = [pscustomobject]@{
Name = 'demo'
Settings = [pscustomobject]@{
Network = [pscustomobject]@{
Proxy = [pscustomobject]@{ Enabled = $false; Port = 8080 }
}
}
}
$data | ConvertTo-Json -Depth 2
$data | ConvertTo-Json -Depth 5
Microsoft LearnではDepthの既定値は2です。指定したDepthを超える入力について警告される場合があります。
再読込して確認する
$json = $data | ConvertTo-Json -Depth 5 $check = $json | ConvertFrom-Json $check.Settings.Network.Proxy.Port
8080が辿れるかを見ます。
1か所変える
Depthを3へ変え、出力と警告を比較します。
flowchart TD
A["Object"] --> B["ConvertTo-Json"]
B --> C{"Depth十分?"}
C -->|Yes| D["必要階層"]
C -->|No| E["警告/表現を確認"]
仕事で使うなら
Depthをむやみに最大へせず、APIが必要とする構造を把握して十分な値を指定します。
なぜDepthがAPI障害につながるのか
PowerShell上のobjectが正しく見えていても、APIへ渡す直前にはJSONという別の表現へserializeされます。ここで必要な階層まで表現できていなければ、「PowerShellでは値があるのに、送信先では設定が欠ける」という切り分けにくい障害になります。
そこで送信前にJSON文字列を見るだけでなく、一度ConvertFrom-Jsonで戻して、必要なpropertyまで辿れるか確認します。Depthを大きくすれば常に正解というより、API contract上必要な深さを把握して、その構造が保持されていることを確認するのがポイントです。
