Compartir a través de

Enumerar usuarios

Espacio de nombres: microsoft.graph

Recupere una lista de objetos user.

Nota: Esta solicitud puede tener retrasos de replicación para los usuarios que se crearon, actualizaron o eliminaron recientemente.

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
✅ ✅ ✅ ✅

Permisos

Se requiere uno de los siguientes permisos para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, vea Permisos.

Tipo de permiso Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa) User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegado (cuenta personal de Microsoft) No admitida.
Aplicación User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Los invitados no pueden llamar a esta API. Para obtener más información sobre los permisos para miembros e invitados, consulte ¿Cuáles son los permisos de usuario predeterminados en Microsoft Entra ID?

Permisos para escenarios específicos

  • User-Mail.ReadWrite.All es el permiso con privilegios mínimos para leer y escribir la propiedad otherMails; también permite leer algunas propiedades relacionadas con el identificador en el objeto de usuario.
  • User-PasswordProfile.ReadWrite.All es el permiso con privilegios mínimos para leer y escribir propiedades relacionadas con el restablecimiento de contraseña; también permite leer algunas propiedades relacionadas con el identificador en el objeto de usuario.
  • User-Phone.ReadWrite.All es el permiso con privilegios mínimos para leer y escribir las propiedades businessPhones y mobilePhone ; también permite leer algunas propiedades relacionadas con el identificador en el objeto de usuario.
  • User.EnableDisableAccount.All + User.Read.All es la combinación de permisos con privilegios mínimos para leer y escribir la propiedad accountEnabled .

Solicitud HTTP

GET /users

Parámetros de consulta opcionales

Este método admite los $countparámetros de consulta , $expand, $filter, $orderby$search, $selecty $top OData para ayudar a personalizar la respuesta. No se admite $skip. Los tamaños de página predeterminado y máximo son 100 y 999 objetos de usuario respectivamente, excepto cuando se especifica $select=signInActivity o $filter=signInActivity. Cuando signInActivity se selecciona o filtra, el tamaño máximo de página es 500. Algunas consultas solo se admiten cuando se usa el encabezado ConsistencyLevel establecido en eventual y $count. Para obtener más información, vea Funcionalidades avanzadas de consulta en objetos de directorio. Los parámetros $count y $search no están disponibles actualmente en espacios empresariales de Azure AD B2C.

De forma predeterminada, solo se devuelve un conjunto limitado de propiedades (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname y userPrincipalName). Para devolver un conjunto de propiedades alternativo, especifique el conjunto deseado de propiedades del usuario mediante el parámetro de consulta OData $select. Por ejemplo, para devolver displayName, givenName y postalCode, agregue lo siguiente a su consulta $select=displayName,givenName,postalCode.

Las propiedades de extensión también admiten parámetros de consulta como se indica a continuación:

Tipo de extensión Comentarios
onPremisesExtensionAttributes 1-15 Solo se devuelve con $select. Admite $filter (eq, ne y eq en valores null).
Extensiones de esquema Solo se devuelve con $select. Admite $filter (eq, ne y eq en valores null).
Extensiones abiertas Solo se devuelve con $expand, es decir, users?$expand=extensions.
Extensiones de directorio Solo se devuelve con $select. Admite $filter (eq, ne y eq en valores null).

Algunas propiedades no se pueden devolver dentro de una colección de usuarios. Las siguientes propiedades solo se admiten al recuperar un único usuario: aboutMe, birthday, hireDate, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, mailboxSettings.

Las siguientes propiedades no se admiten en cuentas personales de Microsoft y serán null: aboutMe, birthday, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, streetAddress.

Encabezados de solicitud

Encabezado Valor
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.
ConsistencyLevel eventual. Este encabezado y $count son necesarios cuando se usa $search,o en un uso específico de $filter. Para obtener más información sobre el uso de ConsistencyLevel y $count, 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, este método devuelve un código de respuesta 200 OK y la colección de objetos user en el cuerpo de la respuesta. Si se devuelve una colección de usuarios grande, puede usar la paginación en la aplicación.

