Configurer et utiliser l’API Trello avec Talend

Nos experts Talend vous donne une astuce pour configurer et utiliser l'API Trello avec Talend. Ce tutoriel vous sera utile pour apprendre à récupérer, lire et extraire les données de vos tableaux Trello dans le studio Talend. Vous découvrirez ainsi comment faire appel à un webservice pour créer un élément. Nos experts vous expliquent comment lire la réponse d’un appel à un webservice et stocker les informations nécessaires dans le contexte. Enfin, vous apprendrez à enchaîner la création de plusieurs éléments à la suite, mettre à jour et supprimer un élément. 

Création d'un compte Trello

Prérequis : vous avez besoin d'un compte Trello pour effectuer les exercices proposés dans ce tutoriel Talend.

Trello est un gestionnaire de tâches basé sur les méthodes agiles permettant de créer des listes de tâches par projet et d’y travailler en équipe.

Si vous n’avez pas de compte Trello, suivez les étapes suivantes pour en créer un. Allez sur le site de Trello www.trello.com puis cliquez sur S’inscrire.

Saisissez votre mail puis cliquez sur Créer un nouveau compte.

Saisissez votre nom (ou pseudo) ainsi que votre mot de passe et cliquez sur Créer un nouveau compte.

Vérifiez votre boîte mail et cliquez sur le lien qui vous a été envoyé pour vous connecter.

A ce stade, vous devriez avoir un tableau de base correspondant à un projet.

Rendez-vous ensuite sur la page https://trello.com/app-key.

Cochez la case et cliquez sur Afficher la clé d’API.

Copiez-collez sur votre poste la valeur du champ Identifiant. Il s’agira de notre identifiant d’API.

Cliquez ensuite sur le mot 'jeton' du premier paragraphe.

Autorisez l’utilisation de Server Token en bas de page.

Copiez-collez la valeur qui vous est donnée sur votre poste, il s’agira de notre jeton d’API.

Vous pouvez pour la suite utiliser l’API de Trello dont la documentation est disponible à cette URL : https://developers.trello.com/reference#introduction

Faire appel à un webservice

Nous allons maintenant voir comment faire un appel simple à un webservice pour créer un élément. 

Créez un nouveau Job nommé « TrelloAPI ».

Créez un nouveau groupe de contexte dans votre référentiel et appelez-le « Trello ».

A l’intérieur de ce nouveau groupe de contexte, créez les variables suivantes :

Cliquez sur Finish pour fermer la fenêtre.

Ajoutez ensuite votre contexte à votre nouveau Job en passant par le bouton de gestion des groupes de contextes.

Pour commencer, nous allons créer notre nouveau tableau, sans lequel la suite des opérations ne sera pas possible.

Pour cela, ajoutez un tPrejob.

Plusieurs composants permettent de faire appel à des webservices. Pour commencer, nous utiliserons celui qui est le plus complet, à savoir le tRESTClient.

Ce composant est ce qu’il y a de mieux pour travailler avec des webservices, d’ailleurs si vous le cherchez dans la palette vous verrez qu’il fait partie de la catégorie ESB, d’où l’utilisation en général de Talend ESB pour tout ce qui concerne les webservices.

Liez le tRESTClient avec un lien OnComponentOk et observez ses propriétés.

Modifiez l’URL pour faire appel à l’URL de votre contexte et ajoutez-y + 'boards/' pour faire appel à l’URL de gestion des tableaux.

Sachant que nous voulons créer un élément, choisissez POST comme Méthode http.

Ajoutez ensuite les paramètres suivants à votre requête. Attention, les « » sont obligatoires dans le nom des paramètres et pour les valeurs ne provenant pas du contexte.

Lancez votre Job et observez votre compte Trello, un second tableau s’est créé.

Récupération d’éléments et stockage dans le contexte

L'objectif est maintenant de lire la réponse d’un appel à un webservice et stocker les informations nécessaires dans le contexte.

