无法通过Azure DevOps REST API为系统内置工作项类型新增状态

问题根源 #

系统默认工作项类型（如Bug、UserStory）的引用名称（witRefName）并非通用的Microsoft.VSTS.WorkItemTypes.xxx，而是与项目绑定的具体流程模板（如自定义Kanban、Scrum、Agile）关联，格式为[流程名称].[工作项类型]（例如Processo-Kanban.Bug）。直接使用全局默认RefName会触发VS402805错误，因为该名称在当前流程的工作项类型列表中不存在。

解决方案步骤 #

1. 获取目标流程下工作项类型的正确RefName #

通过Azure DevOps Processes API查询当前项目绑定流程的所有工作项类型，提取对应的引用名称：

import requests
from requests.auth import HTTPBasicAuth

# 替换为你的组织、流程ID和个人访问令牌（PAT）
ORG_URL = "https://dev.azure.com/你的组织名"
PROCESS_ID = "你的流程ID"
PAT = "你的PAT令牌"

# 调用API获取流程下所有工作项类型
url = f"{ORG_URL}/_apis/work/processes/{PROCESS_ID}/workitemtypes?api-version=7.1-preview.2"
response = requests.get(url, auth=HTTPBasicAuth('', PAT))
wit_list = response.json()["value"]

# 遍历输出工作项类型名称与对应RefName
for wit in wit_list:
    print(f"工作项类型: {wit['name']} | 引用名称: {wit['referenceName']}")

如何获取流程ID？

先调用流程列表API获取所有流程，找到目标项目使用的流程ID：

url = f"{ORG_URL}/_apis/work/processes?api-version=7.1-preview.2"
response = requests.get(url, auth=HTTPBasicAuth('', PAT))
process_list = response.json()["value"]
for process in process_list:
    print(f"流程名称: {process['name']} | 流程ID: {process['id']}")

2. 使用正确的RefName调用添加状态API #

将脚本中原来的Microsoft.VSTS.WorkItemTypes.xxx替换为上述步骤获取的流程绑定RefName，再调用状态添加API：

# 替换为实际的工作项类型RefName和新状态信息
WIT_REF_NAME = "Processo-Kanban.Bug"
NEW_STATE_NAME = "待评审"
NEW_STATE_COLOR = "ffa500"
STATE_CATEGORY = "InProgress"  # 可选值：Proposed, InProgress, Resolved, Completed, Removed

# 添加状态的API请求
add_state_url = f"{ORG_URL}/_apis/work/processes/{PROCESS_ID}/workitemtypes/{WIT_REF_NAME}/states?api-version=7.1-preview.3"
payload = {
    "name": NEW_STATE_NAME,
    "color": NEW_STATE_COLOR,
    "stateCategory": STATE_CATEGORY
}

response = requests.post(add_state_url, json=payload, auth=HTTPBasicAuth('', PAT))
# 检查响应结果
if response.status_code == 201:
    print("状态添加成功:", response.json())
else:
    print("错误信息:", response.json())

3. 关键注意事项 #

• 确保你的PAT拥有**Processes (Read & Write)**权限，否则会触发权限错误。
• 不同流程模板下的同一工作项类型RefName不同，比如Scrum流程下的Bug可能是Scrum.Bug，自定义Kanban流程下是Processo-Kanban.Bug。
• Web UI操作后能看到正确RefName的原因是，UI会自动使用当前流程绑定的实例化RefName进行操作。

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