Comment créer et configurer une fonction de connecteur HTTP ?

Apprenez à naviguer dans la fenêtre modale de la fonction connecteur et dans le processus de création.

Vue d'ensemble

Les fonctions de connecteur sont une fonctionnalité permettant de structurer la façon dont les applications Tulip interagissent avec les serveurs et les services externes. Si un connecteur est la connexion générale entre Tulip et le serveur externe, les fonctions de connecteur sont des requêtes spécifiques pour des services ou des informations. Dans cet article, nous allons vous expliquer comment créer et configurer une fonction de connecteur pour accéder à des éléments spécifiques de données ou d'informations à partir d'un service externe.

Pour plus d'informations sur les bases des API, consultez l'article Comment utiliser une API.

Configuration

Avant de créer une fonction de connecteur, vous devez créer un connecteur HTTP pour établir une connexion entre vos applications et le service avec lequel vous souhaitez communiquer. Vous créerez vos fonctions de connecteur au sein de ce connecteur, et chaque fonction de connecteur au sein d'un connecteur partagera la configuration de son connecteur parent. Pour créer un connecteur HTTP, suivez les étapes de cet article : Comment configurer un connecteur.

Une fois que vous avez créé un connecteur, il est temps de créer des fonctions de connecteur. Les fonctions de connecteur sont les opérations individuelles que votre connecteur exécute pour extraire des données du serveur d'API auquel vous vous connectez.

Créer une fonction de connecteur

Dans la page Connecteurs, sélectionnez le connecteur avec lequel vous souhaitez travailler en cliquant sur son nom.

Cette page affiche une liste de fonctions associées au connecteur. Pour créer une nouvelle fonction de connecteur, cliquez sur + Créer une fonction.

Pour faire court, nous supposerons dans cet article que vous connaissez déjà les différentes parties de l'éditeur de fonctions de connecteur.

Voici la procédure à suivre pour configurer une fonction de connecteur :

1. Sélectionnez le type API Call.
2. Écrire l'URL de l'API
3. Définir les entrées
4. Définir les paramètres des données renvoyées
5. Définir les sorties en utilisant la notation par points

Type d'appel et URL

Les deux premiers éléments à configurer pour toute fonction du connecteur HTTP sont le type d'appel de l'API (GET, POST, PUT, etc.) et l'URL du point de terminaison. Sélectionnez un type d'appel dans la liste déroulante et saisissez le chemin du point d'accès dans le champ qui suit l'URL de base. Consultez la documentation de l'API du service auquel vous souhaitez vous connecter pour obtenir une liste des points de terminaison et des détails de configuration.

:: :(Info) (NOTE)
In this article we’re using a piece of jargon: API Call. An API call, or API request, is a message sent to a server asking an API to provide a service or information. Since APIs are a way for one program to interact with another, calls are the process by which one application sends a request to another application.
:: :

Dans cet article, nous utiliserons l'API Document360 comme exemple, qui est le service qui héberge la base de connaissances de Tulip. La fonction que nous mettons en place renvoie un article avec ses propriétés associées en se basant sur l'ID de l'article.

Nommons notre fonction, définissons le type d'appel (GET) et saisissons l'URL de l'appel :

:: :(Info) (NOTE)
The call URL is case sensitive. Make sure you type it in exactly how you see it listed in the API documentation.
:: :

Obtenez le type d'appel et l'URL dans la documentation des points de terminaison de votre système. Ces deux actions déterminent votre requête REST. Pour un aperçu détaillé de ce qu'est une requête REST, voir Anatomie d'une requête REST.

En cliquant sur Test, vous exécutez la fonction et obtenez des informations dans la section Résultats du test de l'éditeur. En sélectionnant Body sous Test Results, vous pouvez voir le résultat complet et non filtré de votre requête. Génial, nous avons des données !

{{glossaire.Entrée}}s

:: :(Info) (Valid characters)
Connector function inputs allow letters from any languages, numbers, spaces, underscores, and dashes.
:: :

La configuration actuelle de notre fonction de connexion ne nous permet d'obtenir qu'un seul numéro d'article spécifique.

Notre objectif avec cette fonction est de la configurer de manière à ce qu'elle renvoie des informations sur tous les articles qui nous intéressent. Pour ce faire, nous devons modifier notre fonction afin de pouvoir passer une valeur pour n'importe quel identifiant d'article.

Nous pouvons modifier notre fonction de connecteur pour qu'elle prenne n'importe quelle valeur en configurant les entrées. Les entrées vous permettent de prendre des valeurs dans vos applications et de les passer dans les fonctions du connecteur.

Les entrées sont configurées en deux parties : 1.) créer une entrée dans le panneau d'entrée, 2.) spécifier où cette entrée sera utilisée dans la fonction de connecteur.

