通过

列出 transitiveRoleAssignment

  • 项目

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

获取特定主体的直接和可传递 的 unifiedRoleAssignment 对象列表。 例如，如果通过组成员身份为用户分配了Microsoft Entra角色，则角色分配是可传递的，并且此请求会将组的 ID 列为 principalId。 还可以按 roleDefinitionId 和 directoryScopeId 筛选结果。 仅目录 (Microsoft Entra ID) 提供程序支持。

有关详细信息，请参阅使用 Microsoft Entra 组管理角色分配。

注意

对于最近创建、更新或删除的角色分配，此请求可能存在复制延迟。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） RoleManagement.Read.Directory Directory.Read.All、Directory.ReadWrite.All、RoleManagement.ReadWrite.Directory
委派（个人 Microsoft 帐户） 不支持。 不支持。
应用程序 RoleManagement.Read.Directory Directory.Read.All、Directory.ReadWrite.All、RoleManagement.ReadWrite.Directory

重要

在具有工作或学校帐户的委托方案中，必须为登录用户分配受支持的Microsoft Entra角色或具有支持的角色权限的自定义角色。 此操作支持以下最低特权角色：

  • 目录读取器
  • 全局读取者
  • 特权角色管理员

HTTP 请求

列出目录提供程序的可传递角色分配：

GET /roleManagement/directory/transitiveRoleAssignments?$filter=principalId eq '{principalId}'

查询参数

此方法需要 $filter (eq) OData 查询参数，以将可传递角色分配范围限定为主体。 可以通过将筛选器扩展到其他受支持的属性来缩小请求的范围。 此方法还支持 $count 和 $select OData 查询参数来帮助自定义响应。 若要了解一般信息，请参阅 OData 查询参数。

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
ConsistencyLevel 最终。 此标头 $count、 和 $filter 是必需的。 有关使用 ConsistencyLevel、 和 $filter的详细信息，$count请参阅目录对象上的高级查询功能。

请求正文

请勿提供此方法的请求正文。

响应

如果成功，此方法在响应正文中返回响应 200 OK 代码和 unifiedRoleAssignment 对象的集合。

如果请求不包括设置为 eventual的 ConsistencyLevel 标头，此方法返回404 Not Found响应代码。

示例

对于本部分中的示例，请考虑以下角色分配方案。 名为 Alice 的用户具有直接和可传递角色分配，如下所示：

用户 组 Role 范围 角色分配 ID
爱丽丝
2c7936bc-3517-40f3-8eda-4806637b6516		 用户管理员
fe930be7-5e62-47db-91af-98c3a49a38b1		 Tenant RA1
857708a7-b5e0-44f9-bfd7-53531d72a739
G1
ae2fc327-4c71-48ed-b6ca-f48632186510
(Alice 是成员) 		用户管理员
fe930be7-5e62-47db-91af-98c3a49a38b1		 Tenant RA2
8a021d5f-7351-4713-aab4-b088504d476e
G2
6ffb34b8-5e6d-4727-a7f9-93245e7f6ea8
(Alice 是成员) 		帮助台管理员
729827e3-9c14-49f7-bb1b-9608f156bbb8		 管理单元 (AU1)
26e79164-0c5c-4281-8c5b-be7bc7809fb2		 RA3
6cc86637-13c8-473f-afdc-e0e65c9734d2
  • 使用角色分配 RA1 直接在租户范围内为 Alice 分配用户管理员角色。
  • Alice 是组 G1 的成员，G1 具有角色分配 RA2 的租户范围内的用户管理员角色。
  • Alice 也是组 G2 的成员，G2 在具有角色分配 RA3 的管理单元 AU1 范围内分配了支持人员管理员角色。

示例 1：获取主体的直接和可传递角色分配

请求

以下示例显示了一个请求。 此请求需要 将 ConsistencyLevel 标头设置为 eventual 和 $count=true 和 $filter 查询参数。 有关使用 ConsistencyLevel、 和 $filter的详细信息，$count请参阅目录对象上的高级查询功能。

