Utilisation de paramètres de requête pour personnaliser des réponses

Microsoft Graph prend en charge des paramètres de requête facultatifs que vous pouvez utiliser pour spécifier et contrôler la quantité de données renvoyées dans une réponse. La prise en charge des paramètres exacts de la requête varie d’une opération API à l’autre, et peut différer entre les points de terminaison v1.0 et bêta en fonction de l’API.

Conseil

Sur le point de terminaison bêta, le préfixe $ est facultatif. Par exemple, plutôt que d’utiliser $filter, vous pouvez utiliser filter. Sur le point de terminaison v1, le préfixe $ est facultatif pour un sous-ensemble d’API uniquement. Pour simplifier, incluez toujours $ si vous utilisez le point de terminaison v1.

Les paramètres de la requête peuvent être des options de requête de système OData ou d’autres paramètres de requête.

Options de requête de système OData

Une opération API Microsoft Graph peut prendre en charge une ou plusieurs des options de requête de système OData suivantes. Ces options de requête sont compatibles avec le langage de requêtes OData V4.

Remarque : OData 4.0 prend en charge les options de requête système uniquement dans les opérations GET.

Cliquez sur les exemples pour les essayer dans l’Afficheur Graph.

Nom Description Exemple
$count Récupère le nombre total de ressources correspondantes. /me/messages?$top=2&$count=true
$expand Récupère les ressources connexes. /groups?$expand=members
$filter Filtre les résultats (lignes). /users?$filter=startswith(givenName,'J')
$format Renvoie les résultats dans le format de média spécifié. /users?$format=json
$orderby Classe les résultats. /users?$orderby=displayName desc
$search Renvoie les résultats en fonction des critères de recherche. /me/messages?$search=pizza
$select Filtre les propriétés (colonnes). /users?$select=givenName,surname
$skip Établit l’index dans un ensemble de résultats. Également utilisé par certaines API pour implémenter la pagination. Peut être utilisé avec $top pour effectuer la pagination manuellement. /me/messages?$skip=11
$top Définit la taille de la page de résultats. /users?$top=2

Autres paramètres de requête

Nom Description Exemple
$skipToken Récupère la page de résultats suivante à partir des ensembles de résultats qui s’étendent sur plusieurs pages. (Certaines API utilisent $skip à la place.) /users?$skiptoken=X%274453707402000100000017...

Autres fonctionnalités des URL OData

Les fonctionnalités OData 4.0 ci-après sont des segments d’URL, et non des paramètres de requête.

Nom Description Exemple
$count Récupère l’entier total de la collection. GET /users/$count
GET /groups/{id}/members/$count
$ref Met à jour l’appartenance d'entités à une collection. POST /groups/{id}/members/$ref
$value Récupère ou met à jour la valeur binaire d’un élément. GET /me/photo/$value

Codage des paramètres de requête

Les valeurs des paramètres de requête doivent être codées en pourcentage. Un bon nombre de clients HTTP, de navigateurs et d’outils (par exemple, l’Afficheur Graph) vous aideront dans cette opération. Une requête peut échouer en raison d’un codage inapproprié des valeurs des paramètres de requête.

Une URL non codée ressemble à ceci :

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName, 'J')

Une URL correctement codée ressemble à ceci :

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName%2C+'J')

Échappement de guillemets simples

Pour les demandes nécessitant des guillemets simples, si les valeurs de n’importe quel paramètre contiennent également des guillemets simples, ces derniers doivent être en double échappement, faute de quoi la demande échouera en raison d’une syntaxe invalide.Dans l’exemple, la valeur de chaîne let''s meet for lunch?a le guillemet simple placé dans une séquence d’échappement.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=subject eq 'let''s meet for lunch?'

paramètre count

Utilisez le paramètre de requête $count pour inclure le nombre total d’éléments dans une collection, ainsi que la page des valeurs de données renvoyées par Microsoft Graph.

Notes

$count peut également être utilisé en tant que segment d’URL pour récupérer l’entier total de la collection. Sur les ressources qui dérivent de directoryObject , est-elle uniquement prise en charge dans une requête avancée. Voir Fonctionnalités de requête avancée dans des objets annuaire Azure AD.

L’utilisation de $count n’est pas prise en charge chez les clients Azure AD B2C.

