通过PowerShell调用Graph API创建Entra角色时遇JSON格式错误

错误核心原因 #

这个错误是因为你传入的JSON中，某个要求数组类型的字段被传成了单个值（PrimitiveValue）。Graph API创建自定义Entra角色时，rolePermissions.allowedResourceActions、resourceScopes等字段必须是数组格式，但你的PSCustomObject定义中可能把这些字段写成了单个字符串，导致序列化后的JSON不符合API要求。

正确实现代码 #

1. 构造符合类型要求的角色定义对象 #

确保数组类型的字段用@()包裹：

# 构造合规的自定义角色对象
$roleDefinition = [PSCustomObject]@{
    displayName = "自定义Entra测试角色"
    description = "拥有目录读取权限的自定义角色"
    rolePermissions = @(
        [PSCustomObject]@{
            allowedResourceActions = @("Microsoft.Authorization/*/read") # 必须用@()包裹成数组
            condition = $null # 可选字段，若使用需注意格式
        }
    )
    resourceScopes = @("/") # 资源范围必须是数组类型
    isEnabled = $true
}

2. 正确序列化JSON #

PowerShell默认ConvertTo-Json的深度是2，嵌套结构需指定足够的Depth避免序列化截断：

$jsonBody = $roleDefinition | ConvertTo-Json -Depth 10

3. 调用Graph API接口 #

必须指定Content-Type为application/json：

$token = "你的有效访问令牌"
$uri = "https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions"

Invoke-RestMethod -Uri $uri -Method Post -Headers @{Authorization = "Bearer $token"} -Body $jsonBody -ContentType "application/json"

关键排查点 #

• 直接输出$jsonBody查看序列化结果，确认allowedResourceActions、resourceScopes等字段是数组格式（如["Microsoft.Authorization/*/read"]），而非单个字符串
• 核对官方文档，确认所有必填字段的类型，尤其是rolePermissions内部的嵌套数组字段
• 即使只有一条权限规则，rolePermissions本身也必须用@()包裹成数组

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