Utiliser les opérations de requête OData dans les demandes REST SharePointUse OData query operations in SharePoint REST requests

Avant de commencerBefore you start

Le service REST SharePoint prend en charge un large éventail d’opérateurs de chaîne de requête OData, qui vous permettent de sélectionner, de filtrer et d’ordonner les données demandées.The SharePoint REST service supports a wide range of OData query string operators that enable you to select, filter, and order the data you request.

Conseil

Le service REST SharePoint Online (et SharePoint sur site 2016 et ultérieur) prend en charge la combinaison de plusieurs requêtes en un seul appel au service à l’aide de l’option de requête $batch OData.The SharePoint Online (and on-premises SharePoint 2016 and later) REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. Pour obtenir plus d’informations et des liens vers des exemples de code, consultez la rubrique Créer des requêtes de lots avec l’API REST.For details and links to code samples, see Make batch requests with the REST APIs.

Sélectionner les champs à renvoyerSelect fields to return

Utilisez l’option de requête $select pour spécifier les champs à renvoyer pour une liste, un élément de liste ou un autre objet SharePoint donné représenté par un ensemble d’entités.Use the $select query option to specify which fields to return for a given list, list item, or other SharePoint object represented by an entity set. Vous pouvez utiliser $select=* pour renvoyer tous les champs disponibles.You can use $select=* to return all available fields.

Notes

En général, si vous ne définissez pas l’option de requête $select, le service REST renvoie tous les champs disponibles par défaut.In general, if you do not specify the $select query option, the REST service returns all available fields by default. Cependant, il arrive que des objets SharePoint comprennent des propriétés dont la récupération mobilise beaucoup de ressources. Pour optimiser les performances du service REST, ces propriétés ne sont pas incluses dans la requête par défaut et doivent faire l’objet d’une demande explicite. Par exemple, la propriété SPWeb.EffectiveBasePermissions n’est pas renvoyée par défaut et doit être demandée de façon explicite à l’aide de l’option de requête $select.However, in a few cases, some SharePoint objects include properties that are very resource intensive to retrieve; to optimize REST service performance, these properties are not included in the default query, and must be explicitly requested.For example, the SPWeb.EffectiveBasePermissions property is not returned by default, and must be explicitly requested by using the $select query option.

En outre, vous pouvez demander à ce que la requête renvoie des champs projetés à partir d’autres listes, ainsi que les valeurs des recherches.In addition, you can specify that the request returns projected fields from other lists and the values of lookups. Pour ce faire, spécifiez le nom du champ dans les options de requête $select et $expand.To do this, specify the field name in both the $select and $expand query options. Par exemple :For example:

http://server/site/_api/web/lists('guid')/items?$select=Title,Products/Name&$expand=Products/Name

L’expansion et la sélection en bloc d’éléments connexes ne sont pas prises en charge.Bulk expansion and selection of related items is not supported.

Sélectionner les éléments à renvoyerSelect items to return

Utilisez l’option de requête $filter pour sélectionner les éléments à renvoyer.Use the $filter query option to select which items to return. La rubrique Opérateurs de requête OData pris en charge dans le service REST SharePoint présente les options de comparaison des requêtes de filtrage et les fonctions que vous pouvez utiliser avec le service REST SharePoint.OData query operators supported in the SharePoint REST service lists the filter query comparison options and functions you can use with the SharePoint REST service.

Requête pour les champs Liste de choix à valeur uniqueQuery for single value lookup fields

Les champs Liste de choix à valeur unique sont représentés par deux champs distincts dans le service REST SharePoint : l’un représentant la valeur du champ en question, l’autre le nom du champ. Vous pouvez effectuer des requêtes sur la valeur du champ Liste de choix comme vous le feriez avec n’importe quel champ de ce type de données. Par exemple, si la valeur du champ Liste de choix est une chaîne, vous pouvez utiliser les options de comparaison de chaîne dans votre requête.Single value lookup fields are represented by two separate fields in the SharePoint REST service: one field representing the actual field value, and another representing the field name. You can perform queries against the lookup field value as you would any other field of that data type. For example, if the lookup field value is a string, you can use string comparison options in your query.

Requête pour les utilisateursQuery for users

Dans le service REST SharePoint, les utilisateurs sont représentés par leur nom (d’affichage) convivial, et non par leur alias ou leur combinaison domaine\alias. Par conséquent, vous devez créer les requêtes d’utilisateurs sur leurs noms conviviaux.In the SharePoint REST service, users are represented by the user's friendly (display) name, and not their alias or domain\alias combination. Therefore, you must construct user queries against users' friendly names.

Notes