Al intentar usar $select en la /users colección para recuperar propiedades que no se pueden devolver dentro de una colección de usuarios (por ejemplo, la solicitud ../users?$select=aboutMe), se devuelve un 501 Not Implemented código de error.

Ejemplos

Ejemplo 1: obtener todos los usuarios

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/v1.0/users

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.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
    "value": [
        {
            "businessPhones": [],
            "displayName": "Conf Room Adams",
            "givenName": null,
            "jobTitle": null,
            "mail": "Adams@contoso.com",
            "mobilePhone": null,
            "officeLocation": null,
            "preferredLanguage": null,
            "surname": null,
            "userPrincipalName": "Adams@contoso.com",
            "id": "6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0"
        },
        {
            "businessPhones": [
                "425-555-0100"
            ],
            "displayName": "MOD Administrator",
            "givenName": "MOD",
            "jobTitle": null,
            "mail": null,
            "mobilePhone": "425-555-0101",
            "officeLocation": null,
            "preferredLanguage": "en-US",
            "surname": "Administrator",
            "userPrincipalName": "admin@contoso.com",
            "id": "4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
        }
    ]
}

Ejemplo 2: obtener una cuenta de usuario con un nombre de inicio de sesión

Solicitud

En el ejemplo siguiente se muestra la solicitud.

Nota: al filtrar por issuerAssignedId, debe proporcionar tanto el emisor como el issuerAssignedId. Sin embargo, el valor del emisor se omitirá en determinados escenarios. Para obtener más información sobre el filtrado de identidades, consulte objectIdentity resource type (Tipo de recurso objectIdentity).

GET https://graph.microsoft.com/v1.0/users?$select=displayName,id&$filter=identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')

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.

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

{
  "value": [
    {
      "displayName": "John Smith",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
    }
  ]
}

Ejemplo 3: Obtener solo un recuento de usuarios

Solicitud

En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual porque $count está en la solicitud. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.

Nota: Los parámetros de consulta $count y $search actualmente no están disponibles en inquilinos de Azure AD B2C.

GET https://graph.microsoft.com/v1.0/users/$count
ConsistencyLevel: eventual

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 200 OK
Content-type: text/plain

893

Ejemplo 4: Usar $filter y $top para obtener un usuario con un nombre para mostrar que comience por "a", junto con un recuento de los objetos devueltos

Solicitud

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

Nota: Los parámetros de consulta $count y $search actualmente no están disponibles en inquilinos de Azure AD B2C.

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'a')&$orderby=displayName&$count=true&$top=1
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.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count":1,
  "value":[
    {
      "displayName":"a",
      "mail":"a@contoso.com",
      "mailNickname":"a_contoso.com#EXT#",
      "userPrincipalName":"a_contoso.com#EXT#@contoso.com"
    }
  ]
}

Ejemplo 5: Use $filter para obtener todos los usuarios con un correo que termine con ""a@contoso.com, incluido un recuento de objetos devueltos, con los resultados ordenados por userPrincipalName.

Solicitud

En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual y la cadena de consulta $count=true porque la solicitud tiene los parámetros de consulta $orderby y $filter, y también usa el operador endsWith. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.

Nota: Los parámetros de consulta $count y $search actualmente no están disponibles en inquilinos de Azure AD B2C.

GET https://graph.microsoft.com/v1.0/users?$filter=endswith(mail,'a@contoso.com')&$orderby=userPrincipalName&$count=true
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.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count": 1,
  "value": [
    {
      "displayName": "Grady Archie",
      "givenName": "Grady",
      "jobTitle": "Designer",
      "mail": "GradyA@contoso.com",
      "userPrincipalName": "GradyA@contoso.com",
      "id": "e8b753b5-4117-464e-9a08-713e1ff266b3"
      }
    ]
}

Ejemplo 6: use $search para obtener usuarios cuyos nombres para mostrar contengan las letras "wa", junto con un recuento de los objetos devueltos

Solicitud

En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual porque $search está en la solicitud. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.

Nota: Los parámetros de consulta $count y $search actualmente no están disponibles en inquilinos de Azure AD B2C.

