Utilisation de paramètres de requête pour personnaliser des réponsesUse query parameters to customize responses

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.Microsoft Graph supports optional query parameters that you can use to specify and control the amount of data returned in a response. 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.The support for the exact query parameters varies from one API operation to another, and depending on the API, can differ between the v1.0 and beta endpoints.

Conseil

Sur le point de terminaison bêta, le préfixe $ est facultatif.$ On the v1.0 and beta endpoints, the prefix is optional. Par exemple, plutôt que d’utiliser $filter, vous pouvez utiliser filter.For example, instead of $filter, you can use filter. Sur le point de terminaison v1, le préfixe $ est facultatif pour un sous-ensemble d’API uniquement.On the v1 endpoint, the $ prefix is optional for only a subset of APIs. Pour simplifier, incluez toujours $ si vous utilisez le point de terminaison v1.For simplicity, always include $ if using the v1 endpoint.

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.Query parameters can be OData system query options or other query parameters.

Options de requête de système ODataOData system query options

Une opération API Microsoft Graph peut prendre en charge une ou plusieurs des options de requête de système OData suivantes.A Microsoft Graph API operation might support one or more of the following OData system query options. Ces options de requête sont compatibles avec le langage de requêtes OData V4.These query options are compatible with the OData V4 query language.

Remarque : OData 4.0 prend en charge les options de requête système uniquement dans les opérations GET.Note: OData 4.0 supports system query options in only GET operations.

Cliquez sur les exemples pour les essayer dans l’Afficheur Graph.Note: Click the examples to try them in Graph Explorer.

NomName DescriptionDescription ExempleExample
$count$count Récupère le nombre total de ressources correspondantes.Retrieves the total count of matching resources. /me/messages?$top=2&$count=true
$expand$expand Récupère les ressources connexes.Retrieves related resources. /groups?$expand=members
$filter$filter Filtre les résultats (lignes).Filters results (rows). /users?$filter=startswith(givenName,'J')
$format$format Renvoie les résultats dans le format de média spécifié.Returns the results in the specified media format. /users?$format=json
$orderby$orderby Classe les résultats.Orders results. /users?$orderby=displayName desc
$search$search Renvoie les résultats en fonction des critères de recherche. Actuellement pris en charge dans les collections messages et person.Returns results based on search criteria. Currently supported on messages and person collections. /me/messages?$search=pizza
$select$select Filtre les propriétés (colonnes).Filters properties (columns). /users?$select=givenName,surname
$skip$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.Indexes into a result set. Also used by some APIs to implement paging and can be used together with $top to manually page results. /me/messages?$skip=11
$top$top Définit la taille de la page de résultats.Sets the page size of results. /users?$top=2

Autres paramètres de requêteOther query parameters

NomName DescriptionDescription ExempleExample
$skipToken$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.)Retrieves the next page of results from result sets that span multiple pages. (Some APIs use $skip instead.) /users?$skiptoken=X%274453707402000100000017...

Codage des paramètres de requêteEncoding query parameters

Les valeurs des paramètres de requête doivent être codées en pourcentage.The values of query parameters should be percent-encoded. Un bon nombre de clients HTTP, de navigateurs et d’outils (par exemple, l’Afficheur Graph) vous aideront dans cette opération.Many HTTP clients, browsers, and tools (such as the Graph Explorer) will help you with this. Une requête peut échouer en raison d’un codage inapproprié des valeurs des paramètres de requête.If a query is failing, one possible cause is failure to encode the query parameter values appropriately.

Une URL non codée ressemble à ceci :An unencoded URL looks like this:

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

Une URL correctement codée ressemble à ceci :A properly encoded URL looks like this:

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

Échappement de guillemets simplesEscaping single quotes

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.For requests that use single quotes, if any parameter values also contain single quotes, those must be double escaped; otherwise, the request will fail due to invalid syntax. Dans l’exemple, la valeur de chaîne let''s meet for lunch? comporte un guillemet simple en échappement.In the example, the string value let''s meet for lunch? has the single quote escaped.

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

