如何使用Python API新增Azure DevOps迭代路径选项

• 在配置了多条迭代路径的Azure DevOps项目中，使用官方Azure Python API创建新工作项时，若/fields/System.IterationPath字段设置为已存在的值（如RTC-ADS\PI28\Sprint 28-3），工作项可正常创建；如果填入尚未创建的迭代值（如RTC-ADS\PI27），则会创建失败，返回错误：

ERROR:root:Error creating ADS work item: TF401347: Invalid tree name given for work item -1, field 'System.IterationPath'.

• 手动在Azure项目设置中可创建PI27迭代，需要确认是否可通过Azure Python API自动完成新迭代值创建，已知REST接口存在对应能力，但不确定Python SDK是否支持该操作。
• 自行尝试编写POST请求代码新增迭代路径，代码如下：

pat = CONFIG.personal_access_token
authorization = str(base64.b64encode(bytes(':'+pat, 'ascii')), 'ascii')

headers = {
    'Accept': 'application/json',
    'Authorization': 'Basic '+authorization
}

response = requests.post(
    url="https://dev.azure.com/ADSP-Org-A03/RTC-ADS/_apis/work/teamsettings/iterations?api-version=6.0&iteration=apple&startDate=2021-01-01&endDate=2021-01-11", 
    headers=headers
)

print(response.text)

执行后返回参数为空的错误：

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

初步判断为请求格式有误，但未找到可参考的有效实现示例，需要明确正确实现方式。

• 接口功能认知有误：/work/teamsettings/iterations接口的作用是将项目中已存在的迭代节点关联到指定团队，本身不具备创建全新迭代路径节点的能力。
• 请求传参方式错误：该接口要求迭代参数放在JSON格式的请求体中传递，将参数拼接在URL查询字符串中时，服务端无法读取到iteration参数，因此返回参数为空的错误。
• 全新的迭代路径属于项目分类节点，需要调用分类节点相关接口完成创建，创建完成后才能在工作项的System.IterationPath字段中引用，也可根据需要关联到对应团队。

方式1：直接调用REST接口实现 #

首先需要在请求头中增加Content-Type: application/json声明，将参数放在请求体中传递。

1. 创建全新项目级迭代节点
   调用分类节点创建接口，可直接创建不存在的迭代路径，支持配置迭代的起止时间，示例代码：

   import requests
   import base64
   
   pat = CONFIG.personal_access_token
   authorization = str(base64.b64encode(bytes(':'+pat, 'ascii')), 'ascii')
   
   headers = {
       'Accept': 'application/json',
       'Authorization': 'Basic '+authorization,
       'Content-Type': 'application/json'
   }
   
   # 请求体定义迭代属性
   request_body = {
       "name": "PI27",
       "attributes": {
           "startDate": "2024-01-01T00:00:00Z",
           "finishDate": "2024-03-31T00:00:00Z"
       }
   }
   
   # 根路径创建PI27迭代，如果要创建PI27下的子Sprint，可在URL的iterations后追加/PI27，请求体name填对应Sprint名称即可
   response = requests.post(
       url="https://dev.azure.com/ADSP-Org-A03/RTC-ADS/_apis/wit/classificationnodes/iterations?api-version=6.0",
       headers=headers,
       json=request_body
   )
   print(response.json())
   

2. （可选）将创建好的迭代关联到指定团队
   如果需要让迭代在指定团队的迭代列表中展示，可调用团队迭代关联接口，传入上一步返回的迭代节点ID即可：

   team_iteration_body = {
       "id": "上一步创建返回的迭代节点ID"
   }
   # URL中替换为实际的团队名称
   response = requests.post(
       url="https://dev.azure.com/ADSP-Org-A03/RTC-ADS/{替换为实际团队名}/_apis/work/teamsettings/iterations?api-version=6.0",
       headers=headers,
       json=team_iteration_body
   )
   

完成上述操作后，创建工作项时即可直接将System.IterationPath设置为新创建的迭代路径，不会再报树名无效错误。

方式2：通过官方Azure Python SDK实现 #

安装SDK包后，可直接通过工作项跟踪客户端完成迭代创建，无需手动构造HTTP请求，示例代码：

from azure.devops.connection import Connection
from msrest.authentication import BasicAuthentication
from azure.devops.v6_0.work_item_tracking.models import WorkItemClassificationNode

pat = CONFIG.personal_access_token
org_url = "https://dev.azure.com/ADSP-Org-A03"
credentials = BasicAuthentication('', pat)
connection = Connection(base_url=org_url, creds=credentials)
wit_client = connection.clients.get_work_item_tracking_client()

# 定义待创建的迭代属性
new_iteration = WorkItemClassificationNode(
    name="PI27",
    attributes={
        "startDate": "2024-01-01T00:00:00Z",
        "finishDate": "2024-03-31T00:00:00Z"
    }
)
# structure_type传"Iterations"表示创建迭代节点，传"Areas"可创建区域路径节点
created_iteration = wit_client.create_or_update_classification_node(
    new_iteration,
    project="RTC-ADS",
    structure_type="Iterations"
)

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