Table of contents

Options de requêtes, de filtres et de pagination prises en charge | Concepts de l’API Graph

Jimaco Brannian|Dernière mise à jour: 05/09/2016
|
1 Contributeur

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

La fonctionnalité d’API Azure AD Graph est également disponible au moyen de Microsoft Graph, une API unifiée qui intègre aussi des API d’autres services Microsoft tels que Outlook, OneDrive, OneNote, Planner et Office Graph, tous accessibles par le biais d’un seul point de terminaison à l’aide d’un seul jeton d’accès.

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 prise 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. 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. 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. 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.

$orderby

$orderby trie les objets renvoyés par le paramètre spécifié. Exemples de demandes utilisant l’option $orderby :

DemandeDescription
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6Renvoie une liste d’utilisateurs classés par nom d’affichage.
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6Renvoie 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 :

DemandeDescription
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6Renvoie l’objet groupe ainsi que ses membres.
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6Renvoie l’objet utilisateur ainsi que ses collaborateurs directs.
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6Renvoie 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 :

DemandeDescription
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 :

DemandeDescription
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=trueLe 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 :

  1. 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.
  2. 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.
  3. 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.
  4. 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érieurRésultats de la requêteURI (pour contoso.com)
Ressources de niveau supérieurRetourne 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
ContactsRetourne les informations sur les contacts d’organisationhttps://graph.windows.net/contoso.com/contacts?api-version=1.6
UtilisateursRetourne les informations utilisateurhttps://graph.windows.net/contoso.com/users?api-version=1.6
GroupesRetourne les données des groupeshttps://graph.windows.net/contoso.com/groups?api-version=1.6
Rôles d’annuaireRetourne tous les rôles d’annuaire activés dans le locatairehttps://graph.windows.net/contoso.com/directoryRoles?api-version=1.6
SubscribedSkusRetourne les abonnements du locatairehttps://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6
Métadonnées d’annuaireRetourne 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êteURI (pour contoso.com)
Répertorier tous les utilisateurs et groupeshttps://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 userPrincipalNamehttps://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 surnamehttps://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’objectIdhttps://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6
Récupérer le gestionnaire d’un utilisateurhttps://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 utilisateurhttps://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 utilisateurhttps://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 groupehttps://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 groupehttps://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 B2Chttps://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@exemple.com » dans un locataire Azure Active Directory B2Chttps://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

© 2017 Microsoft