paramètre countcount parameter

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.Use the $count query parameter to include a count of the total number of items in a collection alongside the page of data values returned from Microsoft Graph.

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.For example, the following request will return both the contact collection of the current user, and the number of items in the contact collection in the @odata.count property.

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

Essayer l’Afficheur GraphTry in Graph Explorer

Remarque : $count n’est pas pris en charge pour les collections de ressources qui sont issues d’objets directoryObject, telles que les collections users ou groups.Note: $count is not supported for collections of resources that derive from directoryObject like collections of users or groups.

paramètre expandexpand parameter

De nombreuses ressources Microsoft Graph présentent des propriétés déclarées, ainsi que leurs relations avec les autres ressources.Many Microsoft Graph resources expose both declared properties of the resource as well as its relationships with other resources. 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.These relationships are also called reference properties or navigation properties, and they can reference either a single resource or a collection of resources. Par exemple, les dossiers de courrier, le gestionnaire et les collaborateur directs d’un utilisateur sont tous présentés comme relations.For example, the mail folders, manager, and direct reports of a user are all exposed as relationships.

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.Normally, you can query either the properties of a resource or one of its relationships in a single request, but not both. You can use the $expand query string parameter to include the expanded resource or collection referenced by a single relationship (navigation property) in your results.

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 :The following example gets root drive information along with the top-level child items in a drive:

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

Essayer l’Afficheur GraphTry in Graph Explorer

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.With some resource collections, you can also specify the properties to be returned in the expanded resources by adding a $select parameter. The following example performs the same query as the previous example but uses a $select statement to limit the properties returned for the expanded child items to the id and name properties.

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

Essayer l’Afficheur GraphTry in Graph Explorer

Remarque : 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, 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.Note: Not all relationships and resources support the $expand query parameter. For example, you can expand the directReports, manager, and memberOf relationships on a user, but you cannot expand its events, messages, or photo relationships. Not all resources or relationships support using $select on expanded items.

Avec des ressources Azure AD issues de directoryObject, telles que les utilisateurs et les groupes, $expand est uniquement pris en charge pour beta et renvoie généralement un maximum de 20 éléments correspondant à la relation développée.With Azure AD resources that derive from directoryObject, like user and group, $expand is only supported for beta and typically returns a maximum of 20 items for the expanded relationship.

paramètre filterfilter parameter

Utilisez le paramètre de requête $filter pour récupérer uniquement un sous-ensemble d’une collection.Use the $filter query parameter to retrieve just a subset of a collection.

Par exemple, pour rechercher des utilisateurs dont le nom d’affichage commence par la lettre « J », utilisez startswith.For example, to find users whose display name starts with the letter 'J', use startswith.

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

Essayer l’Afficheur GraphTry in Graph Explorer

La prise en charge des opérateurs $filter varie entre les API Microsoft Graph.Support for $filter operators varies across Microsoft Graph APIs. Les opérateurs logiques suivants sont généralement pris en charge :The following logical operators are generally supported:

  • égal à (eq)equals (eq)
  • n’est pas égal à (ne)not equals (ne)
  • supérieur à (gt)greater than (gt)
  • supérieur ou égal à (ge)greater than or equals (ge)
  • inférieur à (lt), inférieur ou égal à (le)less than (lt), less than or equals (le)
  • et (and)and (and)
  • ou (or)or (or)
  • pas (not)not (not)

L’opérateur de chaîne startswith est souvent pris en charge.The startswith string operator is often supported. L’opérateur lambda any est pris en charge pour certaines API.The any lambda operator is supported for some APIs.

Remarque : vous devez spécifier des propriétés de certaines manières lorsque vous utilisez à la fois $filter et $orderby dans la même requête pour recevoir des messages.Note: You must specify properties in certain ways when using both $filter and $orderby in the same query to get messages.

Pour consulter quelques exemples d’utilisation, reportez-vous au tableau ci-dessous.For some usage examples, see the following table. Pour plus de détails sur la syntaxe $filter, reportez-vous au protocole OData.For more details about $filter syntax, see the OData protocol.

