Répertorier des utilisateurs

Espace de noms: microsoft.graph

Récupérez la liste des objets user.

Autorisations

L’une des autorisations suivantes est nécessaire pour appeler cette API. Pour plus d’informations, notamment sur la façon de choisir les autorisations, voir Autorisations.

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Déléguée (compte Microsoft personnel) Non prise en charge.
Application User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Les utilisateurs invités ne peuvent pas appeler cette API. Pour plus d’informations sur les autorisations pour les utilisateurs membres et invités, consultez Quelles sont les autorisations utilisateur par défaut dans Azure Active Directory ?

Requête HTTP

GET /users

Paramètres facultatifs de la requête

Cette méthode prend en charge les paramètres de requête $count, $expand, $filter, $orderBy, $search, $selectet $top OData pour personnaliser la réponse. $skip n’est pas pris en charge. Les tailles de page par défaut et maximales sont respectivement de 100 et 999 objets utilisateur. Certaines requêtes sont prises en charge uniquement lorsque vous utilisez l’en-tête ConsistencyLevel défini sur eventual et $count. Pour plus d’informations, consultez Capacités de requête avancées sur les objets annuaire Azure AD. Les paramètres $count et $search ne sont actuellement pas disponibles dans les clients Azure AD B2C.

Par défaut, seul un ensemble limité de propriétés est renvoyé (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname et userPrincipalName). Pour renvoyer un autre jeu de propriétés, spécifiez le jeu souhaité de propriétés user à l’aide du paramètre de requête $select OData. Par exemple, pour renvoyer displayName, givenName et postalCode, ajoutez les éléments suivants à votre requête $select=displayName,givenName,postalCode.

Certaines propriétés ne peuvent pas être renvoyées dans une collection d’utilisateurs. Les propriétés suivantes sont uniquement prises en charge lors de l’extraction d’un seul utilisateur : aboutMe, birthday, hireDate, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, mailboxSettings.

Les propriétés suivantes ne sont pas prises en charge dans les comptes Microsoft personnels et seront null : aboutMe, birthday, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, streetAddress.

En-têtes de demande

En-tête Valeur
Authorization Bearer {token} (requis)
ConsistencyLevel éventuellement. Cet en-tête et cet $count sont requis lors de l’utilisation de $search, ou dans une utilisation spécifique de $filter. Pour plus d’informations sur l’utilisation de ConsistencyLevel et $count, consultez Fonctionnalités de requête avancées sur Azure AD objets d’annuaire.

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 une collection d’objets utilisateur dans le corps de la réponse. Si une collection importante d’utilisateurs est renvoyée, vous pouvez utiliser une pagination dans votre application.

Toute tentative d’utilisation de $select sur la collection /users pour récupérer des propriétés qui ne peuvent pas être renvoyées au sein d’une collection d’utilisateurs (par exemple, la demande ../users?$select=aboutMe) renvoie un code d’erreur 501 Not Implemented.

Exemples

Exemple 1 : obtenir tous les utilisateurs

Demande

Voici un exemple de demande.

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

Réponse

Voici un exemple de réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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

{
  "value": [
    {
      "displayName":"contoso1",
      "mail":"'contoso1@gmail.com",
      "mailNickname":"contoso1_gmail.com#EXT#",
      "otherMails":["contoso1@gmail.com"],
      "proxyAddresses":["SMTP:contoso1@gmail.com"], 
      "userPrincipalName":"contoso1_gmail.com#EXT#@microsoft.onmicrosoft.com"
    }
  ]
}

Exemple 2 : obtenir un compte d’utilisateur à l’aide d’un nom de connexion

Demande

Voici un exemple de demande.

Lorsque vous filtrez par identités, vous devez fournir l’émetteur et la fonction issuerAssignedId. La valeur de issuerAssignedId doit être l’adresse e-mail du compte d’utilisateur, et non le nom d’utilisateur principal (UPN). Si un nom d’utilisateur principal est utilisé, la réponse est une liste vide.

GET https://graph.microsoft.com/v1.0/users?$select=displayName,id&$filter=identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'contoso.onmicrosoft.com')

Réponse

Voici un exemple de réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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

{
  "value": [
    {
      "displayName": "John Smith"
    }
  ]
}

Exemple 3 : obtenir seulement un nombre d’utilisateurs

Demande

Voici un exemple de demande. Cette demande nécessite que l’en-tête ConsistencyLevel soit défini sur eventual, car $count figure dans la demande. Pour plus d’informations sur l’utilisation de ConsistencyLevel et $count, consultez Fonctionnalités de requête avancées sur Azure AD objets d’annuaire.

Remarque : Les paramètres de requête $count et $search ne sont actuellement pas disponibles dans les clients Azure AD B2C.

GET https://graph.microsoft.com/v1.0/users/$count
ConsistencyLevel: eventual

Réponse

Voici un exemple de réponse.

HTTP/1.1 200 OK
Content-type: text/plain

893

Exemple 7 : utiliser $filter et $top pour obtenir un groupe avec un nom complet commençant par « a », avec un nombre d’objets retournés

Demande

Voici un exemple de demande. Cette requête nécessite que l’en-tête ConsistencyLevel soit défini sur eventual et la chaîne de requête $count=true, car la requête a les paramètres de requête $orderBy et $filter. Pour plus d’informations sur l’utilisation de ConsistencyLevel et $count, consultez Fonctionnalités de requête avancées sur Azure AD objets d’annuaire.

