使用VSTS REST API更新构建定义时遇请求反序列化异常

我来帮你搞定这个头疼的问题！你遇到的这个「请求正文无法反序列化」的错误，几乎都是因为请求的JSON格式不对，或者没遵循Azure DevOps/TFS构建定义API的要求。下面给你拆解原因和具体解决步骤：

核心原因分析 #

Azure DevOps的构建定义API（PUT方法）要求你传递完整的构建定义对象，而不是只传变量部分；同时对JSON的格式、嵌套深度有严格要求，稍有疏忽就会触发反序列化失败。

正确操作步骤（附代码示例） #

1. 先获取现有构建定义 #

首先要拉取当前完整的构建定义，因为更新时需要把整个定义回传给API，不能只修改变量就提交：

# 替换成你的组织、项目、定义ID和PAT
$orgUrl = "https://dev.azure.com/你的组织名"
$projectName = "你的项目名"
$definitionId = 123 # 你的构建定义ID
$pat = "你的个人访问令牌（PAT）"
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f "", $pat)))

# 获取现有构建定义
$definitionUrl = "$orgUrl/$projectName/_apis/build/definitions/$definitionId`?api-version=7.1-preview.7"
$existingDefinition = Invoke-RestMethod -Uri $definitionUrl -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)} -Method Get

2. 修改变量部分 #

构建定义里的变量是嵌套对象结构，不是简单的键值对。你可以修改现有变量，或者添加新变量：

# 示例1：更新现有变量的值
$existingDefinition.variables["你的变量名"].value = "新的变量值"

# 示例2：添加一个新的非保密变量
$existingDefinition.variables["新变量名"] = @{
    value = "新变量的值"
    isSecret = $false
}

# 示例3：添加一个保密变量（会被加密存储）
$existingDefinition.variables["保密变量名"] = @{
    value = "保密内容"
    isSecret = $true
}

3. 正确序列化JSON（关键！） #

PowerShell的ConvertTo-Json默认深度只有2，而构建定义的嵌套层级远超过这个数，直接序列化会导致内容被截断，这是最容易踩的坑！一定要指定足够的深度：

# 序列化时指定深度10（根据你的定义复杂度可以调整更大）
$jsonBody = $existingDefinition | ConvertTo-Json -Depth 10

4. 发送更新请求 #

最后发送PUT请求，务必指定Content-Type为application/json：

$updateUrl = "$orgUrl/$projectName/_apis/build/definitions/$definitionId`?api-version=7.1-preview.7"
Invoke-RestMethod -Uri $updateUrl -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)} -Method Put -Body $jsonBody -ContentType "application/json"

常见坑点排查 #

• 不要尝试只传递变量部分给API：PUT操作要求完整的构建定义，否则API无法识别
• 检查JSON是否被截断：可以把$jsonBody打印出来，看看末尾是否有...，如果有就说明深度不够，调大-Depth的值
• 确认PAT的权限：必须给PAT分配「Build（编辑）」权限，否则会返回权限错误
• 不要遗漏Content-Type头：没有这个头，API会把请求正文当成纯文本，自然无法反序列化

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