Répertorier des utilisateurs

  • Article

Espace de noms: microsoft.graph

Récupérez la liste des objets user.

Remarque : Cette demande peut avoir des retards de réplication pour les utilisateurs qui ont été récemment créés, mis à jour ou supprimés.

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

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
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 invités ne peuvent pas appeler cette API. Pour plus d’informations sur les autorisations pour les membres et les invités, consultez Quelles sont les autorisations utilisateur par défaut dans Microsoft Entra ID ?

Requête HTTP

GET /users

Paramètres facultatifs de la requête

Cette méthode prend en charge les $countparamètres de requête , $orderby$filter$expand, $search, , $select, et$top OData pour personnaliser la réponse. $skip n’est pas pris en charge. Vous devez spécifier $select=signInActivity ou $filter=signInActivity lors de la liste des utilisateurs, car la propriété signInActivity n’est pas retournée par défaut.

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 Fonctionnalités de requête avancées sur les objets d’annuaire. 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 retourné (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, and userPrincipalName). Pour retourner un autre jeu de propriétés, spécifiez l’ensemble souhaité de propriétés utilisateur à 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.

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. Prend en charge $filter (eq, ne, et eq sur les valeurs null).
Extensions de schéma Retourné uniquement avec $select. Prend en charge $filter (eq, ne, et eq sur les valeurs null).
Extensions d’ouverture Retourné uniquement avec $expand, c’est-à-dire, users?$expand=extensions.
Extensions d’annuaire Retourné uniquement avec $select. Prend en charge $filter (eq, ne, et eq sur les valeurs null).

Certaines propriétés ne peuvent pas être retournées dans une collection d’utilisateurs. Les propriétés suivantes sont uniquement prises en charge lors de la récupération 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
Autorisation Porteur {token}. Obligatoire. En savoir plus sur l’authentification et l’autorisation.
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 les 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.

La tentative d’utilisation $select sur la /users collection pour récupérer des propriétés qui ne peuvent pas être retournées dans une collection d’utilisateurs (par exemple, la requête ../users?$select=aboutMe) retourne un 501 Not Implemented code d’erreur.

Exemples

Exemple 1 : obtenir tous les utilisateurs

Demande

L’exemple suivant illustre une demande.

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

Réponse

L’exemple suivant illustre la 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",
    "value": [
        {
            "businessPhones": [],
            "displayName": "Conf Room Adams",
            "givenName": null,
            "jobTitle": null,
            "mail": "Adams@contoso.com",
            "mobilePhone": null,
            "officeLocation": null,
            "preferredLanguage": null,
            "surname": null,
            "userPrincipalName": "Adams@contoso.com",
            "id": "6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0"
        },
        {
            "businessPhones": [
                "425-555-0100"
            ],
            "displayName": "MOD Administrator",
            "givenName": "MOD",
            "jobTitle": null,
            "mail": null,
            "mobilePhone": "425-555-0101",
            "officeLocation": null,
            "preferredLanguage": "en-US",
            "surname": "Administrator",
            "userPrincipalName": "admin@contoso.com",
            "id": "4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
        }
    ]
}

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

Demande

L’exemple suivant illustre une demande.

Remarque : lorsque vous filtrez pour un issuerAssignedId, vous devez fournir l’émetteur et la fonction issuerAssignedId. Toutefois, la valeur de l’émetteur est ignorée dans certains scénarios. Pour plus d’informations sur le filtrage des identités, consultez Type de ressource objectIdentity

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 'My B2C tenant')

Réponse

L’exemple suivant illustre la 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",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
    }
  ]
}

Exemple 3 : obtenir seulement un nombre d’utilisateurs

Demande

L’exemple suivant illustre une 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 les 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

L’exemple suivant illustre la 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

L’exemple suivant illustre une 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 les 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

L’exemple suivant illustre la 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#",
      "userPrincipalName":"a_contoso.com#EXT#@contoso.com"
    }
  ]
}

Exemple 5 : utiliser $filter pour obtenir tous les utilisateurs avec un message qui se termine par « »,a@contoso.com y compris un nombre d’objets retournés, avec les résultats classés par userPrincipalName

Demande

L’exemple suivant illustre une 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 les 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

L’exemple suivant illustre la 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

L’exemple suivant illustre une 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 les 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

L’exemple suivant illustre la 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",
      "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

L’exemple suivant illustre une 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 les 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

L’exemple suivant illustre la 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",
      "userPrincipalName":"oscarward@contoso.com"
    },
    {
      "displayName":"contosoAdmin1",
      "givenName":"Contoso Administrator",
      "mail":"'contosoadmin1@fabrikam.com",
      "userPrincipalName":"contosoadmin1_fabrikam.com#EXT#@contoso.com"
    }
  ]
}

Exemple 8 : Obtenir des utilisateurs invités (B2B) à partir d’un locataire ou d’un domaine spécifique par userPrincipalName

Demande

