Utiliser le filtrage OData avec SharePoint

14 minutes

Dans cette unité, nous allons découvrir comment utiliser les filtres OData (Open Data Protocol) lors de l’interrogation de listes et bibliothèques de documents SharePoint.

Pourquoi utiliser un filtre OData ?

Pourquoi utiliser des filtres OData pour SharePoint ? Par défaut, l’action Obtenir les éléments pour les listes ou l’action Obtenir les fichiers pour les bibliothèques récupère uniquement les 100 premiers éléments ou fichiers depuis SharePoint si vous ne spécifiez pas de valeur Premiers éléments ou Seuil. Bien que vous puissiez spécifier un Premiers éléments jusqu’à la limite de limitation de seuil par défaut de 5 000 éléments, si votre liste ou bibliothèque comporte plus de 5 000 éléments ou fichiers, cela ne renvoie pas toutes vos données utilisant une entrée sous Premiers éléments. Par conséquent, le filtrage de votre requête vous permet de créer des résultats inférieurs aux limites de seuil.

Toute tentative de saisie d’un nombre supérieur à 5 000 entraîne un échec du flux lorsque vous essayez de l’exécuter.

Comprendre les paramètres d’action pour les grandes listes ou bibliothèques

Si votre liste ou bibliothèque comporte plus de 100 éléments ou fichiers et jusqu’à 5 000 éléments, il vous suffit d’ajuster le Premiers éléments. Dans le champ Premiers éléments, vous pouvez saisir une valeur allant jusqu’à la limite de seuil par défaut de 5 000. La limite de seuil vise à empêcher cette étape de renvoyer plus de 5 000 éléments. Le Premiers éléments est un moyen performant de récupérer jusqu’à 5 000 éléments depuis vos données.

Si votre liste ou bibliothèque comporte plus de 5 000 éléments ou si votre requête renvoie plus de 5 000 éléments, vous devez activer la pagination de l’étape. En quoi consiste la pagination ? Chaque fois que l’action Obtenir les éléments récupère des valeurs, elle obtient 100 éléments à la fois. Tout comme si vous parcourez votre liste ou bibliothèque SharePoint, vous accédez au bas des éléments visibles et SharePoint récupère 100 éléments supplémentaires. Ainsi, la pagination permet au processus de récupération (par lots de 100 éléments) de se poursuivre bien au-delà. Gardez cependant à l’esprit que la pagination prend du temps et ralentit votre flux. Lorsque le paramètre Pagination est activé, votre action répète ce processus pour renvoyer la valeur saisie manuellement du seuil total (autre entrée nécessaire dont nous parlerons dans un instant).

Pour trouver le paramètre Pagination, cliquez sur les points de suspension dans le coin droit de votre action Obtenir les éléments ou Obtenir les fichiers pour afficher l’option Paramètres.

Dans le volet des paramètres de l’action, réglez le bouton bascule Pagination sur Activé, puis saisissez ici une valeur pour Seuil. La pagination peut renvoyer de 1 à 100 000 éléments de votre source de données, mais il vous suffit de la définir pour le nombre d’éléments que vous prévoyez de renvoyer. Enfin, cliquez sur Terminé pour revenir aux paramètres standard.

Le paramètre Seuil dans le volet des paramètres est un peu difficile à comprendre, mais considérez-le comme suit. Il doit correspondre au nombre d’éléments que vous prévoyez de recevoir de votre requête, mais il ne peut pas renvoyer plus de 100 000 éléments. Par exemple, si vous définissez votre seuil sur 500 et que 2 000 éléments correspondent à la requête, vous ne recevez que 500 éléments. Dans le même cas, si vous définissez votre seuil sur 2 000, vous obtenez les 2 000 éléments attendus.

Pourquoi est-ce important ? Pourquoi ne devriez-vous pas simplement utiliser les valeurs maximales de Premiers éléments (5 000) et Seuil (100 000) ? Parce que demander à Power Automate de paginer prend du temps et ralentit votre flux. Si vous pouvez obtenir toutes les données que vous attendez avec une valeur Premiers éléments de 2 500 (par exemple), il n’est pas nécessaire de régler le bouton bascule Pagination et d’appliquer la valeur maximale au seuil pour continuer à paginer sur l’ensemble de vos données.

Dernier point à prendre en compte avant de continuer : définissez toujours le paramètre Premiers Éléments sur 5 000 si vous prévoyez de renvoyer plus de 5 000 éléments. Le paramètre Premiers Éléments est un moyen rapide de renvoyer les 5 000 premiers éléments et la pagination reprend à la fin de ces 5 000 premiers éléments. Ils œuvrent de concert. La pagination seule fonctionne certainement, mais elle doit continuer à récupérer 100 éléments à la fois pour effectuer le même travail.

