通过Azure DevOps API和PowerShell迁移迭代时POST请求报错：必须为iteration参数提供值

我完全懂你现在的挫败感——能顺利拉取源ADO里的迭代列表，结果一到POST创建环节就卡在这个参数验证错误上，太闹心了。咱们一步步拆解问题，把这个坑填上。

首先，这个错误的核心原因很明确：你的POST请求体没有按照ADO API的要求，正确传递完整的迭代对象结构，或者请求的格式不对，导致ADO服务器识别不到你要创建的迭代参数。

下面是几个你需要重点排查和修正的点：

1. 确保请求体是符合要求的JSON对象 #

ADO的迭代创建API（针对_apis/wit/classificationnodes/Iterations端点）要求请求体必须是包含name（必填）以及可选属性（比如startDate、finishDate）的JSON对象，而不是简单的字符串。

举个正确的请求体示例：

# 构建迭代对象
$iterationPayload = @{
    name = "Sprint 2024-06"
    attributes = @{
        startDate = "2024-06-01T00:00:00Z"
        finishDate = "2024-06-14T00:00:00Z"
    }
}

# 转成JSON，注意Depth参数要足够大，避免嵌套结构被截断
$jsonBody = $iterationPayload | ConvertTo-Json -Depth 10

2. 不要漏掉Content-Type请求头 #

这是很多人踩的坑：如果你的请求头里没有指定Content-Type: application/json，ADO服务器会无法解析你发送的JSON体，直接判定你没传iteration参数。

修正后的请求头应该是这样：

$PAT = "你的ADO个人访问令牌"
$headers = @{
    Authorization = "Basic " + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$PAT"))
    "Content-Type" = "application/json"  # 这个必须加！
}

3. 确认目标API URL的正确性 #

如果是创建根级迭代，URL格式是：

https://dev.azure.com/{目标组织}/{目标项目}/_apis/wit/classificationnodes/Iterations?api-version=7.1-preview.2

如果是创建子迭代，需要把URL指向父迭代的节点，比如：

https://dev.azure.com/{目标组织}/{目标项目}/_apis/wit/classificationnodes/Iterations/父迭代名称?api-version=7.1-preview.2

建议用较新的API版本（比如7.1-preview.2），避免兼容性问题。

4. 完整的可参考脚本片段 #

把这些点整合起来，给你一个可复用的迁移脚本片段，你可以对照自己的代码调整：

# 配置基础参数
$sourceOrg = "你的源组织名称"
$sourceProj = "你的源项目名称"
$targetOrg = "你的目标组织名称"
$targetProj = "你的目标项目名称"
$personalAccessToken = "你的ADO个人访问令牌（需要Work Item Tracking读写权限）"

# 构建通用请求头
$requestHeaders = @{
    Authorization = "Basic " + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$personalAccessToken"))
    "Content-Type" = "application/json"
}

# 获取源项目的迭代列表
$sourceIterationsUrl = "https://dev.azure.com/$sourceOrg/$sourceProj/_apis/wit/classificationnodes/Iterations?api-version=7.1-preview.2&depth=2"
$sourceIterations = Invoke-RestMethod -Uri $sourceIterationsUrl -Headers $requestHeaders -Method Get

# 遍历迭代，逐个创建到目标项目
foreach ($iter in $sourceIterations.value) {
    # 确定目标URL：根迭代还是子迭代
    if ($iter.path -eq $iter.name) {
        # 根迭代
        $targetUrl = "https://dev.azure.com/$targetOrg/$targetProj/_apis/wit/classificationnodes/Iterations?api-version=7.1-preview.2"
    } else {
        # 子迭代，截取父路径
        $parentPath = $iter.path -replace "\\$($iter.name)", ""
        $targetUrl = "https://dev.azure.com/$targetOrg/$targetProj/_apis/wit/classificationnodes/Iterations/$parentPath?api-version=7.1-preview.2"
    }

    # 构建创建迭代的请求体
    $createBody = @{
        name = $iter.name
        attributes = @{
            startDate = $iter.attributes.startDate
            finishDate = $iter.attributes.finishDate
        }
    } | ConvertTo-Json -Depth 10

    try {
        $createResponse = Invoke-RestMethod -Uri $targetUrl -Headers $requestHeaders -Method Post -Body $createBody
        Write-Host "✅ 成功创建迭代：$($iter.name)"
    } catch {
        Write-Host "❌ 创建迭代 $($iter.name) 失败：$($_.Exception.Message)"
    }
}

最后再提醒几个容易忽略的细节：

• 你的PAT必须拥有目标项目的Work Item Tracking > 读写权限，不然可能会出现权限相关的隐性错误
• 用ConvertTo-Json时一定要加-Depth参数，默认深度是2，嵌套的attributes结构会被截断，导致参数不完整

备注：内容来源于stack exchange，提问作者USMC6072