GET https://graph.microsoft.com/v1.0/users?$search="displayName:wa"&$orderby=displayName&$count=true
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.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Oscar Ward",
      "givenName":"Oscar",
      "mail":"oscarward@contoso.com",
      "userPrincipalName":"oscarward@contoso.com"
    }
  ]
}

Ejemplo 7: use $search para obtener usuarios con nombres para mostrar que contengan las letras "wa" o las letras "to", junto con un recuento de los objetos devueltos

Solicitud

En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual porque $search está en la solicitud. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.

Nota: Los parámetros de consulta $count y $search actualmente no están disponibles en inquilinos de Azure AD B2C.

GET https://graph.microsoft.com/v1.0/users?$search="displayName:wa" OR "displayName:ad"&$orderbydisplayName&$count=true
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.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Oscar Ward",
      "givenName":"Oscar",
      "mail":"oscarward@contoso.com",
      "userPrincipalName":"oscarward@contoso.com"
    },
    {
      "displayName":"contosoAdmin1",
      "givenName":"Contoso Administrator",
      "mail":"'contosoadmin1@fabrikam.com",
      "userPrincipalName":"contosoadmin1_fabrikam.com#EXT#@contoso.com"
    }
  ]
}

Ejemplo 8: Obtención de usuarios invitados (B2B) de un inquilino o dominio específicos por userPrincipalName

Solicitud

En el ejemplo siguiente se muestra la solicitud. El valor userPrincipalName para los usuarios invitados (colaboración B2B) siempre contiene el identificador "#EXT#". Por ejemplo, userPrincipalName de un usuario en su inquilino principal es AdeleV@adatum.com. Al invitar al usuario a colaborar en el inquilino, contoso.com, su userPrincipalName en el inquilino es "AdeleV_adatum.com#EXT#@contoso.com".

Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual y la cadena de $count=true consulta porque la solicitud incluye el operador endsWith. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.

NOTA: Debe codificar el carácter reservado "#" en el valor userPrincipalName como "%23" en la dirección URL de la solicitud. Para obtener más información, vea Codificación de caracteres especiales.

GET https://graph.microsoft.com/v1.0/users?$select=id,displayName,mail,identities&$filter=endsWith(userPrincipalName,'%23EXT%23@contoso.com')&$count=true
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.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,mail,identities)",
    "@odata.count": 2,
    "value": [
        {
            "id": "39807bd1-3dde-48f3-8165-81ddd4e46de0",
            "displayName": "Adele Vance",
            "mail": "AdeleV@adatum.com",
            "identities": [
                {
                    "signInType": "userPrincipalName",
                    "issuer": "contoso.com",
                    "issuerAssignedId": "AdeleV_adatum.com#EXT#@cntoso.com"
                }
            ]
        }
    ]
}

Ejemplo 9: Uso de $filter para obtener usuarios a los que se les asigna una licencia específica

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/v1.0/users?$select=id,mail,assignedLicenses&$filter=assignedLicenses/any(u:u/skuId eq cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46)

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,mail,assignedLicenses)",
  "value": [
    {
      "id": "cb4954e8-467f-4a6d-a8c8-28b9034fadbc",
      "mail": "admin@contoso.com",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46"
        }
      ]
    },
    {
      "id": "81a133c2-bdf2-4e67-8755-7264366b04ee",
      "mail": "DebraB@contoso.com",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46"
        }
      ]
    }
  ]
}

Ejemplo 10: Obtener el valor de una extensión de esquema para todos los usuarios

En este ejemplo, el identificador de la extensión de esquema es ext55gb1l09_msLearnCourses.

Solicitud

GET https://graph.microsoft.com/v1.0/users?$select=ext55gb1l09_msLearnCourses

Respuesta

En la respuesta siguiente, la propiedad de extensión de esquema ext55gb1l09_msLearnCourses no está asignada en dos de los objetos de usuario.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(ext55gb1l09_msLearnCourses)",
    "value": [
        {},
        {
            "ext55gb1l09_msLearnCourses": {
                "@odata.type": "#microsoft.graph.ComplexExtensionValue",
                "courseType": "Developer",
                "courseName": "Introduction to Microsoft Graph",
                "courseId": 1
            }
        },
        {}
    ]
}