Le tableau suivant répertorie quelques exemples où le paramètre de requête $filter est utilisé.The following table shows some examples that use the $filter query parameter.

Remarque : Cliquez sur les exemples pour essayer l’Afficheur Graph.Note: Click the examples to try them in Graph Explorer.

DescriptionDescription ExempleExample
Rechercher des utilisateurs portant le nom Mary dans plusieurs propriétés.Search for users with the name Mary across multiple properties. https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')
Obtenir tous les événements de l’utilisateur connecté qui commencent après le 01/07/2017.Get all the signed-in user's events that start after 7/1/2017. https://graph.microsoft.com/v1.0/me/events?$filter=start/dateTime ge '2017-07-01T08:00'
Obtenir tous les messages électroniques provenant d’une adresse spécifique reçus par l’utilisateur connecté.Get all emails from a specific address received by the signed-in user. https://graph.microsoft.com/v1.0/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 all emails received by the signed-in user in April 2017. https://graph.microsoft.com/v1.0/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 all unread mail in the signed-in user's Inbox. https://graph.microsoft.com/v1.0/me/mailFolders/inbox/messages?$filter=isRead eq false
Répertorier tous les groupes Office 365 dans une organisation.List all Office 365 groups in an organization. https://graph.microsoft.com/v1.0/groups?$filter=groupTypes/any(c:c+eq+'Unified')

Remarque : les opérateurs $filter suivants ne sont pas pris en charge pour les ressources Azure AD : ne, gt, ge, lt, le et not. L’opérateur de chaîne contains n’est actuellement pas pris en charge sur les ressources Microsoft Graph.Note: The following $filter operators are not supported for Azure AD resources: ne, gt, ge, lt, le, and not. The contains string operator is currently not supported on any Microsoft Graph resources.

paramètre formatformat parameter

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.Use the $format query parameter to specify the media format of the items returned from Microsoft Graph.

Par exemple, la requête suivante renvoie les utilisateurs de l’organisation au format json :For example, the following request returns the users in the organization in the json format:

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

Essayer l’Afficheur GraphTry in Graph Explorer

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.Note: The $format query parameter supports a number of formats (for example, atom, xml, and json) but results may not be returned in all formats.

paramètre orderbyorderby parameter

Pour spécifier l’ordre de tri des éléments renvoyés à partir de Microsoft Graph, utilisez le paramètre de requête $orderby.Use the $orderby query parameter to specify the sort order of the items returned from Microsoft Graph.

Par exemple, la requête suivante renvoie les utilisateurs de l’organisation classés par nom d’affichage :For example, the following request returns the users in the organization ordered by their display name:

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

Essayer l’Afficheur GraphTry in Graph Explorer

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 :You can also sort by complex type entities. The following request gets messages and sorts them by the address field of the from property, which is of the complex type emailAddress:

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

Essayer l’Afficheur GraphTry in Graph Explorer

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.To sort the results in ascending or descending order, append either asc or desc to the field name, separated by a space; for example, ?$orderby=name%20desc.

Avec certaines API, vous pouvez trier les résultats dans plusieurs propriétés.With some APIs, you can order results on multiple properties. 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).For example, the following request orders the messages in the user's Inbox, first by the name of the person who sent it in descending order (Z to A), and then by subject in ascending order (default).

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

Essayer l’Afficheur GraphTry in Graph Explorer

Remarque : Quand vous spécifiez le paramètre $filter, le serveur détermine un ordre de tri pour les résultats.When you specify $filter the server will infer a sort order for the results. 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.If you use both $orderby and $filter to get messages, because the server always infers a sort order for the results of a $filter, you must specify properties in certain ways.

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.The following example shows a query filtered by the subject and importance properties, and then sorted by the subject, importance, and receivedDateTime properties in descending order.

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

Essayer l’Afficheur GraphTry in Graph Explorer

Remarque : avec des ressources Azure AD issues de directoryObject, telles que les utilisateurs et les groupes, vous ne pouvez pas associer $orderby à des expressions $filter.Note: With Azure AD resources that derive from directoryObject, like user and group, you cannot combine $orderby with $filter expressions.