GET https://graph.microsoft.com/beta/roleManagement/directory/transitiveRoleAssignments?$count=true&$filter=principalId eq '2c7936bc-3517-40f3-8eda-4806637b6516'
ConsistencyLevel: eventual

响应

以下示例显示了相应的响应。

注意：为了提高可读性，可能缩短了此处显示的响应对象。 所有属性都将通过实际调用返回。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/directory/transitiveRoleAssignments",
    "value": [
        {
            "id": "857708a7-b5e0-44f9-bfd7-53531d72a739",
            "principalId": "2c7936bc-3517-40f3-8eda-4806637b6516",
            "directoryScopeId": "/",
            "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1"
        },
        {
            "id": "8a021d5f-7351-4713-aab4-b088504d476e",
            "principalId": "ae2fc327-4c71-48ed-b6ca-f48632186510",
            "directoryScopeId": "/",
            "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1"
        },
        {
            "id": "6cc86637-13c8-473f-afdc-e0e65c9734d2",
            "principalId": "6ffb34b8-5e6d-4727-a7f9-93245e7f6ea8",
            "directoryScopeId": "/administrativeUnits/26e79164-0c5c-4281-8c5b-be7bc7809fb2",
            "roleDefinitionId": "729827e3-9c14-49f7-bb1b-9608f156bbb8"
        }
    ]
}

示例 2：获取主体的直接和可传递分配，但仅获取特定角色定义

请求

以下示例显示了一个请求。 此请求需要 将 ConsistencyLevel 标头设置为 eventual 和 $count=true 和 $filter 查询参数。 有关使用 ConsistencyLevel、 和 $filter的详细信息，$count请参阅目录对象上的高级查询功能。

GET https://graph.microsoft.com/beta/roleManagement/directory/transitiveRoleAssignments?$count=true&$filter=principalId eq '2c7936bc-3517-40f3-8eda-4806637b6516' and roleDefinitionId eq 'fe930be7-5e62-47db-91af-98c3a49a38b1'
ConsistencyLevel: eventual

响应

以下示例显示了相应的响应。

注意：为了提高可读性，可能缩短了此处显示的响应对象。 所有属性都将通过实际调用返回。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/directory/transitiveRoleAssignments",
    "value": [
        {
            "id": "857708a7-b5e0-44f9-bfd7-53531d72a739",
            "principalId": "2c7936bc-3517-40f3-8eda-4806637b6516",
            "directoryScopeId": "/",
            "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1"
        },
        {
            "id": "8a021d5f-7351-4713-aab4-b088504d476e",
            "principalId": "6ffb34b8-5e6d-4727-a7f9-93245e7f6ea8",
            "directoryScopeId": "/",
            "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1"
        }
    ]
}

示例 3：获取主体的直接和可传递角色分配，但仅限管理单元范围

请求

以下示例显示了一个请求。 此请求需要 将 ConsistencyLevel 标头设置为 eventual 和 $count=true 和 $filter 查询参数。 有关使用 ConsistencyLevel、 和 $filter的详细信息，$count请参阅目录对象上的高级查询功能。

GET https://graph.microsoft.com/beta/roleManagement/directory/transitiveRoleAssignments?$count=true&$filter=principalId eq '2c7936bc-3517-40f3-8eda-4806637b6516' and directoryScopeId eq '/administrativeUnits/26e79164-0c5c-4281-8c5b-be7bc7809fb2'
ConsistencyLevel: eventual

响应

以下示例显示了相应的响应。

注意：为了提高可读性，可能缩短了此处显示的响应对象。 所有属性都将通过实际调用返回。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/directory/transitiveRoleAssignments",
    "value": [
        {
            "id": "6cc86637-13c8-473f-afdc-e0e65c9734d2",
            "principalId": "6ffb34b8-5e6d-4727-a7f9-93245e7f6ea8",
            "directoryScopeId": "/administrativeUnits/26e79164-0c5c-4281-8c5b-be7bc7809fb2",
            "roleDefinitionId": "729827e3-9c14-49f7-bb1b-9608f156bbb8"
        }
    ]
}