Par exemple, la requête suivante renvoie la collection contact de l’utilisateur actuel et le nombre d’éléments dans la collection contact de la propriété @odata.count.

GET  https://graph.microsoft.com/v1.0/me/contacts?$count=true

Le paramètre de requête $count est pris en charge pour ces collections de ressources et leurs relations dérivant de directoryObject et uniquement dans les requêtes avancées :

paramètre expand

De nombreuses ressources Microsoft Graph présentent des propriétés déclarées, ainsi que leurs relations avec les autres ressources. Ces relations sont également appelées propriétés de référence ou propriétés de navigation. Elles peuvent faire référence à une ressource unique ou à une collection de ressources. Par exemple, les dossiers de courrier, le gestionnaire et les collaborateur directs d’un utilisateur sont tous présentés comme relations.

Normalement, vous pouvez interroger soit les propriétés d’une ressource, soit l’une de ses relations dans une demande unique, mais pas les deux. Vous pouvez utiliser le $expandparamètre de chaîne de requête pour inclure la collection ou la ressource développée qui est référencée par une seule relation (propriété de navigation) dans vos résultats. Une seule relation peut être développée dans une seule requête..

L’exemple suivant indique comment obtenir les informations sur le lecteur racine, ainsi que les éléments enfants de niveau supérieur dans un lecteur :

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children

Avec certaines collections de ressources, vous pouvez également spécifier les propriétés à renvoyer dans les ressources développées en ajoutant un paramètre $select. L’exemple suivant effectue la même requête que dans l’exemple précédent, mais utilise une instruction $select afin de limiter les propriétés renvoyées pour les éléments enfants développés dans les propriétés id et name.

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children($select=id,name)

Notes

Les relations et les ressources ne prennent pas toutes en charge $expandle paramètre de requête. Par exemple, vous pouvez développer les relations directReports, manager et memberOf sur un utilisateur, mais vous ne pouvez pas développer ses relations events, messages ou photo. Les ressources ou les relations ne prennent pas toutes en charge l’utilisation de $select sur des éléments développés.

Avec des ressources Azure AD qui dérivent de directoryObject, telles que les utilisateurs et les groupes, $expand renvoie généralement un maximum de 20 éléments correspondant à la relation développée et n’a aucun @odata.nextLink. Consultez d’autres problèmes connus.

paramètre filter

Utilisez le paramètre de requête $filter pour récupérer uniquement un sous-ensemble d’une collection. Le paramètre de requête $filter peut également être utilisé pour récupérer des relations telles que membres, memberOf, transitiveMembers et transitiveMemberOf. Par exemple, obtenez tous les groupes de sécurité dont je suis membre.

L’exemple suivant recherche les utilisateurs dont le nom d’affichage commence par la lettre « J » :

GET https://graph.microsoft.com/v1.0/users?$filter=startsWith(displayName,'J')

La prise en charge des opérateurs $filter varie entre les API Microsoft Graph. Les opérateurs logiques suivants sont généralement pris en charge :

Type d'opérateur Opérateur
Opérateurs d’égalité
  • égal à eq
  • n’est pas égal à ne
  • Négation not
  • dans in
Opérateurs relationnels
  • inférieur à lt
  • supérieur à gt
  • inférieur ou égal à le
  • supérieur ou égal à ge
Opérateurs lambda
  • n’importe quel any
  • tous les all
Opérateurs conditionnels
  • et and
  • ou or
Fonctions
  • Commence par startsWith
  • Se termine par endsWith
  • Contient contains

Remarque : la prise en charge de ces opérateurs varie en fonction de l’entité et certaines propriétés prennent en charge $filter uniquement dans les requêtes avancées. Consultez la documentation d’une entité spécifique pour des détails.

Filtrage en utilisant des opérateurs lambda

OData définit les opérateurs any et all pour évaluer les correspondances sur des propriétés à plusieurs valeurs, à savoir, une collection de valeurs primitives telles que les types de Chaîne ou une collection d’entités.

L’opérateurany applique de façon répétée une expression booléenne à chaque membre d’une collection et renvoie true si l’expression est true pour tous les membres de la collection, sinon elle retourne false. Voici la syntaxe de l’anyopérateur :