Désactivez vos 2 composants précédents puis ajoutez à nouveau un tRESTClient qui nous servira à récupérer les informations sur l’utilisateur.

Modifiez son URL pour faire appel à l’URL des utilisateurs à savoir notre URL de contexte suivie de +'members/' + context.API_USERNAME et saisissez votre identifiant et jeton dans les paramètres de la requête.

Cette fois-ci la Méthode HTTP est du GET et nous souhaitons envoyer du JSON.

Regardez maintenant ses paramètres avancés.

Le champ qui nous intéresse est Convertir la réponse en document DOM cochée par défaut. En étant cochée, le type de retour de la réponse sera du XML, en la décochant le type de retour sera du JSON.

Laissez-la cochée car nous allons traiter un retour de type XML dans un premier temps et nous traiterons du JSON par la suite.

Ajoutez un tLogRow pour afficher le résultat de votre appel. Vous remarquerez que la liaison disponible depuis le tRESTClient n’est pas Main mais Réponse.

Vous pouvez voir que votre réponse se situe dans la variable body et qu’il s’agit bien de XML.

Supprimez votre tLogRow et ajoutez un tExtractXMLField relié par un Réponse à la place.

Rendez-vous dans ses propriétés.

Il faut tout d’abord définir quel champ contient le XML, nous avons vu qu’il s’agissait de body et ensuite la Requête XPath boucle, soit l’élément racine de notre XML, donc root.

Nous allons pour la suite du Job avoir besoin de récupérer l’ID de l’utilisateur.

Modifiez le schéma du tExtractXMLField et ajoutez une colonne id de type String.

Votre nouvelle colonne devient accessible dans le Mapping de votre composant.

Sachant que l’identifiant présent dans la réponse reçue s’appelle également id, modifiez la valeur de Requête XPath de la colonne id pour y mettre 'id'.

Une fois le mapping effectué, nous allons devoir récupérer l’identifiant et le stocker en variable de contexte pour faire nos futurs appels.

Ajoutez un composant tJavaRow et liez-le par un lien Main. Ainsi les données récupérées vont transitez jusqu’à ce nouveau composant.

Dans le code du composant saisissez : context.API_USERID = input_row.id;

Nous allons ensuite récupérer les tableaux de l’utilisateur pour pouvoir stocker l’identifiant du tableau que nous avons créé auparavant.

Il est tout à fait possible d’utiliser à nouveau un tRESTClient, mais cette fois-ci nous allons voir un autre composant permettant d’appeler un webservice.

Sous le sous-job précédent ajoutez un composant tREST.

Rendez-vous dans ses paramètres et remplissez son URL :

context.API_URL +'members/' + context.API_USERID + '/boards'

Choisissez GET comme Méthode HTTP et saisissez votre identifiant et jeton.

Vous remarquez qu’il y a nettement moins d’options que pour le tRESTClient. Ici nous n’avons que le strict nécessaire.

Il faut savoir que le tREST ne laisse pas le choix sur le type de retour, il renverra ce que le serveur lui répond. Lors d’un POST il est éventuellement possible de définir quel type de données est envoyé en ajoutant des en-têtes HTTP appropriées.

Sachant que notre API nous répond de base du JSON, nous allons avoir besoin d’ajouter un composant tExtractJSONFields que nous allons lier avec un Main.

Vous pouvez voir que ses propriétés sont similaires au tExtractXMLField.

Choisissez Xpath comme lecteur définissez votre champ contenant les informations, ici Body.

Dans la Requête Xpath boucle, saisissez simplement '' pour signifier de prendre l’élément racine.

Pour chaque tableau, nous allons avoir besoin de récupérer son nom et son identifiant. Modifiez donc le schéma de votre tExtractJSONFields pour ajouter les colonnes id et name de type String.

Faîtes ensuite correspondre vos colonnes dans le Mapping.

Nous allons ensuite ajouter un tFilterRow pour spécifier qu’on ne veut que le tableau que l’on a créé au début du Job en le filtrant par son nom.

