Options de requêtes, de filtres et de pagination prises en charge | Concepts de l’API Graph
Cette rubrique répertorie les options de requête, les filtres et les opérations de pagination que vous pouvez utiliser avec l’API Azure Active Directory (AD) Graph. La section finale offre plusieurs exemples de requêtes courantes que vous pouvez exécuter avec l’API Azure AD Graph.
Important
Nous vous recommandons fortement d’utiliser Microsoft Graph plutôt que l’API Graph Azure AD pour accéder aux ressources Azure Active Directory. Nos efforts de développement sont désormais axés sur Microsoft Graph et aucune autre amélioration n’est prévue pour l’API Graph Azure AD. Il existe un nombre très limité de scénarios pour lesquels l’API Graph Azure AD peut être encore appropriée ; pour plus d’informations, consultez le billet de blog Microsoft Graph ou l’API Azure AD dans le Centre de développement Office.
Adressage
Toutes les requêtes ci-dessous s’adressent au locataire à l’aide d’un nom de domaine. Vous pouvez remplacer contoso.com par l’un des noms de domaine inscrits de votre locataire avec votre ID de locataire (GUID) ou avec l’alias MyOrganization (pour l’accès délégué). Dans certains cas, vous pouvez utiliser l’alias me. Pour obtenir des informations sur les façons de s’adresser au locataire, consultez Présentations des opérations.
Options de requête prises en charge
Graph prend en charge les options de requête suivantes : $filter, $orderby, $expand, $top et $format. Les options de requête suivantes ne sont pas prises en charge pour le moment : $count, $inlinecount et $skip.
$filter
Les restrictions générales suivantes s’appliquent aux requêtes qui contiennent un filtre :
$filter ne peut pas être combiné avec des expressions $orderby.
Le filtrage n’est pas pris en charge pour les requêtes sur les objets d’annuaire [DirectoryRole] ou [SubscribedSku].
Toutes les propriétés des objets de répertoire pris en charge ne peuvent pas être utilisées dans une expression de filtre. Pour plus d’informations sur les propriétés filtrables des types pris en charge, consultez [User], [Group] et contact.
Les restrictions suivantes s’appliquent aux expressions de filtre :
Opérateurs logiques : and (et) et or (ou) sont pris en charge. Par exemple :
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=accountEnabled eq true and (userPrincipalName eq 'jonlawr@contoso.com' or mail eq 'jonlawr@contoso.com')Opérateurs de comparaison : eq (égal à), ge (supérieur ou égal à) et le (inférieur ou égal à) sont pris en charge.
startswith est pris en charge. Par exemple :
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')any est pris en charge lors de l’interrogation de propriétés à valeurs multiples. Par exemple :
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=userPrincipalName eq 'Mary@Contoso.com' or proxyAddresses/any(c:c eq 'smtp:Mary@Contoso.com')Opérateurs arithmétiques : non pris en charge.
Fonctions : non prises en charge.
Les valeurs null ne sont pas prises en charge comme opérande dans les expressions de filtre. Par exemple, vous ne pouvez pas spécifier de valeur null pour filtrer pour les propriétés non définies.
Pour filtrer sur une propriété binaire, comme issuerUserId dans userIdentities, la valeur doit d’abord être codée en Base64 avant de pouvoir être utilisée dans la chaîne $filter.
$orderby
$orderby trie les objets renvoyés par le paramètre spécifié. Exemples de demandes utilisant l’option $orderby :
| Demande | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6 |
Renvoie une liste d’utilisateurs classés par nom d’affichage. |
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6 |
Renvoie la liste des 50 premiers utilisateurs classés par nom d’affichage. |
Les restrictions suivantes s’appliquent aux expressions $orderby :
Deux ordres de tri sont actuellement pris en charge : DisplayName pour les objets [User] et [Group], et UserPrincipalName pour les objets [User]. Le critère de tri par défaut pour les utilisateurs est UserPrincipalName.
$orderby ne peut pas être combiné avec des expressions $filter.
$expand
$expand renvoie un objet et ses objets liés. Exemples de demandes utilisant l’option $expand :
| Demande | Description |
|---|---|
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6 |
Renvoie l’objet groupe ainsi que ses membres. |
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6 |
Renvoie l’objet utilisateur ainsi que ses collaborateurs directs. |
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6 |
Renvoie l’objet utilisateur ainsi que son gestionnaire. |
Les restrictions suivantes s’appliquent aux expressions $expand :
- Le nombre maximal d’objets renvoyés pour une demande est de 20.
$top
$top n’est pas pris en charge pour les requêtes sur les objets d’annuaire [DirectoryRole] ou [SubscribedSku].
Prise en charge de la pagination
Vous pouvez naviguer vers l’avant et l’arrière dans les pages du Graph. Une réponse contenant des résultats paginés inclut un jeton d’évitement (odata.nextLink) permettant d’obtenir la page de résultats suivante. Ce jeton d’évitement peut être combiné avec un argument de requête previous-page=true pour remonter d’une page.
L’exemple de requête suivant illustre la pagination vers l’avant :
| Demande | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000' |
Le paramètre $skiptoken de la réponse précédente est inclus, qui vous permet d’accéder à la page de résultats suivante. |
L’exemple de requête suivant illustre la pagination vers l’arrière :
| Demande | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true |
Le paramètre $skiptoken de la réponse précédente est inclus. En cas de combinaison avec le paramètre &previous-page=true, la page de résultats précédente est récupérée. |
Les étapes suivantes montrent le flux de demandes/réponses pour la pagination vers l’avant et l’arrière :
- Une demande est faite pour obtenir la liste des 10 premiers utilisateurs sur 15. La réponse contient un jeton d’évitement pour indiquer la page finale de 10 utilisateurs.
- Pour obtenir les 5 utilisateurs finaux, une autre demande est faite, qui contient le jeton d’évitement renvoyé par la réponse précédente.
- Pour remonter d’une page, une demande est faite à l’aide du jeton d’évitement renvoyé à l’étape 1, et le paramètre &previous-page=true est ajouté à la demande.
- La réponse contient la page précédente (première) de 10 utilisateurs. Dans un autre scénario où il resterait plus de pages, un nouveau jeton d’évitement serait renvoyé. Ce nouveau jeton d’évitement peut être ajouté à la demande en même temps que &previous-page=true pour remonter de nouveau d’une page.
Les restrictions suivantes s’appliquent aux demandes paginées :
- La taille de page par défaut est 100. La taille de page maximale est 999.
- Les requêtes sur des rôles ne prennent pas en charge la pagination. Cela inclut la lecture des objets de rôle mêmes, ainsi que des membres de rôle.
- La création de liste de ressources, telle qu’une recherche de tous les utilisateurs d’un locataire (/users), ne prend pas en charge la pagination. Par exemple :
https://graph.windows.net/contoso.com/users?api-version=1.6. Toutefois, quel que soit le type, quand un filtre est appliqué, la pagination n’est pas prise en charge et seule la première page de résultats est renvoyée. - La pagination pour les recherches de lien, par exemple, pour l’appartenance aux groupes, n’est pas prise en charge. Par exemple :
https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.
Ordre de tri
- Le jeu de résultats d’une requête portant sur tous les utilisateurs est ordonné en fonction de la propriété UserPrincipalName. Par exemple :
https://graph.windows.net/contoso.com/users?api-version=1.6. - Le jeu de résultats d’une requête portant sur toutes les autres ressources de niveau supérieur, telles que les groupes et les contacts, est ordonné en fonction de la propriété objectId. Par exemple :
https://graph.windows.net/contoso.com/groups?api-version=1.6. - Le tri des résultats des requêtes autres que pour les ressources de niveau supérieur est indéterminé.
Requêtes courantes
Les sections suivantes présentent quelques exemples de requêtes courantes que vous pouvez effectuer avec l’API Graph.
Interrogation des ressources de niveau supérieur
Les requêtes suivantes montrent comment accéder à des ressources de niveau supérieur dans l’API Graph en utilisant contoso.com comme exemple de locataire. Notez qu’un en-tête Authorization qui contient un jeton de support valide provenant d’Azure AD doit exécuter des requêtes sur un locataire.
| Ressource de niveau supérieur | Résultats de la requête | URI (pour contoso.com) |
|---|---|---|
| Ressources de niveau supérieur | Retourne la liste d’URI des ressources de niveau supérieur pour les services d’annuaire (également répertoriés ci-dessous) | https://graph.windows.net/contoso.com?api-version=1.6 |
| Informations sur la société | Retourne les informations sur la société | https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 |
| Contacts | Retourne les informations sur les contacts d’organisation | https://graph.windows.net/contoso.com/contacts?api-version=1.6 |
| Utilisateurs | Retourne les informations utilisateur | https://graph.windows.net/contoso.com/users?api-version=1.6 |
| Groupes | Retourne les données des groupes | https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Rôles d’annuaire | Retourne tous les rôles d’annuaire activés dans le locataire | https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6 |
| SubscribedSkus | Retourne les abonnements du locataire | https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6 |
| Métadonnées d’annuaire | Retourne un document de métadonnées de service qui décrit le modèle de données (c’est-à-dire, structure et organisation des ressources d’annuaire) | https://graph.windows.net/contoso.com/$metadata?api-version=1.6 |
Autres opérations de requête
Le tableau suivant présente quelques autres exemples de requêtes d’API Graph utilisant contoso.com en tant qu’exemple de locataire.
| Opération de requête | URI (pour contoso.com) |
|---|---|
| Répertorier tous les utilisateurs et groupes | https://graph.windows.net/contoso.com/users?api-version=1.6 https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Récupérer un utilisateur en spécifiant l’objectId ou le userPrincipalName | https://graph.windows.net/contoso.com/users/d1f67a6c-02c9-4fe5-81fb-58160ce24fe5?api-version=1.6 https://graph.windows.net/contoso.com/users/admin@contoso.com?api-version=1.6 |
| Demander et filtrer un utilisateur dont le displayName est égal à « Jon Doe » | https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 |
| Demander et filtrer des utilisateurs dont le firstName est égal à « Jon » | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6 |
| Filtrer sur les valeurs givenName et surname | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6 |
| Récupérer un groupe en spécifiant l’objectId | https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6 |
| Récupérer le gestionnaire d’un utilisateur | https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6 |
| Récupérer la liste des collaborateurs directs d’un utilisateur | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6 |
| Récupérer la liste des liens vers les collaborateurs directs d’un utilisateur | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6 |
| Récupérer la liste des adhérents à un groupe | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6 |
| Récupérer la liste de liens vers les membres du groupe | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6 |
| Récupérer l’appartenance aux groupes d’un utilisateur (non transitif) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6 |
| Récupérer la liste des groupes dont l’utilisateur est membre (non transitif) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6 |
| Demander et filtrer les groupes avec displayName >= "az" and <= "dz" | https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6 |
| Retourner tous les utilisateurs de comptes locaux dans un locataire Azure Active Directory B2C | https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6 |
| Retourner les utilisateurs de comptes locaux avec le nom de connexion « joe@example.com » dans un locataire B2C Azure Active Directory | https://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&api-version=1.6 |
Remarque : l’espace blanc dans la chaîne de requête doit être encodé dans l’URL avant d’envoyer une demande. Par exemple, la chaîne de requête https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 doit être codée URL comme suit : https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.
Ressources supplémentaires
contact [Contract]: ../api/entity-and-complex-type-reference.md#contract-entity [Device]: ../api/entity-and-complex-type-reference.md#device-entity [DirectoryLinkChange]: ../api/entity-and-complex-type-reference.md#directorylinkchange-entity [DirectoryObject]: ../api/entity-and-complex-type-reference.md#directoryobject-entity [DirectoryRole]: ../api/entity-and-complex-type-reference.md#directoryrole-entity [DirectoryRoleTemplate]: ../api/entity-and-complex-type-reference.md#directoryroletemplate-entity [ExtensionProperty]: ../api/entity-and-complex-type-reference.md#extensionproperty-entity [Group]: ../api/entity-and-complex-type-reference.md#group-entity [OAuth2PermissionGrant]: ../api/entity-and-complex-type-reference.md#oauth2permissiongrant-entity [ServicePrincipal]: ../api/entity-and-complex-type-reference.md#serviceprincipal-entity [SubscribedSku]: ../api/entity-and-complex-type-reference.md#subscribedsku-entity [TenantDetail]: ../api/entity-and-complex-type-reference.md#tenantdetail-entity [User]: ../api/entity-and-complex-type-reference.md#user-entity