paramètre searchsearch parameter

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.Use the $search query parameter to restrict the results of a request to match a search criterion.

Remarque : actuellement, vous pouvez uniquement rechercher des collections message et person. Une requête $search renvoie jusqu’à 250 résultats. Vous ne pouvez pas utiliser $filter ou $orderby dans une requête de recherche.Note: You can currently search only message and person collections. A $search request returns up to 250 results. You cannot use $filter or $orderby in a search request.

Utilisation du critère $search dans les collections de messagesUsing $search on message collections

Vous pouvez rechercher des messages en fonction d’une valeur dans les propriétés de message spécifiques.You can search messages based on a value in specific message properties. Les résultats de la recherche sont triés par date et heure d’envoi du message.The results of the search are sorted by the date and time that the message was sent.

Si vous effectuez une recherche sur des messages et que vous spécifiez une valeur sans propriété de message spécifique, la recherche est effectuée sur les propriétés de recherche par défaut des éléments from, subject et body.If you do a search on messages and specify only a value without specific message properties, the search is carried out on the default search properties of from, subject, and body.

L’exemple suivant renvoie tous les messages de la boîte de réception de l’utilisateur connecté dont l’une des trois propriétés de recherche par défaut contient « pizza » :The following example returns all messages in the signed-in user's Inbox that contains "pizza" in any of the three default search properties:

GET https://graph.microsoft.com/v1.0/me/messages?$search="pizza"

Essayer l’Afficheur GraphTry in Graph Explorer

Vous pouvez également rechercher des messages en spécifiant les noms de propriété des messages dans le tableau suivant, qui seront reconnus par la syntaxe de langage de requête de mot clé (KQL).Alternatively, you can search messages by specifying message property names in the following table, that are recognized by the Keyword Query Language (KQL) syntax. Ces noms de propriété correspondent aux propriétés définies dans l’entité de message de Microsoft Graph.These property names correspond to properties defined in the message entity of Microsoft Graph. Outlook et d’autres applications Office 365, telles que SharePoint, prennent en charge la syntaxe KQL et procurent le confort d’un domaine de découverte en commun pour leurs magasins de données.Outlook and other Office 365 applications such as SharePoint support KQL syntax, providing the convenience of a common discovery domain for their data stores.

Propriété de messagerie utilisable dans une requêteSearchable email property DescriptionDescription ExempleExample
attachmentattachment Nom des fichiers joints à un message électronique.The names of files attached to an email message. me/messages?$search="attachment:api-catalog.md"
bccbcc Champ Cci d’un message électronique spécifié en tant qu’adresse SMTP, nom d’affichage ou alias.The bcc field of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="bcc:samanthab@contoso.com"&$select=subject,bccRecipients
bodybody Corps d’un message électronique.The body of an email message. me/messages?$search="body:excitement"
cccc Champ Cc d’un message électronique spécifié en tant qu’adresse SMTP, nom d’affichage ou alias.The cc field of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="cc:danas"&$select=subject,ccRecipients
fromfrom Expéditeur d’un message électronique spécifié en tant qu’adresse SMTP, nom d’affichage ou alias.The sender of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="from:randiw"&$select=subject,from
hasAttachmenthasAttachment True si un message électronique contient une pièce jointe qui n’est pas une pièce jointe incorporée, False dans le cas contraire.True if an email message contains an attachment that is not an inline attachment, false otherwise. me/messages?$search="hasAttachments=true"
importanceimportance Importance d’un message électronique, que l’expéditeur peut préciser lors de l’envoi.The importance of an email message, which a sender can specify when sending a message. Les valeurs possibles sont low, medium ou high.The possible values are low, medium, or high. me/messages?$search="importance:high"&$select=subject,importance
kindkind Type du message.The type of message. Les valeurs possibles sont contacts, docs, email, faxes, im, journals, meetings, notes, posts, rssfeeds, tasks ou voicemail.The possible values are contacts, docs, email, faxes, im, journals, meetings, notes, posts, rssfeeds, tasks, or voicemail. me/messages?$search="kind:voicemail"
participantsparticipants Champs De, À, Cc et Cci d’un message électronique spécifié en tant qu’adresse SMTP, nom d’affichage ou alias.The from, to, cc, and bcc fields of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="participants:danas"
receivedreceived Date à laquelle un message électronique a été reçu par un destinataire.The date that an email message was received by a recipient. me/messages?$search="received:07/23/2018"&$select=subject,receivedDateTime
recipientsrecipients Champs À, Cc et Cci d’un message électronique spécifié en tant qu’adresse SMTP, nom d’affichage ou alias.The to, cc, and bcc fields of an email meesage, specified as an SMTP address, display name, or alias. me/messages?$search="recipients:randiq"&$select=subject,toRecipients,ccRecipients,bccRecipients
sentsent Date à laquelle un message électronique a été envoyé par l’expéditeur.The date that an email message was sent by the sender. me/messages?$search="sent:07/23/2018"&$select=subject,sentDateTime
sizesize Taille d’un élément, en octets.The size of an item in bytes. me/messages?$search="size:1..500000"
subjectsubject Texte de la ligne d’objet d’un message électronique.The text in the subject line of an email message. . me/messages?$search="subject:has"&$select=subject
toto Champ À d’un message électronique spécifié en tant qu’adresse SMTP, nom d’affichage ou alias.The to field of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="to:randiw"&$select=subject,toRecipients