De la même façon que précédemment, nous allons ajouter un tJavaRow pour stocker l’identifiant reçu dans le bon contexte en marquant : context.BOARD_ID = input_row.id;

Nous allons maintenant créer notre première liste sur ce tableau.

Pour cela nous allons utiliser le troisième composant permettant d’appeler un webservice.

Ajoutez un tHttpRequest en dessous de votre sous-job. La différence avec les deux composant précédents est que celui-ci fait simplement appel à une URL comme peut le faire tout navigateur.

Ouvrez ses propriétés.

Dans le champ URI, vous devez renseigner non seulement l’URL de base mais aussi tous les paramètres à envoyer :

context.API_URL + 'lists?key='+context.API_KEY+'&token='+context.API_TOKEN+'&name=Colonne1&idBoard='+context.BOARD_ID

Vous pouvez voir que ce composant est déjà beaucoup moins pratique à utiliser que les autres. En revanche il est possible d’envoyer les paramètres depuis un fichier.

Sélectionnez POST comme Méthode. Contrairement aux autres, seules les méthodes GET et POST sont utilisables.

Comme pour le sous-job précédent, nous allons lire les données avec un tExtractJSONFields dans lequel nous allons ajouter une colonne id pour récupérer l’identifiant de la liste que l’on crée. N’oubliez également pas de mapper votre colonne.

Voyez également que nous n’avons pas le choix pour le Champ JSON car le tHttpRequest ne possède qu’un seul champ en sortie.

Il reste ensuite à sauvegarder notre identifiant dans le contexte.

Ajoutez à nouveau un tJavaRow avec ce code : context.LIST_ID = input_row.id;

Liez vos 3 sous-jobs avec des OnSubJobOk pour qu’ils s’exécutent dans le bon ordre.

Lancez votre Job.

Observez votre tableau Trello, vous devriez voir une liste se créer.

Création multiples, mises à jour et suppression 

Dans cette dernière partie, nous allons voir comment créer plusieurs éléments à la suite, mettre à jour et supprimer un élément.

Maintenant que nous avons notre liste dans Trelo, nous allons apprendre à créer des cartes dans celle-ci.

Pour créer plusieurs cartes à la suite, nous pourrions lire les données depuis un fichier ou une table. Dans notre cas nous allons simuler un flux de données.

Ajoutez un tFixedFlowInput à la suite de votre Job. Ce composant permet de générer un flux de données selon notre choix.

Dans ses propriétés, cochez simplement Utiliser du contenu personnalisé (fichier délimité), cela simulera la lecture d’un fichier CSV.

Dans son Contenu, marquez :

Carte 1

Carte 2

Carte 3

Carte 4

Liez ce composant aux sous-jobs précédents avec un OnSubjobOk.

Nous allons maintenant créer nos cartes.

Ajoutez un tRESTClient et liez-le par un Main. Il sera ainsi appelé autant de fois qu’il y a de cartes.

Renommez la liaison en « cartes » puis ouvrez les propriétés du tRESTClient.

Comme URL, remplissez context.API_URL + 'cards' et choisissez POST comme Méthode HTTP ainsi que JSON comme Type de contenu et Accepter Type.

Ajoutez-lui les paramètres suivants :

Remarquez que « cartes.name » correspond à la valeur du nom récupéré depuis la liaison entre les 2 composants. Si vous aviez laissé une liaison nommée par défaut row[N°], alors la valeur à mettre aurait été row[N°].name.

Pour une fois vous pouvez ignorer l’avertissement présent sur le tRESTClient, il est normal de ne pas avoir le même schéma des deux côtés.

Récupérez la réponse dans un tExtractXMLField comme vu précédemment, ajoutez-lui une colonne name et une colonne id et mappez ces 2 champs.

Nous allons maintenant filtrer nos cartes pour stocker d’un coté l’identifiant d’une carte à modifier (Carte 3), et de l’autre l’identifiant d’une carte à supprimer (Carte 1).