$filter=param/any(var:var/subparam eq 'value-to-match')

  • param est la propriété contenant une collection de valeurs ou une collection d’entités.
  • var:var est une variable de plage qui conserve l’élément actuel de la collection au cours de l’itération. Cette variable peut comporter quasiment n’importe quel nom, par exemple, adele:adele ou x:x.
  • subparam est requise quand la requête s’applique à une collection d’entités. Elle représente la propriété du type complexe dont nous faisons correspondre la valeur.
  • value-to-match représente le membre de la collection sur lequel nous faisons une correspondance.

Par exemple, la imAddresses propriété de la ressource utilisateur contient une collection de type primitif String. La requête suivante récupère uniquement les utilisateurs ayant une imAddress de admin@contoso.com.

GET https://graph.microsoft.com/v1.0/users?$filter=imAddresses/any(s:s eq 'admin@contoso.com')

La propriété assignedLicenses de la ressource utilisateur contient une collection d’objets assignedLicense, un type complexe avec deux propriétés, skuId et disabledPlans. La requête suivante récupère uniquement les utilisateurs ayant une licence affectée identifiée par skuId 184efa21-98c3-4e5d-95ab-d07053a96e67.

GET https://graph.microsoft.com/v1.0/users?$filter=assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)

Pour inverser le résultat de l’expression dans la clause any, utilisez l’opérateur NOT, et non pas l’opérateur ne. Par exemple, la requête suivante récupère uniquement les utilisateurs dont imAddress de admin@contoso.com n’est pas affectée.

Remarque : Pour les objets d’annuaire tels que les utilisateurs, les opérateurs NOT et ne sont pris en charge uniquement dans requêtes avancées.

GET https://graph.microsoft.com/v1.0/users?$filter=NOT(imAddresses/any(s:s eq 'admin@contoso.com'))&$count=true
ConsistencyLevel: eventual

L’opérateur all applique une expression booléenne à chaque membre d’une collection et renvoie true si l’expression est true pour tous les membres de la collection, sinon elle retourne false. Elle n’est prise en charge par aucune propriété.

Exemples utilisant l’opérateur de requête filtre

Le tableau suivant répertorie quelques exemples où le paramètre de requête $filter est utilisé. Pour plus de détails sur la syntaxe $filter, reportez-vous au protocole OData.

Remarque : Cliquez sur les exemples pour essayer l’Afficheur Graph.

Description Exemple
Trouver toutes les utilisatrices qui s’appellent Mary dans plusieurs propriétés. GET ../users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')
Trouver tous les utilisateurs du domaine d’e-mail « hotmail.com » OBTENIR ../users?$count=true&$filter=endsWith(mail,'@hotmail.com'). Il s’agit d’une requête avancée.
Obtenir tous les événements de l’utilisateur connecté qui commencent après le 01/07/2017.
GET ../me/events?$filter=start/dateTime ge '2017-07-01T08:00'.
REMARQUE : La propriété dateTime est de type String.
Obtenir tous les messages électroniques provenant d’une adresse spécifique reçus par l’utilisateur connecté. GET ../me/messages?$filter=from/emailAddress/address eq 'someuser@example.com'
Obtenir tous les messages électroniques reçus par l’utilisateur connecté en avril 2017. GET ../me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01
Obtenir tous les messages non lus dans la boîte de réception de l’utilisateur connecté. GET ../me/mailFolders/inbox/messages?$filter=isRead eq false
Obtenir tous les utilisateurs dans les services Vente au détail et Ventes.
GET ../users?$filter=department in ('Retail', 'Sales')
Répertorie les utilisateurs avec un plan de services particulier qui est dans un état suspendu. OBTENIR ../users?$filter=assignedPlans/any(a:a/servicePlanId eq 2e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2 and a/capabilityStatus eq 'Suspended')&$count=true. Il s’agit d’une requête avancée.
Répertorier tous les groupes non Microsoft 365 dans une organisation. OBTENIR ../groups?$filter=NOT groupTypes/any(c:c eq 'Unified')&$count=true. Il s’agit d’une requête avancée.
Répertorier tous les utilisateurs dont le nom de l’entreprise n’est pas indéfini (autrement dit, n’est pas une valeur null) ou Microsoft. OBTENIR ../users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true. Il s’agit d’une requête avancée.
Répertorier tous les utilisateurs dont le nom de l’entreprise est indéfini ou Microsoft. OBTENIR ../users?$filter=companyName in (null, 'Microsoft')&$count=true. Il s’agit d’une requête avancée.
Utilisez la conversion OData pour obtenir un abonnement transitif dans les groupes avec un nom complet commençant par « a », y compris le nombre d’objets retournés. OBTENIR ../me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a'). Il s’agit d’une requête avancée.

