Obtener usuario
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.
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 GET
operació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 se admiten cuando se usa el punto de/me
conexión. - El
User.Read
permiso 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 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
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 error400 Bad Request
. Se produce un error en la solicitud porque la dirección URL infringe la convención de dirección URL de OData, que espera que solo las opciones de consulta del sistema estén precedidas de 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 $select
parámetro de consulta OData para recuperar propiedades de usuario específicas, incluidas las que no se devuelven de forma predeterminada. 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.
Ejemplo
Ejemplo 1: obtenga las propiedades del usuario con la sesión iniciada
Solicitud
GET https://graph.microsoft.com/beta/me
Respuesta
En el ejemplo siguiente se muestra la respuesta. Nota: el objeto de respuesta que se muestra aquí puede haberse acortado para mejorar la legibilidad.
HTTP/1.1 200 OK
Content-type: application/json
{
"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: obtenga las propiedades del usuario con la sesión iniciada
Solicitud
En el ejemplo siguiente se muestra la solicitud.
GET https://graph.microsoft.com/beta/users/{id}
Respuesta
En el ejemplo siguiente se muestra la respuesta.
HTTP/1.1 200 OK
Content-type: application/json
{
"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 identidades, agregue la siguiente expresión de consulta a la consulta. $select=displayName,givenName,postalCode,identities
Solicitud
GET https://graph.microsoft.com/v1.0/users/{id | userPrincipalName}?$select=displayName,givenName,postalCode,identities
Respuesta
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$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: 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/beta/users/{id}?$select=customSecurityAttributes
Respuesta
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$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, el siguiente bloque muestra la respuesta:
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users(customSecurityAttributes)/$entity",
"customSecurityAttributes": null
}
Ejemplo 5: 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/beta/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/beta/$metadata#users(ext55gb1l09_msLearnCourses)/$entity",
"ext55gb1l09_msLearnCourses": {
"@odata.type": "#microsoft.graph.ComplexExtensionValue",
"courseType": "Developer",
"courseName": "Introduction to Microsoft Graph",
"courseId": 1
}
}