Compartir a través de

unifiedRoleDefinition: assignedPrincipals

  • Artículo

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.

Obtenga la lista de entidades de seguridad (usuarios, grupos y entidades de servicio) que están asignadas a un rol específico para distintos ámbitos de forma directa o transitiva. Puede usar el parámetro de $count consulta para obtener también el recuento.

Esta API solo se admite para el proveedor de directorios (Id. de Microsoft Entra).

Para enumerar las asignaciones de roles directas y transitivas para una entidad de seguridad específica, use la API List transitiveRoleAssignments .

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet
✅ ✅ ✅ ✅

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores 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, RoleManagement.ReadWrite.Directory
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación RoleManagement.Read.Directory Directory.Read.All, RoleManagement.ReadWrite.Directory

En escenarios delegados con cuentas profesionales o educativas, al usuario que ha iniciado sesión se le debe asignar un rol de Microsoft Entra compatible o un rol personalizado con uno de los siguientes permisos de rol:

  • microsoft.directory/roleDefinitions/standard/read (con privilegios mínimos)
  • microsoft.directory/roleDefinitions/allProperties/read
  • microsoft.directory/roleDefinitions/allProperties/allTasks

Los roles con menos privilegios admitidos para esta operación son los siguientes, en el orden de menos a más privilegios:

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

Importante

Cuando una aplicación consulta una relación que devuelve una colección de tipos directoryObject , si no tiene permiso para leer un tipo de recurso determinado, se devuelven miembros de ese tipo pero con información limitada. Por ejemplo, solo se devuelve la propiedad @odata.type para el tipo de objeto y el identificador , mientras que otras propiedades se indican como null. Con este comportamiento, las aplicaciones pueden solicitar los permisos con privilegios mínimos que necesitan, en lugar de depender del conjunto de directorios.*Permisos. Para información, consulte Información limitada devuelta para objetos de miembros inaccesibles.

Solicitud HTTP

GET /roleManagement/directory/roleDefinitions/{unifiedRoleDefinitionId}/assignedPrincipals(transitive=@transitive,directoryScopeType='@directoryScopeType',directoryScopeId='@directoryScopeId')

Parámetros de función

En la dirección URL de la solicitud, proporcione los siguientes parámetros de consulta con valores. La siguiente tabla muestra los parámetros que se pueden usar con esta función.

Parámetro Tipo Descripción
transitivo Booleano Indica si se deben incluir entidades de seguridad asignadas a través de la pertenencia a grupos (directa o transitiva). false de forma predeterminada.
directoryScopeType Cadena Ámbito del directorio para el que se van a obtener las entidades de seguridad asignadas. Los valores admitidos son tenant, administrativeUnity resource.
directoryScopeId Cadena Identificador del ámbito del directorio para el que se van a obtener las entidades de seguridad asignadas. De forma predeterminada, se tienen en cuenta todos los ámbitos.

También puede combinar todos los parámetros de función admitidos en una solicitud para obtener resultados detallados.

Ejemplo de patrones de consulta para directoryScopeType

Ámbito Consulta Compatible con
Todos los ámbitos /assignedPrincipals(transitive={true | false}) Todos los roles
Ámbito de inquilino /assignedPrincipals(directoryScopeType='tenant', transitive={true | false}) Todos los roles
Todos los ámbitos de unidad administrativa /assignedPrincipals(directoryScopeType='administrativeUnit', transitive={true | false}) Roles de directorio
Ámbito específico de la unidad administrativa /assignedPrincipals(directoryScopeType='administrativeUnit', directoryScopeId ='{roleDefinitionId | templateId}', transitive={true | false}) Roles de directorio
Todos los ámbitos de recursos /assignedPrincipals(directoryScopeType='resource', transitive={true | false}) Roles de directorio
Ámbito de recurso específico /assignedPrincipals(directoryScopeType='resource', directoryScopeId ='{roleDefinitionId | templateId}', transitive={true | false}) Roles de directorio

Parámetros de consulta opcionales

Este método admite los $countparámetros de consulta , $select, $filtery $orderby OData para ayudar a personalizar la respuesta. También puede filtrar por el tipo de objeto mediante la conversión de OData. Por ejemplo, /assignedPrincipals(transitive=false)/microsoft.graph.user y /assignedPrincipals(transitive=true)/microsoft.graph.servicePrincipal/$count. 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 la autenticación y la autorización.
ConsistencyLevel eventual. Obligatorio. Para obtener más información sobre el uso de ConsistencyLevel, vea Funcionalidades avanzadas de consulta en objetos de directorio.

Cuerpo de la solicitud

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

Respuesta

Si se ejecuta correctamente, esta función devuelve un 200 OK código de respuesta y una colección directoryObject en el cuerpo de la respuesta.

Ejemplos