paramètre format

Pour spécifier le format de média des éléments renvoyés à partir de Microsoft Graph, utilisez le paramètre de requête $format.

Par exemple, la requête suivante renvoie les utilisateurs de l’organisation au format json :

GET https://graph.microsoft.com/v1.0/users?$format=json

Remarque : Le paramètre de requête $format prend en charge certains formats (par exemple : atom, xml et json), mais les résultats ne peuvent pas être renvoyés dans tous les formats.

paramètre orderby

Utilisez le paramètre de requête $orderby pour spécifier l’ordre de tri des éléments renvoyés à partir de Microsoft Graph. L’ordre par défaut est l’ordre croissant.

Par exemple, la requête suivante renvoie les utilisateurs de l’organisation classés par nom d’affichage :

GET https://graph.microsoft.com/v1.0/users?$orderby=displayName

Vous pouvez également trier par entités de type complexe. La demande suivante obtient les messages et les trie en fonction du champ address de la propriété from, qui est de type complexe emailAddress :

GET https://graph.microsoft.com/v1.0/me/messages?$orderby=from/emailAddress/address

Pour trier les résultats dans l’ordre croissant ou décroissant, ajoutez asc ou desc au nom de champ, séparé par un espace ; par exemple, ?$orderby=name%20desc. Si l’ordre de tri n’est pas spécifié, la valeur par défaut (ordre croissant) est déduite.

Par exemple, la requête suivante trie les messages dans la boîte de réception de l’utilisateur, d’abord en fonction du nom de l’expéditeur dans l’ordre décroissant (de Z à A), puis par objet dans l’ordre croissant (par défaut).

GET https://graph.microsoft.com/v1.0/me/mailFolders/Inbox/messages?$orderby=from/emailAddress/name desc,subject

Remarque : Quand vous spécifiez le paramètre $filter, le serveur détermine un ordre de tri pour les résultats. Si vous utilisez $orderby et $filter pour obtenir des messages, étant donné que le serveur déduit toujours un ordre de tri pour les résultats d’un système $filter, vous devez spécifier des propriétés de certaines manières.

L’exemple suivant montre une requête filtrée sur les propriétés subject et importance, puis triées sur les propriétés subject, importance et receivedDateTime dans l’ordre décroissant.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=Subject eq 'welcome' and importance eq 'normal'&$orderby=subject,importance,receivedDateTime desc

Notes

L’association des paramètres de requête $orderby et $filter est prise en charge pour les objets annuaire. Voir Fonctionnalités de requête avancée dans des objets annuaire Azure AD.

paramètre search

Pour limiter les résultats d’une requête qui répondent à un critère de recherche, utilisez le paramètre de requête $search. Sa syntaxe et son comportement varie d’une opération d’API à l’autre. Pour voir la syntaxe pour $search dans plusieurs ressources, voir Utiliser le paramètre de requête $search pour mettre en correspondance un critère de recherche.

paramètre select

Utilisez le paramètre de requête $select pour renvoyer un ensemble de propriétés qui sont différentes de l’ensemble par défaut pour une ressource unique ou pour une collection de ressources. Avec $select, vous pouvez spécifier un sous-ensemble ou un sur-ensemble des propriétés par défaut.

Par exemple, lorsque vous récupérez les messages de l’utilisateur connecté, vous pouvez indiquer que seules les propriétés from et subject doivent être renvoyées :

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject

Important : en règle générale, nous recommandons d’utiliser $select afin de limiter les propriétés renvoyées par une requête à celles requises par votre application. C’est notamment le cas des requêtes pouvant potentiellement renvoyer un ensemble de résultats volumineux. Limiter les propriétés renvoyées dans chaque ligne permet de réduire la charge réseau et d’améliorer les performances de votre application.

