Azure DevOps API推送请求参数合规却报错的排查求助

问题背景 #

调用Azure DevOps的Git推送API：
https://MYSITE.visualstudio.com/MYPROJECT/_apis/git/repositories/2b34d4f7-2c1f-42e7-8861-u0ba34f72b40/pushes?api-version=5.1

请求体如下：

{
  "commits": [
    {
      "comment": "Just a dummy commit",
      "changes": [
        {
          "changeType": "edit",
          "item": {
            "path": "/src/MYPROJECT/MYPROJECT.csproj"
          },
          "newContent": {
            "content": "beans",
            "contentType": "rawText"
          }
        }
      ]
    }
  ],
  "refUpdates": [
    {
      "name": "refs/heads/TestDummyPRs/upgradeProjectToLatest",
      "oldObjectId": "058da4f3328cb1048cb43faf3b5158bc3b025615"
    }
  ]
}

收到错误：

Web Request Failed after 4 attempts. Request: https://MYSITE.visualstudio.com/MYPROJECT/_apis/git/repositories/2b34d4f7-2c1f-42e7-8861-u0ba34f72b40/pushes?api-version=5.1. Status: BadRequest. Response: Invalid status code [BadRequest]. Response: {"$id":"1","innerException":null,"message":"The parameters are incorrect. A posted push must contain exactly one commit and one refUpdate.\r\nParameter name: newPush","typeName":"Microsoft.TeamFoundation.SourceControl.WebServer.InvalidArgumentValueException, Microsoft.TeamFoundation.SourceControl.WebServer","typeKey":"InvalidArgumentValueException","errorCode":0,"eventId":0}

尝试改用网页端抓包的数值枚举值后仍报错，其他API请求（创建分支、获取文件内容）正常。

排查与解决方案 #

1. 检查仓库ID的合法性 #

请求URL中的仓库ID 2b34d4f7-2c1f-42e7-8861-u0ba34f72b40 存在非法字符：第五段首字符是u，而UUID仅允许十六进制字符（0-9、a-f/A-F），这大概率是输入错误（比如将0误写为u）。

• 解决方法：从Azure DevOps项目仓库的设置中复制正确的仓库ID，替换URL中的错误ID。

2. 确认oldObjectId的正确性 #

oldObjectId必须是目标分支当前的最新提交ID，如果该ID已过时（分支已有新提交），API会拒绝请求，且可能返回误导性的参数错误提示。

• 验证方法：调用Git分支查询接口获取目标分支refs/heads/TestDummyPRs/upgradeProjectToLatest的最新objectId，确保与请求体中的值完全一致。

3. 检查请求头设置 #

确保请求头中包含Content-Type: application/json，如果缺少该头，API可能无法正确解析JSON请求体，导致识别不到commits或refUpdates字段，从而抛出参数错误。

4. 确认枚举值映射正确 #

API同时支持字符串和数值枚举，但需确保映射完全正确：

• changeType：edit对应数值2
• contentType：rawText对应数值0
  使用字符串枚举时需严格区分大小写，比如不能写成"Edit"或"EDIT"。

5. 检查JSON序列化完整性 #

确保代码序列化请求体时没有丢失字段或产生语法错误：

• 排查是否存在多余逗号、缺失引号等JSON语法问题
• 确认commits和refUpdates均为数组且仅包含一个元素（符合API要求）

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