关于本文
本文是通过利用生成式 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。
修改一处
将 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 的另一种表示形式。如果此时无法表达所需的层级，就会变成难以排查的故障，即“PowerShell 中有值，但发送端却缺失了设置”。
因此，在发送前不仅要查看 JSON 字符串，还要通过 ConvertFrom-Json 转换回来，确认是否能够追踪到所需的 property。与其说增大 Depth 总是正确的，不如说掌握 API contract（契约）所需的深度并确认该结构得以保留才是关键点。
