Obtenir un utilisateur

Espace de noms: microsoft.graph

Récupérer les propriétés et les relations de l’objet utilisateur .

Cette opération renvoie par défaut uniquement un sous-ensemble des propriétés plus couramment utilisées pour chaque utilisateur. Ces propriétés par défaut sont indiquées dans la section Propriétés. Pour obtenir des propriétés qui ne sont pas renvoyées par défaut, effectuez une opération GET pour l'utilisateur et spécifiez les propriétés dans une option de requête OData $select. Dans la mesure où la ressource utilisateur prend en charge des extensions, vous pouvez également utiliser l’opération GET pour obtenir des propriétés personnalisées et des données d’extension dans une instance utilisateur.

Les clients via Microsoft Entra ID pour les clients peuvent également utiliser cette opération d’API pour récupérer leurs détails.

Cette API est disponible dans les déploiements de cloud national suivants.

Service global Gouvernement des États-Unis L4 Us Government L5 (DOD) Chine gérée par 21Vianet

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme moins privilégiées pour cette API. Utilisez une autorisation ou des autorisations privilégiées plus élevées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, consultez Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez les informations de référence sur les autorisations.

Type d’autorisation Autorisations avec privilèges minimum Autorisations privilégiées plus élevées
Déléguée (compte professionnel ou scolaire) User.Read User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Déléguée (compte Microsoft personnel) User.Read User.ReadWrite
Application User.Read.All User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Remarque

  • L’appel du point de terminaison /me nécessite un utilisateur connecté et par conséquent une autorisation déléguée. Les autorisations d’application ne sont pas prises en charge lorsque le point de terminaison /me est utilisé.
  • L’autorisation User.Read permet à l’application de lire le profil et de découvrir des relations telles que l’appartenance au groupe, les rapports et le responsable de l’utilisateur connecté uniquement.
  • Pour lire la propriété employeeLeaveDateTime :
    • Dans les scénarios délégués, l’administrateur a besoin d’au moins l’un des rôles Microsoft Entra suivants : Administrateur des workflows de cycle de vie (privilège minimum), Lecteur général ; l’application doit disposer de l’autorisation déléguée User-LifeCycleInfo.Read.All.
    • Dans les scénarios d’application uniquement avec des autorisations Microsoft Graph, l’application doit disposer de l’autorisation User-LifeCycleInfo.Read.All .
  • Pour lire la propriété customSecurityAttributes :
    • Dans les scénarios délégués, l’administrateur doit se voir attribuer le rôle Administrateur d’attribution d’attributs et l’application doit disposer de l’autorisation CustomSecAttributeAssignment.Read.All .
    • Dans les scénarios d’application uniquement avec des autorisations Microsoft Graph, l’application doit disposer de l’autorisation CustomSecAttributeAssignment.Read.All .

Requête HTTP

Pour un utilisateur spécifique :

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