Les requêtes d’utilisateurs basées sur l’appartenance ne sont pas prises en charge.Membership-based user queries are not supported. L’utilisation de l’opérateur Current pour lancer des requêtes à l’aide de l’ID de l’utilisateur actif n’est pas prise en charge.Usage of the Current operator to do queries using the ID of the current user is not supported.

Requête pour les champs Liste de choix à valeurs multiples et les utilisateursQuery for multi-value lookup fields and users

Les champs Liste de choix à valeurs multiples étant renvoyés sous la forme d'une chaîne à valeurs multiples, il est impossible de les rechercher (par exemple, l'équivalent d'un élément Includes ou NotIncludes n'est pas pris en charge).Because multi-value lookup fields are returned as a string of multiple values, there is no way to query for them (for example, the equivalent of an Includes element or NotIncludes element is not supported).

Trier les éléments renvoyésSort returned items

Utilisez les options de requête $orderby pour indiquer l’ordre de tri des éléments dans les résultats de votre requête.Use the $orderby query option to specify how to sort the items in your query return set. Pour effectuer un tri en fonction de plusieurs champs, spécifiez une liste de champs séparés par des virgules.To sort by multiple fields, specify a comma-separated list of fields. Vous pouvez également indiquer si vous souhaitez trier les éléments par ordre croissant ou décroissant en ajoutant le mot clé asc ou desc à votre requête.You can also specify whether to sort the items in ascending or descending order by appending the asc or desc keyword to your query.

Parcourir les éléments renvoyésPage through returned items

Utilisez les options de requête $top et $skiptoken pour ne sélectionner qu’un sous-ensemble des éléments qui seraient normalement renvoyés par votre requête.Use the $top and $skiptoken query options to select a subset of the items that would otherwise be returned by your query.

Notes

L’option de requête $skip ne fonctionne pas avec les requêtes pour les éléments de liste SharePoint.The $skip query option does not work with queries for SharePoint list items.

L’option $top vous permet de sélectionner les n premiers éléments des résultats.The $top option enables you to select the first n items of the return set for return. Par exemple, l’URI suivant demande que seuls les dix premiers résultats possibles soient renvoyés :For example, the following URI requests that only the first ten items in the prospective return set actually be returned:

http://server/site/_api/web/lists('<guid>')/items?$top=10

L’option $skiptoken permet d’ignorer les éléments jusqu’à celui spécifié et de renvoyer les suivants.The $skiptoken option enables you to skip over items until the specified item is reached and return the rest.

?$skiptoken=Paged=TRUE%26p_ID=5

Notes

Quand vous utilisez ces options de requête, rappelez-vous que la pagination dans OData est ordinale.When using these query options, take into account that paging in OData is ordinal. Imaginons par exemple que vous implémentiez un bouton Page suivante pour afficher des éléments de liste SharePoint.For example, suppose you are implementing a next page button to display SharePoint list items. Le service REST permet au bouton de renvoyer les éléments 1 à 20 quand vous cliquez dessus, puis les éléments 21 à 40, et ainsi de suite.You use the REST service to enable the button to return items 1 through 20 when clicked, and then items 21 through 40, and so on. Cependant, imaginons qu’un autre utilisateur supprime les éléments 4 et 18 entre deux clics sur le bouton Suivant.However, suppose another user deletes items 4 and 18 between clicks of the next button. Dans ce cas, la position ordinale des éléments restants est réinitialisée et l’affichage des éléments 21 à 40 saute deux éléments.In such a case, the ordinal positioning of the remaining items is reset, and displaying items 21 through 40 actually skips over two items.

Opérateurs de requête OData pris en charge dans le service REST SharePointOData query operators supported in the SharePoint REST service

Pris en chargeSupported Non pris en chargeNot supported
Comparaisons numériques Lt Le Gt Ge Eq NeNumeric comparisons Lt Le Gt Ge Eq Ne Opérateurs arithmétiques (Add, Sub, Mul, Div, Mod)Arithmetic operators (Add, Sub, Mul, Div, Mod)
Fonctions mathématiques de base (arrondi, plancher, plafond)Basic math functions (round, floor, ceiling)
Comparaisons de chaînes startsWith substringof Eq NeString comparisons startsWith substringof Eq Ne endsWith replace substring tolower toupper trim concatendsWith replace substring tolower toupper trim concat
Fonctions de date et heure day() month() year() hour() minute() second()Date and time functions day() month() year() hour() minute() second() Opérateur DateTimeRangesOverlapDateTimeRangesOverlap operator
Si une date/heure appartient à un modèle de date/heure récurrentQuerying as to whether a date time falls inside a recurrent date time pattern

La figure suivante présente les options de requête OData prises en charge.The following figure shows the supported OData query options.

Options de requête OData prises en chargeSupported OData query options

Syntaxe d’option de requête de service REST SharePoint


Voir aussiSee also