Utiliser les opérations de requête OData dans les demandes REST SharePoint
Conseil
Avant de commencer, consultez les ressources suivantes :
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 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. 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.
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.
Remarque
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. 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.
Vous pouvez également demander à ce que la requête renvoie des champs projetés à partir d’autres listes, ainsi que les valeurs des recherches. Pour ce faire, spécifiez le nom du 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. 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.
Requête pour les champs Liste de choix à valeur unique
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 exécuter des requêtes sur la valeur du champ de recherche comme vous le feriez pour n’importe quel autre 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.
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.
Remarque
Les requêtes d’utilisateurs basées sur l’appartenance 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 actif 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 les options de requête $orderby pour indiquer l’ordre de tri des éléments dans les résultats de votre requête. Pour effectuer un tri en fonction de plusieurs champs, spécifiez une liste de champs séparés par des virgules. 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.
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.
Remarque
L’option de requête $skip ne fonctionne pas avec les requêtes pour les éléments de liste SharePoint.
L’option $top vous permet de sélectionner les n premiers éléments des résultats. Par exemple, l’URI suivant demande que seuls les dix premiers résultats possibles soient effectivement 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"
Remarque
Quand vous utilisez ces options de requête, rappelez-vous que la pagination dans OData est ordinale. Imaginons par exemple que vous implémentiez un bouton Page suivante pour afficher des éléments de liste SharePoint. 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. Cependant, imaginons qu’un autre utilisateur supprime les éléments 4 et 18 entre deux clics sur le bouton Suivant. 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.
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