Pour plus d’informations sur les propriétés de messagerie utilisables dans une requête, la syntaxe KQL et les opérateurs pris en charge, et pour bénéficier de conseils sur la recherche, consultez les articles suivants :For more information about searchable email properties, KQL syntax, supported operators, and tips on searching, see the following articles:

Utilisation du critère $search dans les collections personUsing $search on person collections

Vous pouvez utiliser l’API Contacts de Microsoft Graph pour récupérer les contacts les plus pertinents pour un utilisateur. La pertinence est déterminée par les relations professionnelles, ainsi que les modèles de communication et de collaboration de l’utilisateur. L’API Contacts prend en charge les paramètres de requête $search.You can use the Microsoft Graph People API to retrieve the people who are most relevant to a user. Relevance is determined by the user’s communication and collaboration patterns and business relationships. The People API supports the $search query parameter.

Les recherches de contacts sont effectuées dans les propriétés displayName et emailAddress de la ressource person.Searches on people occur on both the displayName and emailAddress properties of the person resource.

La requête suivante recherche une personne nommée « Irene McGowen » dans les propriétés displayName et emailAddress de chaque personne figurant dans la collection people de l’utilisateur connecté.The following request does a search for a person named "Irene McGowen" in the displayName and emailAddress properties in each person in the people collection of the signed-in user. Étant donné qu’une personne nommée « Irene McGowan » est pertinente pour l’utilisateur connecté, les informations relatives à « Irene McGowan » sont renvoyées.Because a person named "Irene McGowan" is relevant to the signed-in user, the information for "Irene McGowan" is returned.

GET https://graph.microsoft.com/v1.0/me/people/?$search="Irene McGowen"

L’exemple suivant illustre la réponse.The following example shows the response.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
       {
           "id": "C0BD1BA1-A84E-4796-9C65-F8A0293741D1",
           "displayName": "Irene McGowan",
           "givenName": "Irene",
           "surname": "McGowan",
           "birthday": "",
           "personNotes": "",
           "isFavorite": false,
           "jobTitle": "Auditor",
           "companyName": null,
           "yomiCompany": "",
           "department": "Finance",
           "officeLocation": "12/1110",
           "profession": "",
           "userPrincipalName": "irenem@contoso.onmicrosoft.com",
           "imAddress": "sip:irenem@contoso.onmicrosoft.com",
           "scoredEmailAddresses": [
               {
                   "address": "irenem@contoso.onmicrosoft.com",
                   "relevanceScore": -16.446060612802224
               }
           ],
           "phones": [
               {
                   "type": "Business",
                   "number": "+1 412 555 0109"
               }
           ],
           "postalAddresses": [],
           "websites": [],
           "personType": {
               "class": "Person",
               "subclass": "OrganizationUser"
           }
       }
   ]
}

