如何通过Azure DevOps REST API添加/更新环境安全用户权限

通过PowerShell调用REST API创建Azure DevOps环境时，需要同步为用户配置环境访问权限。
手动在页面操作时抓包得到的接口信息：

• 请求地址：

https://dev.azure.com/{org}/_apis/securityroles/scopes/distributedtask.environmentreferencerole/roleassignments/resources/{project_id}_{env_id}

• 请求方法：PUT
• 抓包看到的请求体：

[{userId: "{id_of_user}", roleName: "Administrator"}]

编写的PowerShell调用代码执行后返回{"count":0,"value":{}}，权限未配置成功。
原代码：

# other code
...
$body = @(
  @{ 'userId' = '{id_of_user}'; 'roleName': 'Administrator' }
) | ConvertTo-Json
Invoke-RestMethod -Uri $uri -Method Put -Body $body -ContentType "application/json" -Headers $header

返回空结果是三个高频错误导致的，按优先级排查：

1. 缺失API版本参数
   Azure DevOps所有REST API必须显式带api-version查询参数，不带会路由到旧版不兼容接口，直接返回空结果。
2. JSON序列化结构异常
   ConvertTo-Json默认序列化深度为2，嵌套数组/对象容易被截断；另外原代码写哈希表时roleName后用了冒号分隔，虽然高版本PowerShell能兼容，但低版本会解析错误，统一用等号分隔键值对更稳妥，序列化时显式指定-Depth 10保证结构完整。
3. 参数格式错误

• URL里的资源段必须是{项目ID}_{环境ID}格式，两个ID中间是下划线，不能写错分隔符；
• userId必须是用户在Azure AD/DevOps组织内的对象ID（GUID格式），不能传邮箱、UPN或者用户名；
• 鉴权用的PAT需要勾选Environment (Read & manage)权限范围，否则接口不会报错但不会写入权限。

正确可运行的代码示例：

# 替换为实际的组织名、项目ID、环境ID、用户ID
$orgName = "your-org-name"
$projectId = "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
$envId = "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
$userId = "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# 拼接URL，必须带上api-version参数
$uri = "https://dev.azure.com/$orgName/_apis/securityroles/scopes/distributedtask.environmentreferencerole/roleassignments/resources/${projectId}_${envId}?api-version=7.1-preview.1"

# 构造请求体，哈希表键值统一用等号分隔
$bodyPayload = @(
    @{
        userId   = $userId
        roleName = "Administrator" # 合法角色值：Administrator、User、Reader
    }
)

# 序列化JSON，指定深度避免结构截断
$body = $bodyPayload | ConvertTo-Json -Depth 10

# 发送请求，ContentType带utf-8编码避免中文/特殊字符乱码
$response = Invoke-RestMethod -Uri $uri -Method Put -Body $body -ContentType "application/json; charset=utf-8" -Headers $header

校验点 #

调用成功后返回结果的count字段值会大于等于1，value数组中会列出所有已配置的角色分配条目，包含刚添加的用户权限记录。如果还是返回空，先打印$body变量确认序列化后的JSON结构是标准格式，所有键都带双引号，没有缺失字段。

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