Dans v1.0, certaines ressources Azure AD issues de directoryObject, telles que les utilisateurs et les groupes, renvoient un sous-ensemble limité par défaut de propriétés sur les opérations de lecture. Pour ces ressources, vous devez utiliser $select afin de renvoyer les propriétés hors ensemble par défaut.

paramètre skip

Utilisez le paramètre de requête $skip pour définir le nombre d’éléments à ignorer au début d’une collection. Par exemple, la requête suivante renvoie les événements pour l’utilisateur triés par date de création, en commençant par le 21e événement de la collection :

GET  https://graph.microsoft.com/v1.0/me/events?$orderby=createdDateTime&$skip=20

Remarque : certaines API Microsoft Graph, comme Courrier et calendrier Outlook (message, event et calendar), utilisent $skip pour mettre en œuvre la pagination. Lorsque les résultats d’une requête s’étendent sur plusieurs pages, ces API renvoient une propriété @odata:nextLink avec une URL contenant un paramètre $skip. Vous pouvez utiliser cette URL pour renvoyer la page de résultats suivante. Pour plus d’informations, consultez la rubrique relative à la pagination.

L’en-tête ConsistencyLevel requis pour les requêtes avancées sur les objets annuaire n’est pas inclus par défaut dans les requêtes de page suivantes.Il doit être défini explicitement dans les pages suivantes.

paramètre skipToken

Certaines requêtes renvoient plusieurs pages de données, soit en raison de la pagination côté serveur, soit en raison de la pagination côté serveur, soit en raison de l’utilisation du paramètre $top visant à limiter la taille de la page de la réponse. De nombreuses API Microsoft Graph utilisent le paramètre de requête skipToken pour référencer les pages suivantes du résultat.
Le paramètre $skiptoken contient un jeton opaque qui fait référence à la page de résultats suivante et est renvoyé dans l’URL indiquée dans la propriété @odata.nextLink de la réponse. Pour en savoir plus, consultez Paramètre.

Remarque : si vous utilisez le compte OData (ajout de $count=true dans la chaîne de requête) pour les requêtes dans les objets annuaire, la propriété @odata.count est présente uniquement dans la première page.

L’en-tête ConsistencyLevel requis pour les requêtes avancées sur les objets annuaire n’est pas inclus par défaut dans les requêtes de page suivantes.Il doit être défini explicitement dans les pages suivantes.

paramètre top

Utilisez le paramètre $top pour spécifier la taille de la page de l’ensemble de résultats.

S’il reste plusieurs éléments dans l’ensemble de résultats, le corps de la réponse contient un paramètre @odata.nextLink. Ce paramètre contient une URL que vous pouvez utiliser pour obtenir la page de résultats suivante. Pour plus d’informations, consultez la rubrique relative à la pagination.

La valeur minimale de $top est 1, et la valeur maximale dépend de l’API correspondante.

Par exemple, la requête liste messages suivante renvoie les cinq premiers messages dans la boîte aux lettres de l’utilisateur :

GET https://graph.microsoft.com/v1.0/me/messages?$top=5

L’en-tête ConsistencyLevel requis pour les requêtes avancées sur les objets annuaire n’est pas inclus par défaut dans les requêtes de page suivantes.Il doit être défini explicitement dans les pages suivantes.

Gestion des erreurs pour les paramètres de requête

Certaines requêtes renvoient un message d’erreur si un paramètre de requête spécifié n’est pas pris en charge. Par exemple, vous ne pouvez pas utiliser $expand dans la relation user/photo.

https://graph.microsoft.com/v1.0/me?$expand=photo
{
    "error":{
        "code":"ExpandNotSupported",
        "message":"Expand is not allowed for property 'Photo' according to the entity schema.",
        "innerError":{
            "request-id":"1653fefd-bc31-484b-bb10-8dc33cb853ec",
            "date":"2017-07-31T20:55:01"
        }
    }
}

Toutefois, il est important de noter que les paramètres spécifiés dans une requête peuvent échouer silencieusement. Ce peut être le cas de paramètres de requête non pris en charge, ainsi que d’associations de paramètres de requête non prises en charge. Dans ce cas, vous devez examiner les données renvoyées par la requête afin de déterminer si les paramètres de requête que vous avez spécifiés ont eu l’effet souhaité.

Consultez également