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.
Autorisations pour des scénarios spécifiques
- Pour lire la propriété employeeLeaveDateTime :
- Dans les scénarios délégués, l’utilisateur connecté 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’utilisateur connecté 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 .
- User-Mail.ReadWrite.All est l’autorisation la moins privilégiée pour lire et écrire la propriété otherMails ; permet également de lire certaines propriétés liées à l’identificateur sur l’objet utilisateur.
- User-PasswordProfile.ReadWrite.All est l’autorisation la moins privilégiée pour lire et écrire la propriété passwordProfile ; permet également de lire certaines propriétés liées à l’identificateur sur l’objet utilisateur.
- User-Phone.ReadWrite.All est l’autorisation la moins privilégiée pour lire et écrire les propriétés businessPhones et mobilePhone ; permet également de lire certaines propriétés liées à l’identificateur sur l’objet utilisateur.
- User.EnableDisableAccount.All + User.Read.All est la combinaison d’autorisations la moins privilégiée pour lire et écrire la propriété accountEnabled .
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 un400 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 $select
paramè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
}