使用Azure DevOps REST API创建带查询设置的Widget时遇空值错误

问题描述 #

调用Azure DevOps的Create Widget REST API创建"Open Issues"小部件时，添加settings参数关联查询会触发如下空值异常：

{'$id': '1',
 'innerException': None,
 'message': 'Value cannot be null.\r\nParameter name: widget',
 'typeName': 'System.ArgumentNullException, mscorlib',
 'typeKey': 'ArgumentNullException',
 'errorCode': 0,
 'eventId': 0
}

提交的请求payload如下：

payload = {
  "name": "Open Issues",
  "position": {
      "row": 2, 
      "column": 6
  },
  "size": {
      "rowSpan": 1, 
      "columnSpan": 1
  },
  "settings": {
      "defaultBackgroundColor":"#51399f",
      "queryId":"2d5d4371-bb0d-4984-b277-f71eca948d34",
      "queryName":"Open Issues",
      "colorRules":[{
          "isEnabled":True,
          "backgroundColor":"#339947",
          "thresholdCount":0,
          "operator":"<="}],
      "lastArtifactName": "Open Issues"
  },
  "settingsVersion": {    
      "major": 1,    
      "minor": 0,    
      "patch": 0 
  },
  "contributionId": "ms.vss-dashboards-web.Microsoft.VisualStudioOnline.Dashboards.QueryScalarWidget"
}

将settings设为null可成功创建小部件，但无法关联目标查询；且已通过Get Widgets接口确认payload格式与现有小部件的返回结果一致。

解决思路 #

1. 修正布尔值的JSON格式 #

Python中的True为大写，但JSON规范要求布尔值为小写的true。若直接将Python字典序列化，部分库可能未自动转换，导致API无法正确解析settings字段，进而触发widget参数为空的异常。确保序列化后的JSON中布尔值为小写。

2. 验证queryId的有效性 #

确认queryId对应的查询存在于当前项目中，且调用API的账号拥有该查询的读取权限。无效或无权限的queryId可能导致API内部处理失败，抛出看似无关的空值错误。

3. 调整settingsVersion版本号 #

部分小部件类型需要匹配特定的settingsVersion。尝试将minor版本改为1（如"minor":1），与线上已存在的同类型小部件版本保持一致。

4. 移除冗余字段 #

lastArtifactName并非该类型小部件的必填字段，尝试从settings中移除该字段，避免因冗余字段导致的解析异常。

修正后的payload示例 #

payload = {
  "name": "Open Issues",
  "position": {
      "row": 2, 
      "column": 6
  },
  "size": {
      "rowSpan": 1, 
      "columnSpan": 1
  },
  "settings": {
      "defaultBackgroundColor":"#51399f",
      "queryId":"2d5d4371-bb0d-4984-b277-f71eca948d34",
      "queryName":"Open Issues",
      "colorRules":[{
          "isEnabled": True,  # 序列化JSON时会自动转为小写true
          "backgroundColor":"#339947",
          "thresholdCount":0,
          "operator":"<="}]
  },
  "settingsVersion": {    
      "major": 1,    
      "minor": 1,    
      "patch": 0 
  },
  "contributionId": "ms.vss-dashboards-web.Microsoft.VisualStudioOnline.Dashboards.QueryScalarWidget"
}

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