Para ver los ejemplos de esta sección, tenga en cuenta el siguiente escenario de asignación de roles. Un usuario denominado User1 tiene asignaciones de roles directas y transitivas como se indica a continuación:

Usuario Group Role Ámbito
User1
6c62e70d-f5f5-4b9d-9eea-ed517ed9341f		 Rol 1 Ámbito1
User1
6c62e70d-f5f5-4b9d-9eea-ed517ed9341f		 Rol 1 Ámbito2
Grupo 1
86b38db7-6e8b-4ad2-b2aa-ced7f09486c1
(User1 es miembro)		 Rol 1 Ámbito1
Grupo 2
182351a6-d974-4d18-88ae-8a148da44cd2
(User1 es miembro)		 Rol 1 Ámbito1
Grupo 3
b93d5379-a464-4db5-b8e1-694910f1e11e
(User2 es miembro)
(User3 es miembro)		 Rol 1 Ámbito3
  • A User1 se le asigna el rol Role1 directamente en el ámbito scope1.
  • A User1 se le asigna el rol Role1 directamente en el ámbito scope2.
  • User1 es miembro del grupo Group1 y a Group1 se le asigna el rol Role1 en ámbito Scope1.
  • User1 es miembro del grupo Group2 y a Group2 se le asigna el rol Role1 en ámbito Scope1.
  • User2 es miembro del grupo Group3 y a Group3 se le asigna el rol Role1 en el ámbito Scope3.
  • User3 es miembro del grupo Group3 y a Group3 se le asigna el rol Role1 en el ámbito Scope3.

Ejemplo 1: Obtención de un recuento de entidades de seguridad asignadas directas y transitivas para todos los ámbitos

Solicitud

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals(transitive=true)/$count

Respuesta

La solicitud anterior devuelve un recuento de 6 que representa las siguientes asignaciones de roles:

  • Dos asignaciones de roles directos a User1 en Scope1 y Scope2
  • Dos asignaciones de roles transitivas a User1 a Group1 y Group2
  • Dos asignaciones de roles transitivas a User 2 y User3 a Group3.
HTTP/1.1 200 OK
Content-type: text/plain

6

En función del mismo escenario, en los ejemplos siguientes se muestran los recuentos que se devuelven para cada patrón de consulta:

Ejemplo Count
/assignedPrincipals(transitive=false)/$count 4
(User1, Group1, Group2, Group3)
/assignedPrincipals(transitive=false)/microsoft.graph.user/$count 1
(User1)
/assignedPrincipals(transitive=true)/microsoft.graph.user/$count 3
(User1, User2, User3)
/assignedPrincipals(transitive=false)/microsoft.graph.group/$count 3
(Group1, Group2, Group3)
/assignedPrincipals(transitive=true)/microsoft.graph.group/$count 3
(Group1, Group2, Group3)

Ejemplo 2: Obtención de entidades de seguridad asignadas directamente para un ámbito de unidad administrativa y un rol de directorio específicos

Solicitud

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals(directoryScopeType='administrativeUnit', directoryScopeId ='d0c2e067-9ae9-4dbf-a280-51a51c46f432')

Respuesta

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "value": [
    {
        "@odata.type": "#microsoft.graph.user",
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f"
    }
  ]
}

Ejemplo 3: Obtención de entidades de seguridad asignadas directamente para todos los ámbitos

Solicitud

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals

Respuesta

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "value": [
    {
        "@odata.type": "#microsoft.graph.user",
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f",
        "displayName": null,
        "userPrincipalName": null
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "86b38db7-6e8b-4ad2-b2aa-ced7f09486c1",
        "displayName": "Group1"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "182351a6-d974-4d18-88ae-8a148da44cd2",
        "displayName": "Group2"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "b93d5379-a464-4db5-b8e1-694910f1e11e",
        "displayName": "Group3"
    }
  ]
}

Ejemplo 4: Obtención de usuarios asignados directamente solo para un ámbito de todo el inquilino

Solicitud

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals(directoryScopeType='tenant')/microsoft.graph.user

Respuesta

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users",
  "value": [
    {
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f",
        "displayName": null,
        "userPrincipalName": null
    }
  ]
}

Ejemplo 5: Obtención de entidades de seguridad asignadas directamente y recuento insertado

En el ejemplo siguiente se obtienen las entidades de seguridad asignadas directamente y se muestra un recuento insertado.

Solicitud

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals?$count=true

Respuesta

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "@odata.count": 4,
  "value": [
    {
        "@odata.type": "#microsoft.graph.user",
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f",
        "displayName": null,
        "userPrincipalName": null
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "86b38db7-6e8b-4ad2-b2aa-ced7f09486c1",
        "displayName": "Group1"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "182351a6-d974-4d18-88ae-8a148da44cd2",
        "displayName": "Group2"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "b93d5379-a464-4db5-b8e1-694910f1e11e",
        "displayName": "Group3"
    }
  ]
}