如何用PowerShell批量将CSV用户添加至Azure DevOps组及排错

问题排查与核心修正 #

1. API端点错误（导致「Page Not Found」的主要原因） #

原脚本中Add-UserToGroup函数的请求端点错误，groupentitlements用于管理组权限分配，而非添加组成员。需替换为Graph API的组成员管理端点：

$url = "$apiUrl/graph/groups/$groupDescriptor/members?api-version=6.0-preview.1"

同时请求体的参数名需从principalDescriptor改为descriptor，匹配API要求。

2. PAT权限验证 #

确保你的个人访问令牌（PAT）拥有以下权限：

• Graph: Read & Write
• User Profile: Read & Write
• Identity: Read & Write
  创建PAT时，在「Scopes」中勾选上述权限，范围需覆盖整个组织。

3. CSV路径问题 #

原脚本中Resolve-Path "/ test.csv"包含多余空格，会导致文件查找失败，修正为：

$csvFilePath = Resolve-Path "test.csv"
# 或直接使用绝对路径：$csvFilePath = "C:\your-path\test.csv"

修正后的完整脚本 #

# Azure DevOps组织信息与PAT
$organization = "xyz"
$personalAccessToken = "xyz"
$apiUrl = "https://vsaex.dev.azure.com/$organization/_apis"

# 目标组名称
$groupName = "xyz"

# CSV文件路径（确保无多余空格）
$csvFilePath = Resolve-Path "test.csv"

# 生成认证头
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$($personalAccessToken)"))
$headers = @{
    Authorization = "Basic $base64AuthInfo"
}

# 添加用户到组的函数（修正API端点与请求体）
function Add-UserToGroup {
    param (
        [string]$userDescriptor,
        [string]$groupDescriptor
    )

    $body = @{ 
        descriptor = $userDescriptor 
    } | ConvertTo-Json
    $url = "$apiUrl/graph/groups/$groupDescriptor/members?api-version=6.0-preview.1"

    try {
        $response = Invoke-RestMethod -Uri $url -Method Post -Body $body -Headers $headers -ContentType "application/json"
        return $response
    }
    catch {
        Write-Host "添加用户失败: $_"
    }
}

# 获取目标组的描述符
$groupsUrl = "$apiUrl/graph/groups?api-version=6.0-preview.1"
try {
    $groups = Invoke-RestMethod -Uri $groupsUrl -Method Get -Headers $headers
    $group = $groups.value | Where-Object { $_.principalName -eq $groupName }
    if (-not $group) {
        Write-Host "未找到组 '$groupName'"
        exit 1
    }
    $groupDescriptor = $group.descriptor
}
catch {
    Write-Host "获取组列表失败: $_"
    exit 1
}

# 导入CSV用户列表
try {
    $users = Import-Csv -Path $csvFilePath
}
catch {
    Write-Host "导入CSV文件失败: $_"
    exit 1
}

# 批量添加用户到组
foreach ($user in $users) {
    $userEmail = $user.UserName
    $userDescriptorUrl = "$apiUrl/graph/users?api-version=6.0-preview.1&subjectTypes=user&mailAddress=$userEmail"
    try {
        $userDescriptorObject = Invoke-RestMethod -Uri $userDescriptorUrl -Method Get -Headers $headers
        $userDescriptor = $userDescriptorObject.value.descriptor

        if ($userDescriptor) {
            Add-UserToGroup -userDescriptor $userDescriptor -groupDescriptor $groupDescriptor
            Write-Host "已将用户 ($userEmail) 添加到组 ($groupName)"
        } else {
            Write-Host "未找到用户 ($userEmail) 的描述符"
        }
    }
    catch {
        Write-Host "处理用户 $userEmail 失败: $_"
    }
}

额外注意事项 #

• CSV文件需包含UserName列，每行填写用户的邮箱地址。
• 若用户未在Azure DevOps组织中存在，需先通过门户或API邀请用户加入，否则无法获取用户描述符。
• 建议先测试单个用户添加流程，确认无误后再执行批量操作。

内容的提问来源于stack exchange，提问作者My ADO Obsession