Comment définir les paramètres d'une requête

Apprenez les principes fondamentaux de l'utilisation des paramètres de requête dans vos fonctions de connecteur HTTP, conformément à la documentation de l'API.

Les paramètres de requête vous permettent d'affiner et d'adapter les résultats d'une fonction de connecteur. Utilisez les paramètres pour trier, filtrer, définir des limites, compenser un index, etc. Cet article utilise les paramètres de l'API Tulip Table, mais d'autres API peuvent avoir des exigences différentes en matière de paramètres. Veillez à consulter la documentation pour vous assurer que vous utilisez la syntaxe et les spécifications correctes.

Requête avec des filtres

Les filtres peuvent être très utiles pour extraire uniquement les données qui vous intéressent. La syntaxe de ces filtres peut parfois être un peu délicate. Les paragraphes suivants décrivent la façon dont chaque filtre est formé dans l'exemple d'une requête GET pour des enregistrements, suivi d'un exemple complet.

Lesnoms des champs personnalisés sont toujours précédés d'un identifiant à cinq chiffres. Il est plus facile de les trouver après une requête GET all pour vérifier le véritable nom du champ.

• Ex. "field"="maytq_scrap_count"

Les valeurs desarguments sont souvent simples. S'il s'agit d'une valeur textuelle, veillez à la mettre entre guillemets.

• Ex. "arg":15

Faites correspondre le type de fonction que vous souhaitez utiliser.

• Ex. "functionType" : "greaterThan" (plus grand que)

Une requête complète pourrait ressembler à ceci :

https://brian.tulip.co/api/v3/tables/W2HPvyCZrjMMHTiip/records?limit=100&sortBy=\_sequenceNumber&sortDir=asc&filters=[{"field" : "maytq\_scrap\_count", "arg":15, "functionType" : "greaterThan"}]&filterAggregator=any

Comment trouver les paramètres de requête dans la documentation

Pour trouver les paramètres de requête disponibles pour votre demande, consultez la documentation de l'API. Si vous utilisez l'API Tulip Table, vous pouvez trouver la documentation à l'adresse suivante : your-instance.tulip.co/apiDocs. Sélectionnez la requête que vous souhaitez utiliser, puis faites défiler vers le bas jusqu'à l'onglet Parameters.

Chaque méthode individuelle a ses propres paramètres, mais toutes les requêtes n'ont pas de paramètres associés. Veillez à prendre connaissance de ce qui est disponible dans la documentation au préalable.

Syntaxe des paramètres de requête

La syntaxe des requêtes de paramètres repose sur un format de chaîne de requête. Ce format attribue des valeurs aux paramètres spécifiés, la chaîne de requête faisant elle-même partie de l'URL.

Dans l'éditeur de fonction du connecteur, cliquez sur Ajouter un paramètre pour créer un nouveau paramètre de requête.

Un paramètre de requête se compose de deux parties : une clé et une valeur. La clé est le nom du paramètre et la valeur est l'information qui définit le paramètre pour les résultats.

La syntaxe des paramètres de requête utilise Dot Notation, qui spécifie le type exact de paramètre. Veillez à ce que la casse de l'écriture corresponde à la norme API de l'autre système.

Appliquer des paramètres communs aux fonctions de connecteur

Afin de définir un paramètre pour votre fonction de connecteur, identifiez d'abord le paramètre que vous souhaitez utiliser dans la documentation de l'API. Les paramètres ont des exigences différentes pour chacun d'entre eux, nous allons donc voir à quoi ils ressemblent.

:::(Info) (REMARQUE) À des fins de continuité, nous utiliserons la même requête API Call dans chacun des exemples ci-dessous. Il s'agit de la requête GET qui permet de récupérer une liste d'enregistrements dans une table de tulipes via l'API Tulip Table. Les autres API que vous utilisez auront des spécifications différentes pour les paramètres, assurez-vous de consulter les exigences de la documentation de l'API ::: :

Limites

Les limites définissent un plafond pour les résultats renvoyés. Notez que certaines limites ont des paramètres par défaut. Veillez donc à consulter la documentation de l'API pour comprendre la valeur initiale.

ExempleNous ne voulons pas obtenir plus de 70 enregistrements lorsque la fonction de connecteur s'exécute. Heureusement, la valeur par défaut de la limite dans cette requête est 10 et la valeur la plus élevée est 100. La syntaxe du paramètre de la requête doit ressembler à ce qui suit :