Utilisation d’OData dans votre requête de filtre

Maintenant que nous avons plaidé en faveur du filtrage de vos données, découvrons comment utiliser le filtrage OData. Lorsque vous utilisez le filtrage OData dans vos requêtes, le modèle dans le champ Filtrer la requête est basé sur le type de données dans la colonne. Commençons par un filtre par colonne. Si la valeur de la colonne est égale à une chaîne, nous pouvons utiliser un filtre qui ressemble à ceci :

StringColumn eq 'text'

Vous voyez comment l’instruction OData utilise l’abréviation eq pour des égaux ? Il s’agit du code OData pour l’opérateur Est égal à. Notez également comment notre valeur de chaîne est entourée de guillemets simples.

Nous pourrions utiliser le même opérateur OData pour une colonne avec une valeur numérique telle que la suivante :

NumericColumn eq 3

Notez que lorsque nous comparons des valeurs numériques, nous n’avons pas besoin d’utiliser des guillemets simples.

SharePoint n’effectue pas toutes les opérations que Power Automate lui demande de faire en raison de contraintes de délégation. Autrement dit, SharePoint n’effectue que certains types de filtres de requêtes. Voici les opérateurs OData vous permettant de demander un filtrage SharePoint :

Opérateur	Abréviation	Syntaxe
Equals	eq	`StringValueColumn eq 'text'` (ou `NumericColumn eq number`)
Not equals	ne	`StringValueColumn ne 'text'` (ou `NumericColumn ne number`)
Less than	lt	`NumericColumn lt number` (ou `DateValueColumn lt date`)
Greater than	gt	`NumericColumn gt number` (ou `DateValueColumn gt date`)
Less than or equal to	le	`NumericColumn le number` (ou `DateValueColumn le date`)
Greater than or equal to	ge	`NumericColumn le number` (ou `DateValueColumn le date`)
Starts with	startswith	`startswith(StringValueColumn, 'text')`
Substring of	substringof	`substringof('text', StringValueColumn)`
And	and	`FilterFormula and FilterFormula`
Or	or	`FilterFormula or FilterFormula`

Examiner le filtre de type « Le texte est égal à »

Examinons ensemble un exemple. Rechercher une liste SharePoint avec plusieurs éléments que vous pouvez utiliser, puis ouvrez une instance de navigateur distincte sur Power Automate Maker Portal.

Depuis l’écran d’accueil de Power Automate Maker Portal, cliquez sur l’onglet Créer dans le menu de navigation gauche.
Sélectionnez Flux de cloud instantané parmi les options en haut.
Sélectionnez Déclencher manuellement un flux>Créer.
Ajoutez une étape sous votre déclencheur et recherchez sharepoint.
Recherchez et sélectionnez l’action SharePoint Obtenir les éléments.
Ajoutez l’adresse de votre site SharePoint. Il s’agit de l’URL de la page d’accueil du site sur lequel votre liste SharePoint réside. Si vous ne voyez pas le nom de votre liste SharePoint dans la liste déroulante Adresse du site, vous pouvez récupérer la page d’accueil de votre site SharePoint en cliquant sur Accueil dans le rail de navigation gauche, puis copier l’URL depuis votre navigateur. De retour dans Power Automate, sélectionnez l’option déroulante Saisir une valeur personnalisée et collez l’URL de votre page d’accueil SharePoint.
Sous Nom de la liste, recherchez et sélectionnez le nom de la liste SharePoint dans la liste déroulante.
Développez Afficher les options avancéeset recherchez le champ Filtrer la requête. Notez que le texte d’information (sachant que vous pouvez afficher l’intégralité des informations en survolant le champ) vous indique qu’il attend une instruction de filtre OData et fournit même des exemples de syntaxe.
Commençons par filtrer une colonne de valeur de texte SharePoint à l’aide de la fonction equals (eq). Choisissez l’une de vos colonnes comportant des valeurs de texte. Pour la formule, saisissez le nom de votre colonne eq, puis une valeur située sous cette colonne entre guillemets simples. Saisissez une valeur exacte entre les guillemets qui existe dans les données de la colonne.

Si cette valeur ne correspond pas exactement au nom/à la valeur de la colonne, le filtre ne fonctionne pas. Pour voir les valeurs de vos noms de colonne, vous pouvez accéder aux Paramètres de liste de votre liste SharePoint en cliquant sur l’icône des paramètres, puis survolez le nom de la colonne et recherchez le nom de cette colonne en bas de l’écran. Lorsque vous survolez le nom, une URL s’affiche avec un signe égal, puis le nom de votre colonne.