L’exemple suivant illustre une demande. La valeur userPrincipalName pour les utilisateurs invités (B2B Collaboration) contient toujours l’identificateur « #EXT# ». Par exemple, le userPrincipalName d’un utilisateur dans son locataire d’origine est AdeleV@adatum.com. Lorsque vous invitez l’utilisateur à collaborer dans votre locataire, contoso.com, son userPrincipalName dans votre locataire est « AdeleV_adatum.com#EXT#@contoso.com ».

Cette requête nécessite que l’en-tête ConsistencyLevel soit défini sur eventual et la $count=true chaîne de requête, car la requête inclut l’opérateur endsWith. Pour plus d’informations sur l’utilisation de ConsistencyLevel et $count, consultez Fonctionnalités de requête avancées sur les objets d’annuaire.

NOTE: Vous devez encoder le caractère réservé « # » dans la valeur userPrincipalName en tant que « %23 » dans l’URL de la requête. Pour plus d’informations, consultez Encodage de caractères spéciaux.

GET https://graph.microsoft.com/v1.0/users?$select=id,displayName,mail,identities&$filter=endsWith(userPrincipalName,'%23EXT%23@contoso.com')&$count=true
ConsistencyLevel: eventual

Réponse

L’exemple suivant illustre la 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(id,displayName,mail,identities)",
    "@odata.count": 2,
    "value": [
        {
            "id": "39807bd1-3dde-48f3-8165-81ddd4e46de0",
            "displayName": "Adele Vance",
            "mail": "AdeleV@adatum.com",
            "identities": [
                {
                    "signInType": "userPrincipalName",
                    "issuer": "contoso.com",
                    "issuerAssignedId": "AdeleV_adatum.com#EXT#@cntoso.com"
                }
            ]
        }
    ]
}

Exemple 9 : Utiliser $filter pour obtenir des utilisateurs auxquels une licence spécifique est attribuée

Demande

L’exemple suivant illustre une 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

L’exemple suivant illustre la 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"
        }
      ]
    }
  ]
}

Exemple 10 : Obtenir la valeur d’une extension de schéma pour tous les utilisateurs

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

Demande

GET https://graph.microsoft.com/v1.0/users?$select=ext55gb1l09_msLearnCourses

Réponse

Dans la réponse suivante, la propriété d’extension ext55gb1l09_msLearnCourses de schéma n’est pas assignée dans deux des objets utilisateur.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(ext55gb1l09_msLearnCourses)",
    "value": [
        {},
        {
            "ext55gb1l09_msLearnCourses": {
                "@odata.type": "#microsoft.graph.ComplexExtensionValue",
                "courseType": "Developer",
                "courseName": "Introduction to Microsoft Graph",
                "courseId": 1
            }
        },
        {}
    ]
}

Remarque : Vous pouvez également appliquer la $filter propriété d’extension de schéma pour récupérer des objets pour lequel une propriété de la collection correspond à une valeur spécifiée. La syntaxe pour cela est /users?$filter={schemaPropertyID}/{propertyName} eq 'value'. Par exemple : GET /users?$select=ext55gb1l09_msLearnCourses&$filter=ext55gb1l09_msLearnCourses/courseType eq 'Developer'. Les opérateurs eq et les not opérateurs sont pris en charge.

Exemple 11 : Obtenir les utilisateurs, y compris leur heure de dernière connexion

Demande

L’exemple suivant illustre une demande. Les détails de la propriété signInActivity nécessitent une licence Microsoft Entra ID P1 ou P2 et l’autorisation AuditLog.Read.All.

Note: Lorsque vous spécifiez $select=signInActivity ou $filter=signInActivity lors de la liste des utilisateurs, la taille de page maximale pour $top est de 120. Les requêtes dont $top le paramètre est supérieur à 120 retournent des pages avec jusqu’à 120 utilisateurs. signInActivity prend en charge $filter (eq, ne, not, ge, le), mais pas avec d’autres propriétés filtrables.

GET https://graph.microsoft.com/v1.0/users?$select=displayName,userPrincipalName,signInActivity

Réponse

L’exemple suivant illustre la 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(displayName,userPrincipalName,signInActivity)",
  "value": [
    {
      "displayName": "Adele Vance",
      "userPrincipalName": "AdeleV@contoso.com",
      "id": "1aecaf40-dc3a-461f-88a8-d06994e12898",
      "signInActivity": {
        "lastSignInDateTime": "2021-06-17T16:41:33Z",
        "lastSignInRequestId": "d4d31c40-4c36-4775-ad59-7d1e6a171f00",
        "lastNonInteractiveSignInDateTime": "0001-01-01T00:00:00Z",
        "lastNonInteractiveSignInRequestId": ""
      }
    },
    {
      "displayName": "Alex Wilber",
      "userPrincipalName": "AlexW@contoso.com",
      "id": "f0662ee5-84b1-43d6-8338-769cce1bc141",
      "signInActivity": {
        "lastSignInDateTime": "2021-07-29T15:53:27Z",
        "lastSignInRequestId": "f3149ee1-e347-4181-b45b-99a1f82b1c00",
        "lastNonInteractiveSignInDateTime": "2021-07-29T17:53:42Z",
        "lastNonInteractiveSignInRequestId": "868efa6a-b2e9-40e9-9b1c-0aaea5b50200"
      }
    }
  ]
}