Compartir a través de


Obtener un usuario

Espacio de nombres: microsoft.graph

Recupere las propiedades y las relaciones del objeto de usuario .

Esta operación devuelve de forma predeterminada solo un subconjunto de las propiedades más utilizadas de cada usuario. Estas propiedades predeterminadas se indican en la sección Propiedades. Para obtener propiedades que no se devuelven de forma predeterminada, realice una operación GET para el usuario y especifique las propiedades de una opción de consulta de OData $select. Dado que el recurso user admite extensiones, también puede utilizar la GEToperación para obtener propiedades personalizadas y datos de extensión en una instancia user.

Los clientes a través de Microsoft Entra ID para los clientes también pueden usar esta operación de API para recuperar sus detalles.

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) User.Read User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegado (cuenta personal de Microsoft) User.Read User.ReadWrite
Aplicación User.Read.All User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Nota:

  • Para llamar al punto de conexión /me, se requiere un usuario con la sesión iniciada y, por lo tanto, un permiso delegado. Los permisos de aplicación no son compatibles al usar el punto de conexión /me.
  • El permiso User.Read permite a la aplicación leer el perfil y detectar relaciones como la pertenencia a grupos, los informes y el administrador del usuario que ha iniciado sesión únicamente.

Permisos para escenarios específicos

  • Para leer la propiedad employeeLeaveDateTime :
    • En escenarios delegados, el usuario que ha iniciado sesión necesita al menos uno de los siguientes roles de Microsoft Entra: Administrador de flujos de vida (privilegios mínimos), Lector global; a la aplicación se le debe conceder el permiso delegado User-LifeCycleInfo.Read.All.
    • En escenarios de solo aplicación con permisos de Microsoft Graph, se debe conceder a la aplicación el permiso User-LifeCycleInfo.Read.All .
  • Para leer la propiedad customSecurityAttributes :
    • En escenarios delegados, al usuario que ha iniciado sesión se le debe asignar el rol Administrador de asignación de atributos y a la aplicación se le ha concedido el permiso CustomSecAttributeAssignment.Read.All .
    • En escenarios de solo aplicación con permisos de Microsoft Graph, se debe conceder a la aplicación el permiso CustomSecAttributeAssignment.Read.All .
  • 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 la propiedad passwordProfile ; 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

Para un usuario específico:

GET /me
GET /users/{id | userPrincipalName}

