如何通过REST API更新DevOps项目默认概览仪表板并添加部件

你遇到的问题核心是错误使用了API端点和请求体格式，导致系统新建仪表板而非更新现有默认概览仪表板。以下是正确的实现步骤：

1. 确认目标仪表板的关键信息 #

首先通过GET请求获取默认概览仪表板的详情，确保拿到正确的dashboardId和eTag（用于并发控制）：

GET https://dev.azure.com/TenantN/DemoProject/_apis/dashboard/dashboards/e63247c4-b069-4bfe-ad1f-6fe609579629?api-version=7.1-preview.2

返回结果中提取eTag字段，后续更新必须携带该值避免冲突。

2. 选择正确的API操作方式 #

方式一：单个添加部件（推荐） #

使用Widgets Create专用接口，直接向指定仪表板添加单个部件，无需修改整个仪表板的配置：

• 请求方法：POST
• 请求URL：https://dev.azure.com/TenantN/DemoProject/_apis/dashboard/dashboards/e63247c4-b069-4bfe-ad1f-6fe609579629/widgets?api-version=7.1-preview.2
• 请求体（仅包含部件的配置，无需仪表板级字段）：

{
    "name": "TestSQ",
    "position": {
        "row": 1,
        "column": 1
    },
    "size": {
        "rowSpan": 1,
        "columnSpan": 1
    },
    "settings": "",
    "settingsVersion": {
        "major": 1,
        "minor": 0,
        "patch": 0
    },
    "contributionId": "ms.vss-dashboards-web.Microsoft.VisualStudioOnline.Dashboards.QueryScalarWidget"
}

方式二：批量更新仪表板部件 #

如果需要一次性添加多个部件或修改仪表板其他配置，使用PATCH请求更新整个仪表板：

• 请求方法：PATCH
• 请求URL：https://dev.azure.com/TenantN/DemoProject/_apis/dashboard/dashboards/e63247c4-b069-4bfe-ad1f-6fe609579629?api-version=7.1-preview.2
• 请求头：必须添加If-Match: 3（这里的3是你之前获取的仪表板eTag值）
• 请求体注意事项：
  • widgets必须是数组格式（你之前的请求体是单个对象，这是核心错误）
  • 需包含原有部件数组+新部件，避免覆盖原有配置；仅更新需要修改的字段
  • 示例请求体：

{
    "eTag": "3",
    "widgets": [
        // 原有部件的配置（如果需要保留）
        {
            "name": "原有部件1",
            "position": {...},
            "size": {...},
            // 其他原有部件字段
        },
        // 新添加的部件
        {
            "name": "TestSQ",
            "position": {
                "row": 1,
                "column": 1
            },
            "size": {
                "rowSpan": 1,
                "columnSpan": 1
            },
            "settings": "",
            "settingsVersion": {
                "major": 1,
                "minor": 0,
                "patch": 0
            },
            "contributionId": "ms.vss-dashboards-web.Microsoft.VisualStudioOnline.Dashboards.QueryScalarWidget"
        }
    ]
}

核心错误点总结 #

• 错误使用了仪表板的PUT/PATCH端点来添加部件，而非专用的/widgets子端点
• 请求体格式错误：widgets应为数组，且不应在部件操作请求中包含仪表板级别的字段（如name、description）
• 未正确携带eTag及If-Match请求头，导致系统无法识别为更新操作，进而新建仪表板

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