Pour en savoir plus sur l’API Contacts, consultez l’article Utiliser l’API Contacts dans Microsoft Graph pour obtenir des informations sur les contacts plus pertinents pour vous.To learn more about the People API, see Get information about relevant people.

paramètre selectselect parameter

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.Use the $select query parameter to return a set of properties that are different than the default set for an individual resource or a collection of resources. Avec $select, vous pouvez spécifier un sous-ensemble ou un sur-ensemble des propriétés par défaut.With $select, you can specify a subset or a superset of the default properties.

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 :For example, when retrieving the messages of the signed-in user, you can specify that only the from and subject properties be returned:

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

Essayer l’Afficheur GraphTry in Graph Explorer

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.Important: In general, we recommend that you use $select to limit the properties returned by a query to those needed by your app. C’est notamment le cas des requêtes pouvant potentiellement renvoyer un ensemble de résultats volumineux.This is especially true of queries that might potentially return a large result set. 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.Limiting the properties returned in each row will reduce network load and help improve your app's performance.

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.In v1.0, some Azure AD resources that derive from directoryObject, like user and group, return a limited, default subset of properties on reads. For these resources, you must use $select to return properties outside of the default set.

paramètre skipskip parameter

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 :Use the $skip query parameter to set the number of items to skip at the start of a collection. For example, the following request returns events for the user sorted by date created, starting with the 21st event in the collection:

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

Essayer l’Afficheur GraphTry in Graph Explorer

Remarque : certaines API Microsoft Graph, comme Courrier et calendrier Outlook (message, event et calendar), utilisent $skip pour mettre en œuvre la pagination.Note: Some Microsoft Graph APIs, like Outlook Mail and Calendars (message, event, and calendar), use $skip to implement paging. 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.When results of a query span multiple pages, these APIs will return an @odata:nextLink property with a URL that contains a $skip parameter. Vous pouvez utiliser cette URL pour renvoyer la page de résultats suivante.You can use this URL to return the next page of results. Pour plus d’informations, consultez la rubrique relative à la pagination.To learn more, see Paging.

paramètre skipTokenskipToken parameter

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.Some requests return multiple pages of data either due to server-side paging or due to the use of the $top parameter to limit the page size of the response. Many Microsoft Graph APIs use the skipToken query parameter to reference subsequent pages of the result. The $skiptoken parameter contains an opaque token that references the next page of results and is returned in the URL provided in the @odata.nextLink property in the response. To learn more, see Paging.

paramètre toptop parameter

Utilisez le paramètre $top pour spécifier la taille de la page de l’ensemble de résultats.Use the $top query parameter to specify the page size of the result set.

S’il reste plusieurs éléments dans l’ensemble de résultats, le corps de la réponse contient un paramètre @odata.nextLink.If more items remain in the result set, the response body will contain an @odata.nextLink parameter. Ce paramètre contient une URL que vous pouvez utiliser pour obtenir la page de résultats suivante.This parameter contains a URL that you can use to get the next page of results. Pour plus d’informations, consultez la rubrique relative à la pagination.To learn more, see Paging.

Par exemple, la requête suivante renvoie les cinq premiers messages dans la boîte aux lettres de l’utilisateur :For example, the following request returns the first five messages in the user's mailbox:

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

Essayer l’Afficheur GraphTry in Graph Explorer

Gestion des erreurs pour les paramètres de requêteError handling for query parameters

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.Some requests will return an error message if a specified query parameter is not supported. For example, you cannot use $expand on the user/photo relationship.

https://graph.microsoft.com/beta/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.However, it is important to note that query parameters specified in a request might fail silently. 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.This can be true for unsupported query parameters as well as for unsupported combinations of query parameters. 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é.In these cases, you should examine the data returned by the request to determine whether the query parameters you specified had the desired effect.