使用VSTS Rest API创建Markdown组件时遇eTag错误，求助解决方案

看起来你遇到的ETag错误是VSTS REST API的乐观并发控制机制在起作用——它用来确保你操作的资源（这里是仪表板或Widget）在你发起请求时没有被其他操作修改过。下面给你一步步的解决方案：

1. 获取最新的仪表板ETag（创建Widget时必需） #

在创建新的Markdown Widget前，你需要先获取目标仪表板的最新ETag值，确保你的请求是基于当前最新版本的仪表板：

GET https://{accountName}.visualstudio.com/{project}/{team}/_apis/dashboard/dashboards/{dashboardId}?api-version=5.0-preview.2

你可以从响应的响应头ETag或者响应体里的dashboard.eTag字段拿到这个值，注意要完全匹配（包括引号，比如响应头里的"18"要完整带引号使用）。

2. 修正创建Widget的请求体 #

把你原本请求体里的"dashboard": { "eTag": "18" }替换成刚获取到的最新ETag值。修正后的请求体示例如下：

{
  "name": "Markdown",
  "position": {
    "row": 1,
    "column": 4
  },
  "size": {
    "rowSpan": 2,
    "columnSpan": 2
  },
  "settings": "# AK Markdown\nAdd content using the markdown widget.\n- **Bold**\n- *Italic*\n- [Links]()",
  "settingsVersion": {
    "major": 1,
    "minor": 0,
    "patch": 0
  },
  "dashboard": {
    "eTag": "最新获取的仪表板ETag值"
  },
  "contributionId": "ms.vss-dashboards-web.Microsoft.VisualStudioOnline.Dashboards.MarkdownWidget"
}

另外要确保你的JSON请求体是正确序列化的——比如换行符\n要正确转义，避免格式错误导致的隐式问题。

3. 更新现有Widget的正确姿势 #

如果要更新已存在的Markdown Widget，不要用POST，而是要用PUT请求，并且需要带上Widget自身的ETag（不是仪表板的）：

步骤： #

• 先获取目标Widget的详情，拿到它的ETag：

GET https://{accountName}.visualstudio.com/{project}/{team}/_apis/dashboard/dashboards/{dashboardId}/widgets/{widgetId}?api-version=5.0-preview.2

• 使用PUT请求更新，请求地址为：

PUT https://{accountName}.visualstudio.com/{project}/{team}/_apis/dashboard/dashboards/{dashboardId}/widgets/{widgetId}?api-version=5.0-preview.2

• 请求体里需要包含Widget的ETag，示例：

{
  "name": "Markdown",
  "position": {
    "row": 1,
    "column": 4
  },
  "size": {
    "rowSpan": 2,
    "columnSpan": 2
  },
  "settings": "# 更新后的AK Markdown\n这里是构建/发布完成后的最新数据",
  "settingsVersion": {
    "major": 1,
    "minor": 0,
    "patch": 0
  },
  "eTag": "Widget自身的最新ETag值",
  "contributionId": "ms.vss-dashboards-web.Microsoft.VisualStudioOnline.Dashboards.MarkdownWidget"
}

这样就能解决你遇到的ETag错误，顺利实现构建/发布完成后自动创建或更新Markdown组件的需求了。

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