TFS 2017 API：排队构建时自定义变量值未覆盖默认值问题

嘿，我来帮你搞定这个变量覆盖不生效的问题！你遇到的情况很常见，大概率是请求体的格式没弄对，或者有几个容易忽略的细节没注意到，下面给你逐一排查：

最可能的原因：变量参数的格式错误 #

TFS 2017（对应API 3.1）要求你在请求体的parameters字段中，用转义后的JSON字符串来指定变量的新值，而不是直接放JSON对象。正确的格式应该是这样的：

{
  "definition": { "id": 你的构建定义ID },
  "parameters": "{\"variables['你的自定义变量名'].value\": \"你要设置的新值\"}"
}

举个实际例子，如果你的变量名叫DeployEnvironment，想要改成Production，请求体就是：

{
  "definition": { "id": 456 },
  "parameters": "{\"variables['DeployEnvironment'].value\": \"Production\"}"
}

很多人容易犯的错是直接把parameters设为普通JSON对象，比如{"DeployEnvironment": "Production"}，这种格式TFS是识别不了的，必须用嵌套的variables['xxx'].value结构，并且整个参数内容要转义成字符串。

其他需要检查的细节 #

• 变量名大小写敏感：TFS对变量名的大小写是严格区分的，比如定义里是BuildVersion，你传buildversion就不会生效，必须完全匹配。
• 变量是否允许队列时修改：去你的构建定义里检查这个自定义变量的属性，如果勾选了“只读”（不能在排队时更改），那就算API传了新值也会被忽略，得取消这个设置。
• API版本与服务器版本匹配：确认你的TFS服务器版本是2017及以上（API 3.1对应TFS 2017），如果是更早的版本，变量覆盖的格式可能不一样，需要调整API版本或者升级服务器。

验证方法 #

提交请求后，你可以去TFS的构建队列里找到这个排队的构建，查看它的“变量”标签，看看自定义变量是否已经被更新成你传入的值。如果还是没生效，对比上面的正确格式，检查自己的请求体哪里写错了。

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