Utiliser les opérations de requête OData dans les demandes REST SharePoint

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.

Conseil

Le service REST SharePoint Online (et SharePoint 2016 local et version ultérieure) prend en charge la combinaison de plusieurs requêtes dans un seul appel au service à l’aide de l’option de requête $batch OData. Pour en savoir plus et obtenir des liens vers des exemples de code, consultez l’article Créer des requêtes de lots avec l’API REST.

Sélectionner les champs à renvoyer

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. Vous pouvez utiliser $select=* pour renvoyer tous les champs disponibles.

Notes

En général, si vous n'indiquez pas l'option de requête $select, le service REST renvoie tous les champs disponibles par défaut. Mais 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 explicitement à l'aide de l'option de requête $select.

Vous pouvez aussi spécifier que la demande renvoie des champs projetés à partir d'autres listes, ainsi que les valeurs de recherche. Pour ce faire, indiquez le nom de champ dans les options de requête $select et $expand. Par exemple :

GET https://{site_url}/_api/web/lists('{list_guid}')/items?$select=Title,Products/Name&$expand=Products/Name
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

L’expansion et la sélection en bloc d’éléments connexes ne sont pas prises en charge.

Sélectionner les éléments à renvoyer

Utilisez l’option de requête $filter pour sélectionner les éléments à renvoyer. Le tableau Opérateurs de requête OData pris en charge dans le service REST SharePoint énumère les options de comparaison des requêtes de filtrage et les fonctions que vous pouvez utiliser avec le service REST SharePoint.

Requête pour les champs de recherche à valeur unique

Les champs de recherche à valeur unique sont représentés par deux champs distincts dans le service REST SharePoint : l’un représentant la valeur réelle du champ, et un autre représentant le nom du champ. Vous pouvez exécuter des requêtes sur la valeur du champ de recherche comme vous le feriez avec n’importe quel champ de ce type de données. Par exemple, si la valeur du champ de recherche est une chaîne, vous pouvez utiliser les options de comparaison de chaîne dans votre requête.

Requête pour les utilisateurs

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.

Notes

Les requêtes fondées sur l’appartenance des utilisateurs ne sont pas prises en charge. L’utilisation de l’opérateur Current pour lancer des requêtes à l’aide de l’ID de l’utilisateur actuel n’est pas prise en charge.

Requête pour les champs Liste de choix à valeurs multiples et les utilisateurs

Les champs Liste de choix à valeurs multiples étant renvoyés sous la forme d’une chaîne à valeurs multiples, il est impossible de les interroger (par exemple, l’équivalent d’un élément Includes ou NotIncludes n’est pas pris en charge).

Trier les éléments renvoyés

Utilisez l'option de requête $orderby pour indiquer comment trier les éléments dans l'ensemble des réponses de la requête. Pour trier en fonction de plusieurs champs, spécifiez une liste de champs séparés par des virgules. Vous pouvez aussi indiquer si les éléments doivent être triés par ordre croissant ou décroissant en ajoutant le mot clé asc ou desc à votre requête.

Parcourir les éléments renvoyés

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.

Notes

L’option de requête $skip ne fonctionne pas avec les requêtes pour les éléments de liste SharePoint.

L'option $top permet de ne sélectionner que les n premiers éléments devant être renvoyés par la requête. Par exemple, l'URI suivant demande de ne renvoyer que les dix premiers éléments de l'ensemble des éléments pouvant être renvoyés :

GET https://{site_url}/_api/web/lists('{list_guid}')/items?$top=10`
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

L’option de requête $skiptoken permet d’ignorer les éléments jusqu’à celui spécifié et de renvoyer le reste.

GET https://{site_url}/_api/web/lists('{list_guid}')/items?$skiptoken=Paged=TRUE%26p_ID=5`
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

Notes

REMARQUE Lorsque vous utilisez ces options de requête, tenez compte du fait que la pagination dans OData est ordinale. Par exemple, supposons que vous implémentez un bouton Page suivante pour afficher des éléments de liste SharePoint. Vous utilisez le service REST pour activer le bouton et pour qu'il renvoie les éléments 1 à 20 lorsque vous cliquez dessus et puis les éléments 21 à 40, et ainsi de suite. Toutefois, imaginons qu'un autre utilisateur supprime les éléments 4 et 18 entre deux clics sur le bouton Suivant. Dans ce cas, l'ordre des éléments restants est réinitialisé et l'affichage des éléments 21 à 40 ignore deux éléments.

Opérateurs de requête OData pris en charge dans le service REST SharePoint

Pris en charge Non pris en charge
Comparaisons numériques (lt le gt ge eq ne) Opérateurs arithmétiques (add, sub, mul, div, mod)
Fonctions mathématiques de base (round, floor, ceiling)
Comparaisons de chaînes
startswith( {Col to query}, '{chaîne à vérifier}' )
substringof( '{string to check}', {Col to query} )
eq
ne
endswith, replace, substring, tolower, toupper, trim, concat
Fonctions de date et heure day(), month(), year(), hour(), minute(), second() Opérateur DateTimeRangesOverlap
Si une date/heure appartient à un modèle de date/heure récurrent

La figure suivante présente les options de requête OData prises en charge.

Options de requête OData prises en charge

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

Voir aussi