PowerShell调用REST API：获取JSON更新后PUT请求失败排查

问题根源 #

原代码存在两个核心问题：

1. 直接将PowerShell对象传给-Body参数，即使指定了-ContentType，PowerShell也无法保证序列化出符合API要求的JSON结构，尤其是嵌套对象或数组场景。
2. 使用ConvertTo-Json时未指定足够的序列化深度，或未处理UTF-8编码，导致API无法解析请求体。

修正后的代码 #

# 获取远程设置
$headers = @{
  "Accept" = "application/json"
}
$settings = Invoke-RestMethod -Uri "$($apiUrl)/settings" -Method Get -Headers $headers

# 修改目标属性
$settings.name = "Hello World!"

# 配置PUT请求头
$headers = @{
  "Authorization" = $token
  "Accept"        = "application/json"
  "Content-Type"  = "application/json"
}

# 将对象序列化为JSON，指定足够深度避免数据截断
$jsonBody = $settings | ConvertTo-Json -Depth 5
# 转换为UTF-8字节数组提交（适配绝大多数API的编码要求）
$response = Invoke-RestMethod -Uri "$($apiUrl)/settings" -Method Put -Headers $headers -Body ([System.Text.Encoding]::UTF8.GetBytes($jsonBody))

关键注意事项 #

• -Depth参数：ConvertTo-Json默认仅序列化2层嵌套结构，若API返回的设置存在更深层级，需手动指定足够深度（如-Depth 5），否则部分数据会被截断为{}，导致API解析失败。
• UTF-8编码处理：直接传递JSON字符串时，PowerShell可能使用UTF-16编码提交，而多数REST API仅支持UTF-8。手动转换为UTF-8字节数组可避免编码不兼容问题。
• JSON有效性验证：执行PUT前可先验证JSON格式：

  $jsonBody | Test-Json
  

  若验证失败，需检查修改后的对象结构是否符合API要求。

内容的提问来源于stack exchange，提问作者Ben Steenson