如何通过Azure DevOps REST API创建新的顶级待办事项层级？

核心API端点 #

你要找的对应「添加组合待办事项」的API端点是：
POST https://dev.azure.com/{organization}/{project}/_apis/work/processes/{processId}/workitemtypes/{witRefName}/behavior/compositefields?api-version=7.1-preview.1

实现步骤与代码示例 #

1. 获取目标流程的Process ID #

首先需要拿到项目使用的流程（如Scrum/Agile/CMMI）的ID：

import requests

# 替换为你的实际信息
ORG_NAME = "你的组织名称"
PROJECT_NAME = "你的项目名称"
PAT_TOKEN = "你的PAT令牌"

headers = {
    "Authorization": f"Basic {PAT_TOKEN}",
    "Content-Type": "application/json"
}

# 请求获取所有流程，筛选目标流程ID
process_list_url = f"https://dev.azure.com/{ORG_NAME}/_apis/work/processes?api-version=7.1-preview.2"
resp = requests.get(process_list_url, headers=headers)
processes = resp.json()["value"]
# 这里假设用的是Scrum流程，可替换为你实际使用的流程名称
process_id = next(p["id"] for p in processes if p["name"] == "Scrum")

2. 获取工作项类型的引用名 #

比如要给User Story添加待办事项层级，先获取它的引用名：

wit_list_url = f"https://dev.azure.com/{ORG_NAME}/_apis/work/processes/{process_id}/workitemtypes?api-version=7.1-preview.2"
resp = requests.get(wit_list_url, headers=headers)
wit_items = resp.json()["value"]
# 筛选User Story的引用名，可替换为其他工作项类型
wit_ref_name = next(w["referenceName"] for w in wit_items if w["name"] == "User Story")

3. 批量创建四个待办事项层级 #

构造请求体，一次性提交四个层级的创建请求：

create_composite_url = f"https://dev.azure.com/{ORG_NAME}/{PROJECT_NAME}/_apis/work/processes/{process_id}/workitemtypes/{wit_ref_name}/behavior/compositefields?api-version=7.1-preview.1"

# 构造四个层级的配置数据
payload = [
    {
        "name": "层级1",
        "referenceName": "Custom.CompositeLevel1",
        "type": "composite",
        "settings": {
            "workItemTypeReferenceName": wit_ref_name,
            "isEnabled": True,
            "label": "层级1"
        }
    },
    {
        "name": "层级2",
        "referenceName": "Custom.CompositeLevel2",
        "type": "composite",
        "settings": {
            "workItemTypeReferenceName": wit_ref_name,
            "isEnabled": True,
            "label": "层级2"
        }
    },
    {
        "name": "层级3",
        "referenceName": "Custom.CompositeLevel3",
        "type": "composite",
        "settings": {
            "workItemTypeReferenceName": wit_ref_name,
            "isEnabled": True,
            "label": "层级3"
        }
    },
    {
        "name": "层级4",
        "referenceName": "Custom.CompositeLevel4",
        "type": "composite",
        "settings": {
            "workItemTypeReferenceName": wit_ref_name,
            "isEnabled": True,
            "label": "层级4"
        }
    }
]

resp = requests.post(create_composite_url, json=payload, headers=headers)
if resp.status_code == 200:
    print("四个待办事项层级创建成功")
else:
    print(f"创建失败：{resp.json()}")

关键注意事项 #

• 你的PAT令牌必须拥有Process Administration权限，否则会返回403权限错误。
• 自定义字段的引用名必须以Custom.开头，避免和系统内置字段冲突。
• 使用7.1-preview.1版本的API，这是当前支持组合待办事项创建的稳定预览版。
• 在repl.it中运行时，建议将PAT令牌存到环境变量中，不要直接硬编码在代码里。

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