Partager via


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

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

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.0 , le $ préfixe est facultatif uniquement pour un sous-ensemble d’API. Par souci de simplicité, incluez $ toujours dans toutes les versions.

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ête OData V4 et sont prises en charge 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 Indexe dans un jeu de résultats. Également utilisé par certaines API pour implémenter la pagination et peut être utilisé avec $top pour pager manuellement les résultats. /me/messages?$skip=11
$top Définit la taille de la page de résultats. /users?$top=2

Pour connaître les options de requête système OData prises en charge par une API et ses propriétés, consultez la table « Propriétés » dans la page de ressources et la section « Paramètres de requête facultatifs » des opérations LIST et GET pour l’API.

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

Obtenir un nombre d’utilisateurs
$ref Met à jour l’appartenance d'entités à une collection. POST /groups/{id}/members/$ref

Ajouter un membre à un groupe
$value Récupère ou met à jour la valeur binaire d’un élément. GET /me/photo/$value

Obtenir la photo d’un utilisateur, d’un groupe ou d’une équipe
$batch Combinez plusieurs requêtes HTTP dans une requête par lots. POST /$batch

Traitement par lots JSON

Codage des paramètres de requête

Les valeurs des paramètres de requête doivent être codées en pourcentage conformément à la norme RFC 3986. Par exemple, tous les caractères réservés dans les chaînes de requête doivent être codés en pourcentage. De nombreux clients, navigateurs et outils HTTP (tels que l’Explorateur Graph) gèrent cet encodage pour vous. Si une requête échoue, l’une des causes possibles est l’échec de l’encodage approprié des valeurs des paramètres de requête. Dans certains cas, vous devez double-encoder les valeurs.

Notes

Il existe un problème connu lié à l’encodage des symboles esperluette (&) dans $search les expressions sur le point de terminaison v1.0 . Pour plus d’informations sur le problème et la solution de contournement recommandée, consultez Problème connu : $search pour les objets d’annuaire échoue pour l’esperluette encodée (&).

Par exemple, une URL non codée ressemble à ceci :

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

L’URL correctement codée en pourcentage ressemble à ceci :

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

L’URL doublement codée ressemble à ceci :

GET https://graph.microsoft.com/v1.0/users?$filter=startswith%28givenName%2C%20%27J%27%29

Échappement de guillemets simples

Pour les requêtes qui utilisent des guillemets simples, si des valeurs de paramètre contiennent également des guillemets simples, elles doivent faire l’objet d’une double séquence d’échappement ; sinon, la requête échoue en raison d’une syntaxe non valide. Dans l’exemple, la valeur de chaîne let''s meet for lunch? comporte un guillemet simple en é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 récupérer le nombre total d’éléments d’une collection ou d’une expression correspondante. $count peut être utilisé des manières suivantes :

  1. En tant que paramètre de chaîne de requête avec la syntaxe $count=true pour inclure le nombre total d’éléments dans une collection à côté de la page de valeurs de données retournées par Microsoft Graph. Par exemple : users?$count=true.
  2. En tant que segment d’URL permettant de récupérer uniquement le total entier de la collection. Par exemple : users/$count.
  3. Dans une expression $filter avec des opérateurs d’égalité pour récupérer une collection de données où la propriété filtrée est une collection vide. Consultez Utiliser le paramètre de requête $filter pour filtrer une collection d’objets.

Notes

  1. Sur les ressources qui dérivent de directoryObject, $count est uniquement pris en charge dans une requête avancée. Consultez Fonctionnalités de requête avancées sur les objets d’annuaire.
  2. L’utilisation de $count n’est pas prise en charge chez les clients Azure AD B2C.

Par exemple, la requête suivante retourne à la fois la collection de contacts de l’utilisateur actuel et le nombre d’éléments de la collection de contacts dans une propriété @odata.count .

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

Pour les objets d’annuaire, c’est-à-dire les ressources qui dérivent de directoryObject, le $count paramètre de requête est pris en charge uniquement dans les requêtes avancées.

paramètre expand

De nombreuses ressources Microsoft Graph exposent 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.