Conseil

  • Lorsque userPrincipalName commence par un $ caractère, la syntaxe de l’URL de la requête GET /users/$x@y.com échoue avec un 400 Bad Request code d’erreur. Cela est dû au fait que cette URL de requête enfreint la convention d’URL OData, qui n’attend que des options de requête système précédées par un caractère $. Supprimez la barre oblique (/) après /users et insérez le userPrincipalName entre parenthèses et les guillemets simples, comme suit : /users('$x@y.com'). Par exemple, /users('$AdeleVance@contoso.com').
  • Pour interroger un utilisateur B2B à l’aide de userPrincipalName, codez le caractère dièse (#). À savoir, remplacez le symbole # par %23. Par exemple, /users/AdeleVance_adatum.com%23EXT%23@contoso.com.

Pour l’utilisateur connecté :

GET /me

Paramètres facultatifs de la requête

Cette méthode prend en charge le $selectparamètre de requête OData pour récupérer des propriétés utilisateur spécifiques, y compris celles qui ne sont pas retournées par défaut.

Par défaut, seul un ensemble limité de propriétés est renvoyé (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName).

Pour renvoyer un autre jeu de propriétés, vous devez spécifier le jeu souhaité de propriétés user à l’aide du paramètre de requête $select OData. Par exemple, pour retourner displayName, givenName et postalCode, ajoutez l’expression suivante à votre requête $select=displayName,givenName,postalCode.

Les propriétés d’extension prennent également en charge les paramètres de requête comme suit :

Type d’extension Commentaires
onPremisesExtensionAttributes 1-15 Retourné uniquement avec $select.
Extensions de schéma Retourné uniquement avec $select.
Extensions d’ouverture Retourné uniquement par le biais de l’opération Obtenir une extension d’ouverture.
Extensions d’annuaire Retourné uniquement avec $select.

En-têtes de demande

En-tête Valeur
Autorisation Porteur {token}. Obligatoire. En savoir plus sur l’authentification et l’autorisation.

Corps de la demande

N’indiquez pas le corps de la demande pour cette méthode.

Réponse

Si elle réussit, cette méthode renvoie un code de réponse 200 OK et un objet user dans le corps de la réponse. Elle renvoie les propriétés par défaut, sauf si vous utilisez $select pour spécifier des propriétés spécifiques. Cette méthode renvoie 202 Accepted lorsque le traitement de la demande a réussi mais que le serveur a besoin de plus de temps pour effectuer les opérations d’arrière-plan associées.

Si un utilisateur avec l’ID n’existe pas, cette méthode retourne un 404 Not Found code d’erreur.

Exemples

Exemple 1 : Demande d’utilisateurs standard

Demande

Par défaut, seul un ensemble limité de propriétés est renvoyé (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName). Cet exemple illustre la demande et la réponse par défaut.

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

Réponse

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"
}

Exemple 2 : Demande de l’utilisateur connecté

Vous pouvez obtenir les informations de l’utilisateur connecté en remplaçant /users/{id | userPrincipalName} par /me.

Demande

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

Réponse

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"
}

Exemple 3 : utiliser $select pour récupérer des propriétés spécifiques d’un utilisateur

Pour récupérer des propriétés spécifiques, utilisez le paramètre de $select requête OData. Par exemple, pour renvoyer displayName, givenName, postalCodeet identités, vous devez utiliser l’ajout de ce qui suit à votre requête $select=displayName,givenName,postalCode,identities.

Demande

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

Réponse

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"
        }
    ]
}

Exemple 4 : obtenir la valeur d’une extension de schéma pour un utilisateur

Dans cet exemple, l’ID de l’extension de schéma est ext55gb1l09_msLearnCourses.

Demande

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

Réponse

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

Exemple 5 : Obtenir les attributions d’attributs de sécurité personnalisées pour un utilisateur

L’exemple suivant montre comment obtenir les attributions d’attributs de sécurité personnalisées pour un utilisateur.

Attribut #1

  • Jeu d’attributs : Engineering
  • Attribut : Project
  • Type de données d’attribut : collection de chaînes
  • Valeur d’attribut : ["Baker","Cascade"]

Attribut #2

  • Jeu d’attributs : Engineering
  • Attribut : CostCenter
  • Type de données d’attribut : collection de nombres entiers
  • Valeur d’attribut : [1001]

Attribut #3

  • Jeu d’attributs : Engineering
  • Attribut : Certification
  • Type de données d’attribut : booléen
  • Valeur d’attribut : true

Attribut #4

  • Jeu d’attributs : Marketing
  • Attribut : EmployeeId
  • Type de données d’attribut : chaîne
  • Valeur d’attribut : "QN26904"

Pour obtenir des affectations d’attributs de sécurité personnalisées, le principal appelant doit avoir le rôle de Lecteur d’affectation d’attributs ou le rôle d’Administrateur d’affectations d’attributs et doit avoir l’autorisation CustomSecAttributeAssignment.Read.All ou CustomSecAttributeAssignment.ReadWrite.All.

Pour obtenir d’autres exemples d’attributions d’attributs de sécurité personnalisées, consultez Exemples : Affecter, mettre à jour, lister ou supprimer des attributions d’attributs de sécurité personnalisées à l’aide du API Graph Microsoft.

Demande

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

Réponse

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 aucun attribut de sécurité personnalisé n’est affecté à l’utilisateur ou si le principal appelant n’a pas accès, voici la réponse :

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

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