Utilisation de paramètres de requête pour personnaliser des réponses
Article
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.
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.
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.
Pour connaître les options de requête système OData qu’une API et ses propriétés prennent en charge, 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.
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.
Combinez plusieurs requêtes HTTP dans une requête par lots.
POST /$batch
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. 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. Dans certains cas, vous devrez peut-être encoder deux fois les valeurs.
GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName, 'J')
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "startswith(givenName, 'J')";
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "startswith(givenName, 'J')";
});
GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName%2C+'J')
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "startswith(givenName, 'J')";
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "startswith(givenName, 'J')";
});
GET https://graph.microsoft.com/v1.0/users?$filter=startswith%28givenName%2C%20%27J%27%29
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "startswith(givenName, 'J')";
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "startswith(givenName, 'J')";
});
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 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?'
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "subject eq 'let''s meet for lunch?'";
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "subject eq 'let''s meet for lunch?'";
});
Import-Module Microsoft.Graph.Mail
# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Filter "subject eq 'let''s meet for lunch?'"
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 :
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.
En tant que segment d’URL permettant de récupérer uniquement le total entier de la collection. Par exemple : users/$count.
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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Contacts.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Count = true;
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ContactCollectionResponse result = graphClient.me().contacts().get(requestConfiguration -> {
requestConfiguration.queryParameters.count = true;
});
Le paramètre de requête est pris en charge pour les collections des ressources fréquemment utilisées suivantes et leurs relations qui dérivent de $countdirectoryObject et uniquement dans les requêtes avancées:
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.
En général, 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 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. 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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Root.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Expand = new string []{ "children" };
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
DriveItem result = graphClient.drives().byDriveId("{drive-id}").root().get(requestConfiguration -> {
requestConfiguration.queryParameters.expand = new String []{"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)
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Root.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Expand = new string []{ "children($select=id,name)" };
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
DriveItem result = graphClient.drives().byDriveId("{drive-id}").root().get(requestConfiguration -> {
requestConfiguration.queryParameters.expand = new String []{"children($select=id,name)"};
});
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.
GET https://graph.microsoft.com/v1.0/users?$format=json
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Format = "json";
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.format = "json";
});
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
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 renvoie les utilisateurs de l’organisation classés par nom d’affichage :
GET https://graph.microsoft.com/v1.0/users?$orderby=displayName
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Orderby = new string []{ "displayName" };
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"displayName"};
});
Vous pouvez également trier 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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Orderby = new string []{ "from/emailAddress/address" };
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"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.
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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.MailFolders["{mailFolder-id}"].Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Orderby = new string []{ "from/emailAddress/name desc","subject" };
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users mail-folders messages list --user-id {user-id} --mail-folder-id {mailFolder-id} --orderby "from/emailAddress/name desc,subject"
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().mailFolders().byMailFolderId("{mailFolder-id}").messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"from/emailAddress/name desc", "subject"};
});
Import-Module Microsoft.Graph.Mail
# A UPN can also be used as -UserId.
Get-MgUserMailFolderMessage -UserId $userId -MailFolderId $mailFolderId -Sort "from/emailAddress/name desc,subject"
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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "Subject eq 'welcome' and importance eq 'normal'";
requestConfiguration.QueryParameters.Orderby = new string []{ "subject","importance","receivedDateTime desc" };
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --filter "Subject eq 'welcome' and importance eq 'normal'" --orderby "subject,importance,receivedDateTime desc"
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "Subject eq 'welcome' and importance eq 'normal'";
requestConfiguration.queryParameters.orderby = new String []{"subject", "importance", "receivedDateTime desc"};
});
Import-Module Microsoft.Graph.Mail
# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Filter "Subject eq 'welcome' and importance eq 'normal'" -Sort "subject,importance,receivedDateTime desc"
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.
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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "from","subject" };
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"from", "subject"};
});
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 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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Events.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Orderby = new string []{ "createdDateTime" };
requestConfiguration.QueryParameters.Skip = 20;
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
EventCollectionResponse result = graphClient.me().events().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"createdDateTime"};
requestConfiguration.queryParameters.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 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.
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.
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 plus d’informations, consultez la rubrique relative à la pagination.
Remarque
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 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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Top = 5;
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.top = 5;
});
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, 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é.
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.