En nous en tenant aux composants déjà vus, nous pouvons réaliser ceci en ajoutant un TFilterRow pour filtrer d’un côté la carte 3 et en enchainer un 2^nd sur les rejets pour cette fois-ci filtrer la carte 1.

Nous allons cependant faire cela un peu différemment car si pour une raison nous avions voulu avoir également la carte 3 dans le second filtre, cela n’aurait pas été possible de cette manière.

Ajoutez à droite de votre tExtractXMLfield un composant tReplicate et récupérez le schéma dans celui-ci.

Si vous ouvrez ses propriétés vous pouvez voir qu’il n’y a rien à configurer. En réalité ce composant sert uniquement à dupliquer un flux entrant sur plusieurs sorties.

Ajoutez un tFilterRow à la suite dans lequel vous filtrez le nom « Carte 3 » et reliez-le au tReplicate.

Ajoutez ensuite un tJavaRow pour stocker l’identifiant dans le contexte avec ce code :

context.CARD_ID = input_row.id;

A présent, ajoutez un second tFilterRow sous le premier en filtrant cette fois-ci le nom « Carte 1 ».

En faisant un clic droit sur le tReplicate vous pouvez voir que vous pouvez créer un autre lien Main, reliez donc les deux composants.

Pour finir, ajoutez un autre tJavaRow pour stocker l’identifiant dans le contexte en marquant :

context.CARD_ID_TO_DELETE= input_row.id;

Dans votre tableau Trello, supprimer la liste existante en cliquant sur les « … » puis Archiver cette liste.

Relancez votre Job.

Cette fois-ci la liste s’est créée et des cartes ont été ajoutées.

Nous allons créer une seconde liste qui accueillera notre carte modifiée.

Ajoutez à la suite un nouveau tRESTClient appelant l’URL des listes : context.API_URL + 'lists'

Saisissez-lui les paramètres suivants :

Spécifiez qu’il s’agit d’un POST et que l’on envoie du JSON.

Récupérez son identifiant avec un tExtractXMLField.

Stockez l’identifiant dans la variable de contexte avec un tJavaRow :

context.LIST_ID = input_row.id;

Nous allons ensuite enchaîner 2 mises à jour de cartes.

Ajoutez un TRESTClient appelant l’URL des cartes : context.API_URL + 'cards/' + context.CARD_ID

Spécifiez qu’il s’agit d’un PUT comme Méthode HTTP et que le contenu est du JSON.

Ajoutez vos paramètres :

Copiez-collez ce composant avec un autre tRESTClient.

Cette fois-ci définissez lui les paramètres suivants :

Enfin nous allons supprimer une carte.

Ajoutez un dernier tRESTClient appelant l’URL :

context.API_URL + 'cards/' + context.CARD_ID_TO_DELETE

Sélectionnez la méthode DELETE.

Envoyez votre identifiant et jeton en paramètre comme pour les appels précédents.

Nous avons tous nos éléments.

Reliez tous vos éléments dans le bon ordre avec des OnSubjobOk. Entre chaque sous-Job de création et de modification vous pouvez ajouter un composant tSleep configuré avec la variable de contexte SLEEP_TIME (que nous avons défini à 2s), cela nous permettra d’avoir le temps de visualiser chaque action effectuée.

Votre Job final devrait ressembler à ceci :

Dans votre tableau Trello, cliquez sur Afficher le menu.

 Cliquez ensuite sur « … » Plus.

Cliquez sur Fermer le tableau puis sur le bouton rouge Fermer lorsque l'on vous le propose.

Cliquez enfin sur Supprimer définitivement le tableau.

Cliquez sur l’icône Maison pour retourner à votre page d’accueil.

Lancez votre Job.

Dès que votre tableau apparaît ouvrez-le immédiatement en cliquant dessus. Vous devriez ensuite pouvoir observer une à une les étapes de votre Job.

Si vous souhaitez revoir les étapes avec votre tableau ouvert, supprimez simplement les 2 listes et dans votre Job désactivez la création du tableau avant de le ré exécuter.