Voir notre exemple ci-dessous. Notre colonne SharePoint est nommée Description du produit, mais le nom réel dans les données est field_1 : il s’agit donc du nom que nous devons saisir pour le nom de la colonne.
Afin de pouvoir voir combien d’éléments sont renvoyés avec notre filtre, ajoutons une action supplémentaire sous l’action Obtenir les éléments. Ajoutez une action Composer. Cliquez sur le champ Entrées et passez à l’onglet Expression. Ajoutez la formule suivante dans le champ de saisie Expression :

length(outputs('Get_items')?['body/value'])

Cette action compte le nombre de lignes renvoyées par notre action Obtenir les éléments.
Cliquez sur Mettre à jour pour enregistrer cette valeur.
Testons maintenant notre flux. Sélectionnez Enregistrer>Tester>Manuellement>Tester, puis une fois votre connexion vérifiée, cliquez sur Exécuter le flux.
Une fois le flux exécuté, développez l’action Composer dans les résultats du flux et affichez le nombre d’éléments renvoyés. Était-ce ce à quoi vous vous attendiez ? Si vous avez effectué un test avec une longue liste d’éléments comportant plusieurs éléments remplissant vos critères, vous n’avez peut-être renvoyé que 100 éléments.

Si votre filtre n’a pas vraiment fonctionné, vérifiez et assurez-vous que le nom de la colonne est exact et que les données correspondantes sont exactes entre guillemets simples.

Utilisez le paramètre Premiers éléments

À l’aide du même flux, voyons ce que l’utilisation du paramètre Premiers éléments nous apporte. Le paramètre Premiers éléments est un excellent moyen de tester si votre liste filtre correctement, car vous pouvez limiter les données renvoyées à quelques éléments et afficher rapidement ces données une fois le flux exécuté.

Remettez votre flux en mode Édition.
Développez l’action Obtenir les éléments et cliquez sur Afficher les options avancées.
Dans le champ à droite de Premiers éléments, saisissez 1.
Effectuez une nouvelle exécution test de votre flux.

Conseil

Lorsque vous testez votre flux, vous pouvez réexécuter rapidement le flux avec moins de clics sur des boutons à l’aide de l’option Automatiquement avec une exécution précédente.
Sur l’écran des résultats de l’exécution, si vous développez votre action Composer, elle doit refléter la valeur 1 dans les entrées/sorties.
Si vous développez votre action Obtenir les éléments, vous pouvez cliquer sur Cliquer pour télécharger afin d’afficher le code JSON de votre élément renvoyé.
Remettez une nouvelle fois votre flux en mode Édition.
Saisissez une valeur Premiers Éléments correspondant à ce que vous attendez de voir dans votre requête (jusqu’à 5 000), mais pas supérieure au nombre d’éléments de votre liste.
Enregistrez et testez à nouveau votre flux. Avez-vous obtenu les résultats que vous espériez ? Sinon, revenez en arrière, vérifiez vos valeurs et réessayez.

Utiliser la pagination

Pour tester la pagination, vous devez disposer d’une liste de plus de 100 éléments, car la fonction Obtenir les éléments récupère 100 éléments à la fois. Une liste comportant 101 à 200 éléments appellerait deux récupérations. N’oubliez pas que vous n’avez pas vraiment besoin de pagination si vous prévoyez de renvoyer 5 000 éléments ou moins ; le paramètre Premiers éléments est bien plus performant. Mais cela vous permet de découvrir comment cela fonctionne.

Mettez une nouvelle fois votre flux en mode Édition.
Effacez la valeur que vous avez pour le paramètre Premiers éléments afin qu’il soit vide. En réalité, vous utiliserez toujours le paramètre Premiers éléments pour votre filtre, car il peut rapidement appeler vos 5 000 premières valeurs. Mais dans ce cas, nous espérons démontrer comment fonctionne la pagination et à quel point elle peut être lente.
Accédez aux paramètres de l’action Obtenir les éléments.
Réglez le bouton bascule Pagination sur Activé et saisissez le nombre d’éléments que vous souhaitez récupérer dans le champ de saisie Seuil.
Cliquez sur Terminé.
Enregistrez et testez votre flux. Si vous disposez d’une longue liste, notez que l’exécution du flux prend beaucoup de temps. Imaginez que vous parcouriez l’intégralité des 100 éléments de votre liste SharePoint à la fois !

En résumé

J’espère que vous avez acquis une compréhension de base des éléments suivants :

Filtrage des listes SharePoint à l’aide du filtrage OData
Raisons pour lesquelles filtrer SharePoint
Façon dont vous pouvez modifier vos actions SharePoint pour renvoyer les données souhaitées