Nota: También puede aplicar $filter en la propiedad de extensión de esquema para recuperar objetos en los que una propiedad de la colección coincida con un valor especificado. La sintaxis es /users?$filter={schemaPropertyID}/{propertyName} eq 'value'. Por ejemplo, GET /users?$select=ext55gb1l09_msLearnCourses&$filter=ext55gb1l09_msLearnCourses/courseType eq 'Developer'. Se admiten los operadores eq y not.

Ejemplo 11: Obtención de usuarios que incluyan su última hora de inicio de sesión

Solicitud

En el ejemplo siguiente se muestra la solicitud.

Nota:

  • Los detalles de la propiedad signInActivity requieren una licencia Microsoft Entra ID P1 o P2 y el AuditLog.Read.All permiso.
  • Al especificar o al enumerar $select=signInActivity usuarios, el tamaño máximo de página para $top es 500.$filter=signInActivity Solicitudes con $top un conjunto superior a 500 páginas devueltas con hasta 500 usuarios. La propiedad signInActivity admite $filter (eq, ne, not, ge, le), pero no con ninguna otra propiedad filtrable.
GET https://graph.microsoft.com/v1.0/users?$select=displayName,userPrincipalName,signInActivity

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.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(displayName,userPrincipalName,signInActivity)",
  "value": [
    {
      "displayName": "Adele Vance",
      "userPrincipalName": "AdeleV@contoso.com",
      "id": "1aecaf40-dc3a-461f-88a8-d06994e12898",
      "signInActivity": {
        "lastSignInDateTime": "2021-06-17T16:41:33Z",
        "lastSignInRequestId": "d4d31c40-4c36-4775-ad59-7d1e6a171f00",
        "lastNonInteractiveSignInDateTime": "0001-01-01T00:00:00Z",
        "lastNonInteractiveSignInRequestId": "",
        "lastSuccessfulSignInDateTime": "",
        "lastSuccessfulSignInRequestId": ""
      }
    },
    {
      "displayName": "Alex Wilber",
      "userPrincipalName": "AlexW@contoso.com",
      "id": "f0662ee5-84b1-43d6-8338-769cce1bc141",
      "signInActivity": {
        "lastSignInDateTime": "2021-07-29T15:53:27Z",
        "lastSignInRequestId": "f3149ee1-e347-4181-b45b-99a1f82b1c00",
        "lastNonInteractiveSignInDateTime": "2021-07-29T17:53:42Z",
        "lastNonInteractiveSignInRequestId": "868efa6a-b2e9-40e9-9b1c-0aaea5b50200",
        "lastSuccessfulSignInDateTime": "",
        "lastSuccessfulSignInRequestId": ""
      }
    }
  ]
}

Ejemplo 12: Usar $filter y endsWith para obtener usuarios con un dominio de nivel superior especificado en otrosMails

Solicitud

En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual porque $count está en la solicitud. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.

GET https://graph.microsoft.com/v1.0/users?$filter=otherMails/any(x:endswith(x,'.edu'))&$count=true
ConsistencyLevel: eventual

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/v1.0/$metadata#users",
    "@odata.count": 2,
    "value": [
        {
            "displayName": "Isaiah Langer",
            "mail": "isaiahl@fineartschool.edu",
            "id": "0012cd20-3890-409e-9db3-afc3055ebe22"
        },
        {
            "displayName": "Adele Vance",
            "mail": "adelev@bellowscollege.edu",
            "id": "0012cd20-3890-409e-9db3-afc3055ebe22"
        }
    ]
}

Ejemplo 13: Enumerar todos los usuarios cuya administración está restringida

En el ejemplo siguiente se muestra cómo enumerar todos los usuarios cuya administración está restringida.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/v1.0/users?$filter=isManagementRestricted eq true&$select=displayName,userPrincipalName

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.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(displayName,userPrincipalName)",
  "value": [
    {
      "displayName": "Adele",
      "userPrincipalName": "Adele@contoso.com"
    },
    {
      "displayName": "Bob",
      "userPrincipalName": "Bob@contoso.com"
    }
  ]
}