如何通过Microsoft Graph API映射Azure AD PIM合格角色的用户/组名称

1. 选择Graph API端点 #

优先调用roleEligibilitySchedules端点获取所有PIM合格分配记录（包含当前及未来的分配），端点地址：

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleEligibilitySchedules

可通过$select参数精简返回字段，减少数据传输：

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleEligibilitySchedules?$select=principalId,roleDefinitionId,createdDateTime

如果只需要当前生效的合格分配，改用roleEligibilityScheduleInstances端点：

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleEligibilityScheduleInstances

2. 映射principalId到用户/组名称 #

返回结果中的principalId是用户或组的对象ID，需通过这个ID关联到对应的名称，推荐两种方式：

批量查询（高效处理大量数据） #

使用Graph API的$batch功能，一次性批量查询多个principalId的类型和名称，避免多次单独请求：
构造POST请求到https://graph.microsoft.com/v1.0/$batch，请求体示例：

{
  "requests": [
    {
      "id": "1",
      "method": "GET",
      "url": "/users/{principalId1}?$select=id,displayName"
    },
    {
      "id": "2",
      "method": "GET",
      "url": "/users/{principalId2}?$select=id,displayName"
    }
  ]
}

• 若某条请求返回200，说明是用户，直接提取displayName；
• 若返回404，再单独调用/groups/{principalId}查询组信息。

单个查询（适合少量数据） #

遍历每条合格分配记录，先尝试查询用户：

GET https://graph.microsoft.com/v1.0/users/{principalId}?$select=displayName

• 返回200则为用户，取displayName；
• 返回404则调用组查询接口：

GET https://graph.microsoft.com/v1.0/groups/{principalId}?$select=displayName

3. Python实现示例 #

假设已完成Graph API的身份验证并获取了有效access_token，示例代码如下：

import requests

# 替换为你的有效access token
access_token = "YOUR_ACCESS_TOKEN"
headers = {"Authorization": f"Bearer {access_token}"}

# 1. 获取所有PIM合格分配记录
eligibility_res = requests.get(
    "https://graph.microsoft.com/v1.0/roleManagement/directory/roleEligibilitySchedules?$select=principalId,roleDefinitionId",
    headers=headers
)
eligibility_schedules = eligibility_res.json().get("value", [])

# 2. 批量查询用户信息
batch_requests = []
for idx, schedule in enumerate(eligibility_schedules):
    batch_requests.append({
        "id": str(idx + 1),
        "method": "GET",
        "url": f"/users/{schedule['principalId']}?$select=id,displayName"
    })

batch_res = requests.post(
    "https://graph.microsoft.com/v1.0/$batch",
    headers=headers,
    json={"requests": batch_requests}
)
batch_results = batch_res.json().get("responses", [])

# 3. 处理结果，映射用户/组名称
final_assignments = []
for res, schedule in zip(batch_results, eligibility_schedules):
    principal_id = schedule["principalId"]
    if res["status"] == 200:
        # 是用户
        user_info = res["body"]
        final_assignments.append({
            "类型": "用户",
            "ID": principal_id,
            "名称": user_info["displayName"],
            "角色定义ID": schedule["roleDefinitionId"]
        })
    else:
        # 查询组
        group_res = requests.get(
            f"https://graph.microsoft.com/v1.0/groups/{principal_id}?$select=displayName",
            headers=headers
        )
        if group_res.status_code == 200:
            group_info = group_res.json()
            final_assignments.append({
                "类型": "组",
                "ID": principal_id,
                "名称": group_info["displayName"],
                "角色定义ID": schedule["roleDefinitionId"]
            })

# 输出结果
for item in final_assignments:
    print(f"{item['类型']}: {item['名称']} (ID: {item['ID']}) - 角色ID: {item['角色定义ID']}")

4. 可选：映射角色名称 #

如果需要把roleDefinitionId转换为可读的角色名称，可以将角色ID的查询加入批量请求，或者单独调用：

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions/{roleDefinitionId}?$select=displayName

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