Tout d'abord, ajoutez un champ au volet de saisie. Vous pouvez modifier le type de données d'une entrée en cliquant sur l'icône située à côté du nom de l'entrée. Veillez à ce que le type sélectionné corresponde au type de la source que vous utiliserez dans vos applications. Le champ situé à côté du nom de l'entrée peut être utilisé pour tester les valeurs que vous souhaitez transmettre à votre fonction de connecteur et peut simuler les entrées de vos applications.

Ensuite, nous devons spécifier où cette entrée sera utilisée dans notre fonction de connecteur. Les entrées sont accessibles dans l'ensemble d'une fonction de connecteur, y compris dans l'URL du point de terminaison, les paramètres de requête et les extracteurs JSON dans les sorties. Veuillez consulter la documentation de l'API pour tout service que vous souhaitez utiliser pour plus d'informations sur la façon dont une fonction particulière doit être configurée.

Dans notre exemple, nous pouvons accéder à un article particulier en le spécifiant à la fin du chemin d'accès, ou à la place de "{articleId}".

En utilisant des entrées, nous pouvons passer dynamiquement une valeur dans cette URL, et donc utiliser cette fonction de connecteur pour obtenir des informations sur n'importe quel article que nous désirons.

Nous ajoutons des entrées au chemin d'accès en plaçant un signe de dollar**($**) avant et après le paramètre (dans ce cas, "ID"). La chaîne de caractères entre le signe dollar est sensible à la casse et doit correspondre exactement au nom de votre entrée. Reprenons notre exemple et modifions l'URL de manière à ce que l'ID soit aligné sur notre entrée. Le texte entre les signes du dollar se transforme en bloc, indiquant une propriété, comme suit :

Nous pouvons maintenant définir l'ID comme valeur d'entrée plutôt que de coder en dur la valeur directement dans l'URL du point final.

Pour ajouter d'autres entrées, cliquez sur le + dans le coin supérieur droit de la boîte d'entrée.

Paramètres

Les paramètres de requête sont des paires clé-valeur qui apparaissent après le ? dans le point final ou sous Paramètres de requête lors de la création d'une fonction de connecteur.

Maintenant que nous avons configuré nos entrées, vous pouvez créer des paramètres pour modifier les résultats du test et vous assurer que vous n'obtenez que les informations que vous souhaitez. Vous trouverez les clés et les valeurs de ces paramètres dans la documentation de l'API du serveur auquel vous vous connectez.

Avec les paires clé-valeur, l'un des composants est une "clé" et l'autre une "valeur" ; les deux sont ajoutés à la fin de l'URL du lien de votre formulaire. Les deux sont ajoutés à la fin de l'URL du lien de votre formulaire. Pensez-y comme à des jetons dans un courriel pour personnaliser le nom d'une personne. L'utilisation de paires clé-valeur vous permet de transmettre des informations à un formulaire.

La clé indique le nom d'une variable.

La valeur indique la valeur d'une propriété.

Dans cet exemple, nous voulons définir un paramètre qui garantit que l'article renvoyé est publié sur le site de la base de connaissances. En reprenant les informations données dans la documentation de l'API, le paramètre se présente comme suit :

Ces paramètres de requête et de demande sont des champs facultatifs à remplir, mais ils confèrent une spécificité aux résultats du test si vous en avez besoin.

{{glossaire.Sortie}}s

:: :(Info) (Valid characters)
Connector function outputs allow letters from any languages, numbers, spaces, underscores, and dashes.
:: :

Les sorties sont la partie de la fonction du connecteur qui indique les informations renvoyées directement. Elles sont structurées en notation par points, il faut donc prêter une attention particulière au format des résultats des tests pour vérifier que votre notation suit un chemin précis. Les sorties correspondent à des variables dans les applications, veillez donc à leur donner un nom identifiable et unique.

Notez que vous pouvez changer le type de sortie en listes en utilisant la bascule de liste; cette option imbrique les sorties variables dans les objets et mappe universellement le chemin de notation par points pour toutes les sorties imbriquées dans une liste d'objets.

Pour savoir si vos sorties sont correctement mappées, cliquez sur l'onglet "Sorties" dans le volet " Résultats des tests" et notez les résultats qui s'affichent.

Si les sorties correspondent aux résultats, félicitations ! Vous avez réussi à créer une fonction de connecteur opérationnelle et vous êtes prêt à l'utiliser dans des applications. Consultez la rubrique Utilisation des connecteurs HTTP dans les applications pour connaître les prochaines étapes.

Si votre fonction de connecteur ne fonctionne pas correctement, consultez notre guide de dépannage pour savoir ce qui ne va pas.

Suivez le cours de l'Université des connecteurs HTTP pour apprendre à construire des connecteurs.

Pour en savoir plus

• Comment formater les sorties des connecteurs HTTP

Vous avez trouvé ce que vous cherchiez ?

Vous pouvez également vous rendre sur community.tulip.co pour poser votre question ou voir si d'autres personnes ont rencontré une question similaire !