Azure DevOps Agent能力获取脚本报错修复及相关方案咨询

报错根源是脚本冗余调用了Agent详情API，且存在API版本不匹配风险。以下是两种修复方案：

最优修复方案（减少API请求，彻底避免报错） #

获取Agent列表的API已直接返回systemCapabilities属性，无需额外调用详情接口。修改后的完整脚本如下：

# 定义变量
$organization = "xxx"
$pat = "xxxxx"
$outputCsv = "agents_applications_$(Get-Date -Format 'yyyyMMdd_HHmmss').csv"

# Base64编码PAT
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$($pat)"))

# 获取所有Agent池
$poolsUrl = "https://dev.azure.com/$organization/_apis/distributedtask/pools?api-version=7.1"
$poolsResponse = Invoke-RestMethod -Uri $poolsUrl -Method Get -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)}

# 初始化CSV数据数组
$csvData = @()

# 遍历每个Agent池，获取Agent及能力信息
$poolsResponse.value | ForEach-Object {
    $poolName = $_.name
    $poolId = $_.id

    # 获取当前池内所有Agent（包含systemCapabilities）
    $agentsUrl = "https://dev.azure.com/$organization/_apis/distributedtask/pools/$poolId/agents?api-version=7.1"
    $agentsResponse = Invoke-RestMethod -Uri $agentsUrl -Method Get -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)}

    # 提取Agent的能力信息
    $agentsResponse.value | ForEach-Object {
        $agentName = $_.name
        if ($_.systemCapabilities) {
            $_.systemCapabilities.GetEnumerator() | ForEach-Object {
                $csvData += [PSCustomObject]@{
                    AgentPoolName = $poolName
                    AgentName     = $agentName
                    Application   = $_.Key
                    InstalledVersion = $_.Value
                }
            }
        }
    }
}

# 导出为CSV文件
$csvData | Export-Csv -Path $outputCsv -NoTypeInformation
Write-Output "数据已写入文件：$outputCsv"

若坚持使用Agent详情API的修复方案 #

如果必须单独调用详情接口，需修正两个问题：

• 统一API版本：将agentDetailsUrl的API版本改为与其他接口一致的7.1
• 增加空值判断：跳过ID为空的Agent，避免URL构造错误
  修改后的对应代码段：

$agentsResponse.value | ForEach-Object {
    $agentId = $_.id
    $agentName = $_.name

    # 跳过ID为空的Agent
    if ([string]::IsNullOrEmpty($agentId)) {
        Write-Warning "跳过池[$poolName]中ID为空的Agent"
        return
    }

    $agentDetailsUrl = "https://dev.azure.com/$organization/_apis/distributedtask/pools/$poolId/agents/$agentId?api-version=7.1"
    $agentDetailsResponse = Invoke-RestMethod -Uri $agentDetailsUrl -Method Get -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)}

    $agentDetailsResponse.systemCapabilities.GetEnumerator() | ForEach-Object {
        $csvData += [PSCustomObject]@{
            AgentPoolName = $poolName
            AgentName     = $agentName
            Application   = $_.Key
            InstalledVersion = $_.Value
        }
    }
}

方法1：使用Azure DevOps CLI直接获取Agent能力 #

无需复杂脚本，用CLI快速导出Agent能力到CSV：

1. 登录Azure DevOps CLI：

   az devops login --organization https://dev.azure.com/{你的组织名}
   

2. 获取所有Agent的能力并导出：

   az devops pool agent list --pool-id all --include-capabilities --output json | ConvertFrom-Json | ForEach-Object {
       $poolName = $_.pool.name
       $_.systemCapabilities.GetEnumerator() | ForEach-Object {
           [PSCustomObject]@{
               AgentPoolName = $poolName
               AgentName     = $_.name
               Application   = $_.Key
               InstalledVersion = $_.Value
           }
       }
   } | Export-Csv -Path "agent_capabilities.csv" -NoTypeInformation
   

方法2：扫描流水线获取所需Agent能力（注意：非Agent实际安装应用） #

该方法仅能获取流水线定义中要求Agent具备的能力（即Demands），无法反映Agent实际安装的软件：

az pipelines list --organization https://dev.azure.com/{你的组织名} --project {你的项目名} --output json | ConvertFrom-Json | ForEach-Object {
    $pipelineName = $_.name
    az pipelines show --id $_.id --output json | ConvertFrom-Json | Select-Object -ExpandProperty demands | ForEach-Object {
        [PSCustomObject]@{
            PipelineName = $pipelineName
            RequiredCapability = $_
        }
    }
} | Export-Csv -Path "pipeline_demands.csv" -NoTypeInformation

方法3：使用Azure DevOps PowerShell模块 #

若之前尝试模块失败，确保正确安装并使用：

1. 安装模块：

   Install-Module -Name Az.DevOps -Force -AllowClobber
   

2. 登录并获取Agent能力：

   Connect-AzDevOps -Organization https://dev.azure.com/{你的组织名}
   Get-AzDevOpsAgentPool | ForEach-Object {
       $pool = $_
       Get-AzDevOpsAgent -PoolId $pool.Id | ForEach-Object {
           $agent = $_
           $agent.SystemCapabilities.GetEnumerator() | ForEach-Object {
               [PSCustomObject]@{
                   AgentPoolName = $pool.Name
                   AgentName     = $agent.Name
                   Application   = $_.Key
                   InstalledVersion = $_.Value
               }
           }
       }
   } | Export-Csv -Path "agent_capabilities.csv" -NoTypeInformation
   

内容的提问来源于stack exchange，提问作者GUNDRAJU KRUPA VANI