Sugerencia

  • Cuando el userPrincipalName comienza con un carácter $, se produce un error en la sintaxis de la dirección URL de la solicitud GET /users/$x@y.com que arroja un código de error 400 Bad Request. Esto se debe a que esta dirección URL de solicitud infringe la convención de URL de OData, que espera que solo las opciones de consulta del sistema tengan un prefijo con un carácter $. Quite la barra diagonal (/) después de /users y escriba userPrincipalName entre paréntesis y comillas simples como se muestra a continuación: /users('$x@y.com'). Por ejemplo, /users('$AdeleVance@contoso.com').
  • Para consultar a un usuario B2B mediante el userPrincipalName, codifique el carácter hash (#). Es decir, reemplace el símbolo # por %23. Por ejemplo, /users/AdeleVance_adatum.com%23EXT%23@contoso.com.

Para un usuario con sesión iniciada:

GET /me

Parámetros de consulta opcionales

Este método admite el $selectparámetro de consulta OData para recuperar propiedades de usuario específicas, incluidas las que no se devuelven de forma predeterminada.

De forma predeterminada, solo se devuelve un conjunto limitado de propiedades. (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName).

Para devolver un conjunto de propiedades alternativo, tiene que especificar el conjunto de propiedades de usuario que prefiera con el parámetro de consulta $select de OData. Por ejemplo, para devolver displayName, givenName y postalCode, agregue la siguiente expresión a la 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.
Extensiones de esquema Solo se devuelve con $select.
Extensiones abiertas Solo se devuelve a través de la operación Obtener extensión abierta.
Extensiones de directorio Solo se devuelve con $select.

Encabezados de solicitud

Encabezado Valor
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.

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 el objeto user en el cuerpo de la respuesta. Devuelve las propiedades predeterminadas a menos que se use $select para especificar propiedades específicas. Este método devuelve 202 Accepted cuando la solicitud se ha procesado correctamente pero el servidor necesita más tiempo para completar las operaciones en segundo plano relacionadas.

Si un usuario con el identificador no existe, este método devuelve un código de 404 Not Found error.

Ejemplos

Ejemplo 1: Solicitud de usuarios estándar

Solicitud

De forma predeterminada, solo se devuelve un conjunto limitado de propiedades. (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName). Este ejemplo ilustra las solicitudes y respuestas predeterminadas.

GET https://graph.microsoft.com/v1.0/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd

Respuesta

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

{
  "businessPhones": [
       "+1 425 555 0109"
   ],
   "displayName": "Adele Vance",
   "givenName": "Adele",
   "jobTitle": "Retail Manager",
   "mail": "AdeleV@contoso.com",
   "mobilePhone": "+1 425 555 0109",
   "officeLocation": "18/2111",
   "preferredLanguage": "en-US",
   "surname": "Vance",
   "userPrincipalName": "AdeleV@contoso.com",
   "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}

Ejemplo 2: Solicitud de usuario de inicio de sesión

Puede obtener la información de usuario para el usuario que hayan iniciado sesión reemplazando /users/{id | userPrincipalName} con /me.

Solicitud

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

Respuesta

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

{
  "businessPhones": [
       "+1 425 555 0109"
   ],
   "displayName": "Adele Vance",
   "givenName": "Adele",
   "jobTitle": "Retail Manager",
   "mail": "AdeleV@contoso.com",
   "mobilePhone": "+1 425 555 0109",
   "officeLocation": "18/2111",
   "preferredLanguage": "en-US",
   "surname": "Vance",
   "userPrincipalName": "AdeleV@contoso.com",
   "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}

Ejemplo 3: usar $select para recuperar propiedades específicas de un usuario

Para recuperar propiedades específicas, use el parámetro de consulta OData $select. Por ejemplo, para devolver displayName, givenName, postalCode e identities, se usaría la opción agregar lo siguiente a la consulta $select=displayName,givenName,postalCode,identities

Solicitud

GET https://graph.microsoft.com/v1.0/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd?$select=displayName,givenName,postalCode,identities

Respuesta

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(displayName,givenName,postalCode,identities)/$entity",
    "displayName": "Adele Vance",
    "givenName": "Adele",
    "postalCode": "98004",
    "identities": [
        {
            "signInType": "userPrincipalName",
            "issuer": "contoso.com",
            "issuerAssignedId": "AdeleV@contoso.com"
        }
    ]
}

Ejemplo 4: obtener el valor de una extensión de esquema para un usuario

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

Solicitud

GET https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e?$select=ext55gb1l09_msLearnCourses

Respuesta

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

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

Ejemplo 5: Obtención de las asignaciones de atributos de seguridad personalizados para un usuario

En el ejemplo siguiente se muestra cómo obtener las asignaciones de atributos de seguridad personalizados para un usuario.

Atributo n.º 1

  • Conjunto de atributos: Engineering
  • Atributo: Project
  • Tipo de datos de atributo: colección de cadenas
  • Valor de atributo: ["Baker","Cascade"]

Atributo n.º 2

  • Conjunto de atributos: Engineering
  • Atributo: CostCenter
  • Tipo de datos de atributo: colección de enteros
  • Valor de atributo: [1001]

Atributo n.º 3

  • Conjunto de atributos: Engineering
  • Atributo: Certification
  • Tipo de datos de atributo: boolean
  • Valor de atributo: true

Atributo n.º 4

  • Conjunto de atributos: Marketing
  • Atributo: EmployeeId
  • Tipo de datos de atributo: Cadena
  • Valor de atributo: "QN26904"

Para obtener asignaciones de atributos de seguridad personalizadas, se debe asignar a la entidad de seguridad de llamada el rol Lector de asignación de atributos o Administrador de asignación de atributos y se le debe conceder el permiso CustomSecAttributeAssignment.Read.All o CustomSecAttributeAssignment.ReadWrite.All.

Para obtener más ejemplos de asignaciones de atributos de seguridad personalizadas, vea Ejemplos: Asignación, actualización, lista o eliminación de asignaciones de atributos de seguridad personalizados mediante microsoft Graph API.

Solicitud

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

Respuesta

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": {
        "Marketing": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "EmployeeId": "QN26904"
        },
        "Engineering": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "Project@odata.type": "#Collection(String)",
            "Project": [
                "Baker",
                "Cascade"
            ],
            "CostCenter@odata.type": "#Collection(Int32)",
            "CostCenter": [
                1001
            ],
            "Certification": true
        }
    }
}

Si no hay atributos de seguridad personalizados asignados al usuario o si la entidad de seguridad que realiza la llamada no tiene acceso, la siguiente será la respuesta:

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": null
}