List transitiveRoleAssignment

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

Obtener la lista de objetos unifiedRoleAssignment directos y transitivos de una entidad de seguridad específica. Por ejemplo, si se asigna a un usuario una función de Microsoft Entra mediante la pertenencia a grupos, la asignación de funciones es transitiva y esta solicitud mostrará el identificador del grupo como principalId. Los resultados también se pueden filtrar por roleDefinitionId y directoryScopeId. Solo se admite para el proveedor de directorio (Microsoft Entra ID).

Para obtener más información, consulte Usar grupos de Microsoft Entra para administrar las asignaciones de roles.

Nota:

Esta solicitud podría tener retrasos de replicación para las asignaciones de roles que se crearon, actualizaron o eliminaron recientemente. Obtenga más información en Diseño para lograr coherencia final para Microsoft Entra.

Esta API está disponible en las siguientes implementaciones en la nube nacional.

Servicio global Administración pública de EE. UU. Gobierno de EE. UU. L5 (DOD) China operado por 21Vianet

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use uno o varios permisos con privilegios más altos solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) RoleManagement.Read.Directory Directory.Read.All, Directory.ReadWrite.All, RoleManagement.ReadWrite.Directory
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación RoleManagement.Read.Directory Directory.Read.All, Directory.ReadWrite.All, RoleManagement.ReadWrite.Directory

Importante

Para el acceso delegado con cuentas profesionales o educativas, el usuario que ha iniciado sesión debe tener asignado un rol compatible de Microsoft Entra o un rol personalizado que conceda los permisos necesarios para esta operación. Esta operación admite los siguientes roles integrados, que proporcionan solo el privilegio mínimo necesario:

  • Lectores de directorios
  • Lector global
  • Administrador de roles con privilegios

Solicitud HTTP

Para enumerar las asignaciones de roles transitivos de un proveedor de directorio:

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

Parámetros de consulta

Este método requiere que el $filter parámetro de consulta OData (eq) limite las asignaciones de roles transitivos a una entidad de seguridad. Puede limitar el ámbito de la solicitud expandiendo el filtro a otras propiedades compatibles. Este método también admite los $count parámetros de consulta and $select OData para ayudar a personalizar la respuesta. Para obtener información general, vea Parámetros de consulta OData.

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio. Obtenga más información sobre autenticación y autorización.
ConsistencyLevel eventual. Este encabezado, $count, y $filter son necesarios. Para obtener más información sobre el uso de ConsistencyLevel, $count, y $filter, consulte Funcionalidades avanzadas de consulta en objetos de directorio.

Cuerpo de la solicitud

No proporcione un cuerpo de solicitud para este método.

Respuesta

Si tiene éxito, este método devuelve un 200 OK código de respuesta y una colección de objetos unifiedRoleAssignment en el cuerpo de la respuesta.

Si la solicitud no incluye el encabezado ConsistencyLevel establecido en eventual, este método devuelve 404 Not Found el código de respuesta.

Ejemplos

Para obtener los ejemplos de esta sección, considere el siguiente escenario de asignación de roles. Un usuario llamado Alice tiene asignaciones de roles directas y transitivas de la siguiente manera:

Usuario Group Role Ámbito Identificador de asignación de roles
Alicia
2c7936bc-3517-40f3-8eda-4806637b6516
Administrador de usuarios
fe930be7-5e62-47db-91af-98c3a49a38b1
Tenant RA1
857708a7-b5e0-44f9-bfd7-53531d72a739
G1
ae2fc327-4c71-48ed-b6ca-f48632186510
(Alice es miembro)
Administrador de usuarios
fe930be7-5e62-47db-91af-98c3a49a38b1
Tenant RA2
8a021d5f-7351-4713-aab4-b088504d476e
G2
6ffb34b8-5e6d-4727-a7f9-93245e7f6ea8
(Alice es miembro)
Administrador del servicio de asistencia
729827e3-9c14-49f7-bb1b-9608f156bbb8
Unidad administrativa (AU1)
26e79164-0c5c-4281-8c5b-be7bc7809fb2
RA3
6cc86637-13c8-473f-afdc-e0e65c9734d2
  • Alice tiene asignado el rol de administrador de usuarios directamente en el ámbito del inquilino con la asignación de roles RA1.
  • Alice es miembro de un grupo G1 y G1 tiene asignado el rol de administrador de usuarios en el ámbito del espacio empresarial con la asignación de roles RA2.
  • Alice también es miembro del grupo G2 y G2 tiene asignado el rol de administrador del departamento de soporte técnico en un ámbito AU1 de la unidad administrativa con la asignación de roles RA3.

Ejemplo 1: Obtener asignaciones de roles directas y transitivas de una entidad de seguridad

Solicitud

En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere que el encabezado ConsistencyLevel se establezca en eventual y los parámetros de $count=true consulta y $filter . Para obtener más información sobre el uso de ConsistencyLevel, $count, y $filter, consulte Funcionalidades avanzadas de consulta en objetos de directorio.

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

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad. Se devolverán todas las propiedades de una llamada real.

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"
        }
    ]
}

Ejemplo 2: Obtener asignaciones directas y transitivas de una entidad de seguridad, pero solo definiciones de roles específicos

Solicitud

En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere que el encabezado ConsistencyLevel se establezca en eventual y los parámetros de $count=true consulta y $filter . Para obtener más información sobre el uso de ConsistencyLevel, $count, y $filter, consulte Funcionalidades avanzadas de consulta en objetos de directorio.

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

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad. Se devolverán todas las propiedades de una llamada real.

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"
        }
    ]
}

Ejemplo 3: Obtener asignaciones de roles directas y transitivas de una entidad de seguridad, pero solo en el ámbito de la unidad administrativa

Solicitud

En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere que el encabezado ConsistencyLevel se establezca en eventual y los parámetros de $count=true consulta y $filter . Para obtener más información sobre el uso de ConsistencyLevel, $count, y $filter, consulte Funcionalidades avanzadas de consulta en objetos de directorio.

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

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad. Se devolverán todas las propiedades de una llamada real.

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"
        }
    ]
}