Obtener un usuario

Artículo
03/05/2024

Espacio de nombres: microsoft.graph

Recupera las propiedades y relaciones del objeto user.

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

Sugerencia

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.

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.

Ejemplos

Ejemplo 1: Solicitud de usuarios estándar

Solicitud

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].GetAsync();


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users get --user-id {user-id}



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



users, err := graphClient.Users().ByUserId("user-id").Get(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.users().byUserId("{user-id}").get();


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->users()->byUserId('user-id')->get()->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId


from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


result = await graph_client.users.by_user_id('user-id').get()

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.GetAsync();


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users get --user-id {user-id}



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



me, err := graphClient.Me().Get(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.me().get();


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/me')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->me()->get()->wait();


Import-Module Microsoft.Graph.Users

# A UPN can also be used as -UserId.
Get-MgUser -UserId $userId


from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


result = await graph_client.me.get()

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","givenName","postalCode","identities" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users get --user-id {user-id} --select "displayName,givenName,postalCode,identities"



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphusers.UserItemRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","givenName","postalCode","identities"},
}
configuration := &graphusers.UserItemRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().ByUserId("user-id").Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.users().byUserId("{user-id}").get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "givenName", "postalCode", "identities"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd')
	.select('displayName,givenName,postalCode,identities')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UserItemRequestBuilderGetRequestConfiguration();
$queryParameters = UserItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["displayName","givenName","postalCode","identities"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->byUserId('user-id')->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId -Property "displayName,givenName,postalCode,identities"


from msgraph import GraphServiceClient
from msgraph.generated.users.item.user_item_request_builder import UserItemRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UserItemRequestBuilder.UserItemRequestBuilderGetQueryParameters(
		select = ["displayName","givenName","postalCode","identities"],
)

request_configuration = UserItemRequestBuilder.UserItemRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.by_user_id('user-id').get(request_configuration = request_configuration)

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "ext55gb1l09_msLearnCourses" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users get --user-id {user-id} --select "ext55gb1l09_msLearnCourses"



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphusers.UserItemRequestBuilderGetQueryParameters{
	Select: [] string {"ext55gb1l09_msLearnCourses"},
}
configuration := &graphusers.UserItemRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().ByUserId("user-id").Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.users().byUserId("{user-id}").get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"ext55gb1l09_msLearnCourses"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e')
	.select('ext55gb1l09_msLearnCourses')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UserItemRequestBuilderGetRequestConfiguration();
$queryParameters = UserItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["ext55gb1l09_msLearnCourses"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->byUserId('user-id')->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId -Property "ext55gb1l09_msLearnCourses"


from msgraph import GraphServiceClient
from msgraph.generated.users.item.user_item_request_builder import UserItemRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UserItemRequestBuilder.UserItemRequestBuilderGetQueryParameters(
		select = ["ext55gb1l09_msLearnCourses"],
)

request_configuration = UserItemRequestBuilder.UserItemRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.by_user_id('user-id').get(request_configuration = request_configuration)

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "customSecurityAttributes" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users get --user-id {user-id} --select "customSecurityAttributes"



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphusers.UserItemRequestBuilderGetQueryParameters{
	Select: [] string {"customSecurityAttributes"},
}
configuration := &graphusers.UserItemRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().ByUserId("user-id").Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.users().byUserId("{user-id}").get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"customSecurityAttributes"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/{id}')
	.select('customSecurityAttributes')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UserItemRequestBuilderGetRequestConfiguration();
$queryParameters = UserItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["customSecurityAttributes"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->byUserId('user-id')->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId -Property "customSecurityAttributes"


from msgraph import GraphServiceClient
from msgraph.generated.users.item.user_item_request_builder import UserItemRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UserItemRequestBuilder.UserItemRequestBuilderGetQueryParameters(
		select = ["customSecurityAttributes"],
)

request_configuration = UserItemRequestBuilder.UserItemRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.by_user_id('user-id').get(request_configuration = request_configuration)

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
}

Obtener un usuario

Permissions

Solicitud HTTP

Parámetros de consulta opcionales

Encabezados de solicitud

Cuerpo de la solicitud

Respuesta

Ejemplos

Ejemplo 1: Solicitud de usuarios estándar

Solicitud

Respuesta

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

Solicitud

Respuesta

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

Solicitud

Respuesta

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

Solicitud

Respuesta

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

Solicitud

Respuesta

Comentarios

Comentarios

Recursos adicionales