Remarque : Les paramètres de requête $count et $search ne sont actuellement pas disponibles dans les clients Azure AD B2C.

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'a')&$orderby=displayName&$count=true&$top=1
ConsistencyLevel: eventual

Réponse

Voici un exemple de réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count":1,
  "value":[
    {
      "displayName":"a",
      "mail":"a@contoso.com",
      "mailNickname":"a_contoso.com#EXT#",
      "otherMails":["a@contoso.com"],
      "proxyAddresses":["SMTP:a@contoso.com"],
      "userPrincipalName":"a_contoso.com#EXT#@microsoft.onmicrosoft.com"
    }
  ]
}

Exemple 5 : utilisez $filter pour obtenir tous les utilisateurs ayant un courrier qui se termine par « a@contoso.com » y compris le nombre d’objets renvoyés, avec les résultats commandés par userPrincipalName.

Requête

Voici un exemple de demande. Cette requête nécessite que l’en-tête ConsistencyLevel soit défini sur eventual et la chaîne de requête $count=true, car la requête a les paramètres de requête $orderBy et $filter, et et utilise également l’opérateur endsWith. Pour plus d’informations sur l’utilisation de ConsistencyLevel et $count, consultez Fonctionnalités de requête avancées sur Azure AD objets d’annuaire.

Remarque : Les paramètres de requête $count et $search ne sont actuellement pas disponibles dans les clients Azure AD B2C.

GET https://graph.microsoft.com/v1.0/users?$filter=endswith(mail,'a@contoso.com')&$orderby=userPrincipalName&$count=true
ConsistencyLevel: eventual

Réponse

Voici un exemple de réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count": 1,
  "value": [
    {
      "displayName": "Grady Archie",
      "givenName": "Grady",
      "jobTitle": "Designer",
      "mail": "GradyA@contoso.com",
      "userPrincipalName": "GradyA@contoso.com",
      "id": "e8b753b5-4117-464e-9a08-713e1ff266b3"
      }
    ]
}

Exemple 6 : utiliser $search pour récupérer les utilisateurs contenant des noms complets contenant les lettres « wa » ou les lettres « to », y compris le nombre d’objets retournés

Demande

Voici un exemple de demande. Cette demande nécessite que l’en-tête ConsistencyLevel soit défini sur eventual, car $search figure dans la demande. Pour plus d’informations sur l’utilisation de ConsistencyLevel et $count, consultez Fonctionnalités de requête avancées sur Azure AD objets d’annuaire.

Remarque : Les paramètres de requête $count et $search ne sont actuellement pas disponibles dans les clients Azure AD B2C.

GET https://graph.microsoft.com/v1.0/users?$search="displayName:wa"&$orderby=displayName&$count=true
ConsistencyLevel: eventual

Réponse

Voici un exemple de réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Oscar Ward",
      "givenName":"Oscar",
      "mail":"oscarward@contoso.com",
      "mailNickname":"oscward",
      "userPrincipalName":"oscarward@contoso.com"
    }
  ]
}

Exemple 7 : utiliser $search pour obtenir les utilisateurs dont les noms d’affichage contiennent les lettres « wa » ou « ad » ainsi que le nombre d’objets renvoyés

Demande

Voici un exemple de demande. Cette demande nécessite que l’en-tête ConsistencyLevel soit défini sur eventual, car $search figure dans la demande. Pour plus d’informations sur l’utilisation de ConsistencyLevel et $count, consultez Fonctionnalités de requête avancées sur Azure AD objets d’annuaire.

Remarque : Les paramètres de requête $count et $search ne sont actuellement pas disponibles dans les clients Azure AD B2C.

GET https://graph.microsoft.com/v1.0/users?$search="displayName:wa" OR "displayName:ad"&$orderbydisplayName&$count=true
ConsistencyLevel: eventual

Réponse

Voici un exemple de réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Oscar Ward",
      "givenName":"Oscar",
      "mail":"oscarward@contoso.com",
      "mailNickname":"oscward",
      "userPrincipalName":"oscarward@contoso.com"
    },
    {
      "displayName":"contosoAdmin1",
      "mail":"'contosoadmin1@gmail.com",
      "mailNickname":"contosoadmin1_gmail.com#EXT#",
      "proxyAddresses":["SMTP:contosoadmin1@gmail.com"], 
      "userPrincipalName":"contosoadmin1_gmail.com#EXT#@microsoft.onmicrosoft.com"
    }
  ]
}

Exemple 8 : utiliser $filter pour obtenir les utilisateurs auxquels est attribuée une licence spécifique

Demande

Voici un exemple de demande.

GET https://graph.microsoft.com/v1.0/users?$select=id,mail,assignedLicenses&$filter=assignedLicenses/any(u:u/skuId eq cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46)

Réponse

Voici un exemple de réponse.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,mail,assignedLicenses)",
  "value": [
    {
      "id": "cb4954e8-467f-4a6d-a8c8-28b9034fadbc",
      "mail": "admin@contoso.com",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46"
        }
      ]
    },
    {
      "id": "81a133c2-bdf2-4e67-8755-7264366b04ee",
      "mail": "DebraB@contoso.com",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46"
        }
      ]
    }
  ]
}