Vous pouvez utiliser le paramètre de chaîne de requête $expand 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. Pour certaines API, 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 à retourner dans les ressources développées en ajoutant un $select paramètre. L’exemple suivant exécute la même requête que l’exemple précédent, mais utilise une $select instruction pour limiter les propriétés retournées pour les éléments enfants développés aux 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 le paramètre de requête $expand. Par exemple, vous pouvez développer les relations directReports, responsable et memberOf sur un utilisateur, mais vous ne pouvez pas développer ses relations événements, messages ou photo. Les ressources ou les relations ne prennent pas toutes en charge l’utilisation de l’option $select sur les éléments développés.

  • Avec les ressources Microsoft Entra qui dérivent de directoryObject, comme user et group, $expand retourne généralement un maximum de 20 éléments pour la relation développée et n’a pas de @odata.nextLink. Pour plus d’informations, consultez Limitations des paramètres de requête.

  • $expand n’est actuellement pas pris en charge par les requêtes avancées.

paramètre filter

Utilisez le paramètre de requête $filter pour récupérer uniquement un sous-ensemble d’une collection. Pour obtenir des conseils sur l’utilisation $filterde , consultez Utiliser le paramètre de requête $filter pour filtrer une collection d’objets.

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

Notes

Le $format paramètre de requête prend en charge un certain nombre de formats (par exemple, atom, xmlet json), mais les résultats peuvent ne pas être retournés dans tous les formats.

paramètre orderby

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

Par exemple, la requête suivante retourne les utilisateurs de l’organisation classés par leur nom d’affichage dans l’ordre croissant :

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

Certaines API prennent en charge le tri par entités de type complexe. La requête suivante obtient les messages et les trie en fonction du champ d’adresse de la propriété from , qui est du 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 du champ, séparé par un espace, par exemple ( ?$orderby=name desc non codé), ?$orderby=name%20desc (encodé url). Si l’ordre de tri n’est pas spécifié, l’ordre croissant par défaut est déduit.

Avec certaines API, vous pouvez trier les résultats dans plusieurs propriétés. 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

Notes

Lorsque vous spécifiez $filter, le service déduit 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. Consultez Fonctionnalités de requête avancées dans les objets d’annuaire.

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 $select paramètre de requête pour retourner un sous-ensemble de propriétés pour une ressource. Avec $select, vous pouvez spécifier un sous-ensemble ou un sur-ensemble des propriétés par défaut.

Lorsque vous effectuez une requête GET sans utiliser $select pour limiter la quantité de données de propriétés, Microsoft Graph inclut une propriété @microsoft.graph.tips qui fournit une recommandation de bonne pratique pour l’utilisation $select similaire au message suivant :

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

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

Importante

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 la version 1.0, certaines ressources Microsoft Entra qui dérivent de directoryObject, telles que l’utilisateur et le groupe, retournent un sous-ensemble limité de propriétés par défaut lors des lectures. Pour ces ressources, vous devez utiliser $select pour retourner des propriétés en dehors de l’ensemble par défaut.

paramètre skip

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

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

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

Les objets d’annuaire tels que l’utilisateur, le groupe et l’application ne prennent pas en charge $skip.

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 l’utilisation du paramètre $top visant à limiter la taille de la page de réponse. De nombreuses API Microsoft Graph utilisent le paramètre de requête skipToken pour faire référence aux pages suivantes du résultat.
Ce paramètre contient un jeton opaque qui fait référence à la page de résultats suivante et est retourné dans l’URL fournie dans la propriété @odata.nextLink dans la réponse. Pour plus d’informations, consultez la rubrique relative à la pagination.

Notes

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 dans les objets annuaire n’est pas inclus par défaut dans les requêtes de page suivantes. Il doit être défini de manière explicite dans les pages suivantes.

paramètre top

Utilisez le $top paramètre de requête pour spécifier le nombre d’éléments à inclure dans le résultat.

S’il reste plus d’éléments dans le jeu 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

Notes

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

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

Certaines requêtes retournent 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 sur la user/photo relation.

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, parfois, les paramètres de requête spécifiés dans une requête échouent en mode silencieux. Par exemple, pour les paramètres de requête non pris en charge et pour les combinaisons 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é.