Filtres

Les filtres séparent et affinent les résultats en fonction des informations fournies par le paramètre.

Les filtres comportent trois parties, que vous devez écrire dans des paramètres individuels :

• Champ - le nom de la colonne dans le tableau
• Type de fonction - le type de fonction de comparaison
• Argument - la valeur à laquelle comparer les résultats.

Chaque filtre comporte trois parties et chaque filtre complet est un objet. En utilisant la notation en points pour écrire chaque clé, indiquez le type de paramètre ("filter"), le numéro du filtre (0 à n) et la partie du filtre ("field", "functionType" ou "arg"). Il doit y avoir un paramètre pour les trois parties du filtre.

ExempleNous voulons nous assurer que les résultats de la fonction de connecteur n'affichent que les valeurs d'un champ spécifique (eubmc_value) qui sont égales à la valeur d'entrée spécifiée (consommable) de la fonction. Comme il s'agit de notre premier filtre dans les paramètres de la fonction, le numéro du filtre est 0, ce qui signifie que chaque clé de ce filtre commencera par "filter.0". La syntaxe de ce filtre devrait ressembler à ce qui suit :

Tri

Le tri des résultats hiérarchise l'affichage sur la base des informations du paramètre. Les résultats triés déterminent ceux qui sont inclus dans les agrégations. Vous pouvez avoir plusieurs fonctions de tri, mais c'est l'ordre des options qui détermine la priorité du tri.

Les fonctions de tri sont composées de deux parties :

• sortBy - le champ par lequel vous souhaitez trier les résultats
• sortDir - la direction du tri, soit ascendante (asc), soit descendante (desc).

Chaque fonction de tri comporte trois parties. En utilisant la notation en points pour écrire chaque clé, spécifiez le type de paramètre ("sortOptions"), le numéro de tri (0 à n) et l'argument de tri ("sortBy" ou "sortDir"). Il doit y avoir un paramètre pour les trois parties de la fonction de tri pour qu'elle fonctionne.

ExempleNous voulons que les résultats de la fonction de connexion soient triés selon le champ mis à jour le plus récemment, dans un ordre croissant. Comme il s'agit de notre première fonction de tri, le numéro de tri est 0, ce qui signifie que les deux clés de ce tri commenceront par "sortOptions.0". Pour la clé sortBy, la valeur est une valeur spéciale ("_updatedAt") dérivée de la documentation de l'API pour trier les champs mis à jour. La syntaxe de ces paramètres doit ressembler à ce qui suit :

Offsets

Les décalages déterminent l'index auquel le résultat retourné doit commencer. Ce paramètre est utilisé pour la pagination, et non pour l'ordre des enregistrements, qui est déterminé par les paramètres de tri. La valeur du paramètre doit être un nombre entier supérieur ou égal à 0.

ExempleNous voulons afficher uniquement les enregistrements à partir de la 5e position, afin de ne pas voir les 5 premiers résultats. La syntaxe du paramètre de requête doit ressembler à ce qui suit :

Agrégateurs de filtres

Les agrégateurs de filtres déterminent la manière dont les filtres des paramètres sont combinés. Les deux valeurs possibles sont "any" et "all". La valeur "tous" signifie que tous les filtres doivent contenir un enregistrement pour que celui-ci soit inclus dans les résultats. La valeur "any" signifie qu'au moins un des filtres doit correspondre à un enregistrement pour que celui-ci soit inclus dans les résultats. La valeur par défaut est "tous", que vous ayez ou non défini le paramètre.

ExempleNous avons une série de filtres dans les paramètres de la requête, mais il suffit qu'un seul de ces filtres soit vrai pour que les enregistrements correspondent à notre demande. La syntaxe du paramètre de requête devrait ressembler à ce qui suit :

Filtres multiples

Dans certains cas, vous pouvez avoir plusieurs filtres à vérifier dans le tableau. Dans ce cas, vous pouvez ajouter plusieurs filtres à l'objet filters. Cela pourrait ressembler à ce qui suit :

filters=[{"field" : "maytq\scrap\_count", "arg":15, "functionType" : "greaterThan"},{"field" : "maytq\scrap\_reason", "arg" : "scratch", "functionType" : "equal"}]

Pour en savoir plus

• Vue d'ensemble des connecteurs HTTP
• Comment créer et configurer une fonction de connecteur HTTP ?
• Comment utiliser l'API Table