API de Talend Administration Center

Comment sont gérés les Jobs via Talend Administration Center ?

Les Jobs Talend sont planifiés dans Talend Administration Center, qui fournit une interface de gestion de navigation. Ils sont également paramétrés avec des variables de contextes. Mais souvent, les utilisateurs préférent avoir un contrôle par un programme sur les Jobs, via une API. Cet article explique comment exposer des Jobs Talend via l'API de Talend Administration Center. Il fournit des Jobs d'exemple, des utilitaires pratiques pour le navigateur et un exemple d'encapsulation (wrapping) de l'API dans une couche de services RESTful qui utilise les services de données.

La page Job Conductor de Talend Administration Center est simple d'utilisation et performante : elle vous permet de planifier des Jobs avec des déclencheurs Cron simples ou plus complexes ou avec des déclencheurs fichiers. Vous pouvez également lancer manuellement des Jobs depuis le navigateur. Excepté pour le déclencheur fichier, le Job s'exécute toujours à un moment pré-déterminé ou avec l'intervention explicite d'une personne. Pour utiliser des déclencheurs fichiers comme mécanisme de communication inter-processus, il peut vous être demandé de disposer de droits d'accès qui ne sont pas autorisés dans un environnement sécurisé. C'est pour cette raison qu'il est préférable de faire appel à un Job Talend via une vraie API.

Les Jobs peuvent être également paramétrés avec des variables de contextes. Les variables de contextes peuvent être écrasées par des administrateurs système sur la page Job Conductor pour plus de flexibilité. Mais lors de l'exécution du Job, celui-ci s'exécute toujours avec le même jeu de variables de contextes pré-configurées. Les variables de contextes, celles par défaut ou les valeurs écrasées, ne peuvent être modifiées sans intervention humaine. Il est préférable de pouvoir passer des paramètres via une API.

Il existe une option qui permet de construire des Jobs en tant que fichiers autonomes .zip. Les archives générées incluent des scripts d'exécution et tous les fichiers .jar nécessaires. Cependant, les Jobs qui en résultent s'exécutent en isolation et manquent de fonctions de monitoring, de gestion et de contrôle fournies par Talend Administration Center. Aucun mécanisme de connexion centralisé n'est fourni et il n'existe aucun concept de serveurs de Jobs ou de grille de Jobs. À la place, ces responsabilités incombent au développeur. Comme les solutions individuelles se multiplient, la gestion du système élargi est plus difficile et la maintenance devient plus pesante.

Ainsi, alors que les Jobs exportés fournissent plus de flexibilité, il est de plus en plus difficile de pouvoir les gérer. L'API de Talend Administration Center propose une alternative très simple d'utilisation et performante.

API de la MetaServlet de Talend Administration Center

Subscription

L'API de la MetaServlet de Talend Administration Center est une API HTTP de type RPC, (non RESTful) très simple d'utilisation et qui peut être facilement encapsulée dans une interface RESTful, si vous le souhaitez.

API de la MetaServlet

Toutes les opérations de la MetaServlet sont invoquées via une requête GET HTTP. Tous les paramètres de l'opération sont encodés en tant que seul paramètre sans nom, encodé en base-64 pour la requête GET.

L'invite de commande de la MetaServlet de Talend Administration Center est disponible dans le dossier suivant du répertoire d'installation de Talend Administration Center :

<tomcat_path>/webapps/org.talend.administrator/WEB-INF/classes/MetaServletCaller.bat sous Windows

<tomcat_path>/webapps/org.talend.administrator/WEB-INF/classes/MetaServletCaller.sh sous Linux

Lors de l'exécution de MetaServletCaller sans aucun argument, le message d'aide de haut niveau s'affiche :

<tomcat_path>\webapps\tac\WEB-INF\classes>MetaServletCaller.bat
usage: Missing required option: url
 -f,--format-output          format Json output
 -h,--help                   print this help message
 -json,--json-params <arg>   Required params in a Json object
 -url,--tac-url <arg>        TAC's http url
 -v,--verbose                display more informations

--tac-url

Pour obtenir l'intégralité du message d'aide, le service Talend Administration Center doit être opérationnel et vous devez transmettre le paramètre --tac-url.

--help all, -h all

Utilisez le paramètre --help all pour afficher l'intégralité de l'aide et le paramètre -h all pour une version abrégée. Les exemples ci-dessous capturent la sortie dans un fichier texte pour référence ultérieure.

<tomcat_path>\webapps\org.talend.administrator\WEB-INF\classes>MetaServletCaller.bat 
--tac-url=http://localhost:8080/org.talend.administrator/ -help all > tac-help.txt

<tomcat_path>\webapps\org.talend.administrator\WEB-INF\classes>MetaServletCaller.bat 
--tac-url=http://localhost:8080/org.talend.administrator/ -h > tac-help-short.txt

runTask

Exécute une tâche en fonction de son ID.

<tomcat_path>\webapps\org.talend.administrator\WEB-INF\classes>MetaServletCaller.bat 
--tac-url=http://localhost:8080/org.talend.administrator/ -help runTask
----------------------------------------------------------
  Command: runTask
----------------------------------------------------------
Description             : Allows to run a task defined in Job conductor by its id. 
Mode can be 'asynchronous' or 'synchronous'
Requires authentication : true
Since                   : 4.2
Sample                  :
{
  "actionName": "runTask",
  "authPass": "admin",
  "authUser": "admin@company.com",
  "jvmParams": [
    "-Xmx256m",
    "-Xms64m"
  ],
  "mode": "synchronous",
  "taskId": 1
}

Pour exécuter une tâche, vous devez connaître sa valeur de taskId générée par le système. Cette information peut être récupérée en exécutant la commande getTaskIdByName.

getTaskIdByName

Obtient l'ID correspondant de la tâche en recherchant sa valeur de taskName.

<tomcat_path>\webapps\org.talend.administrator\WEB-INF\classes>MetaServletCaller.bat --tac
-url=http://localhost:8080/org.talend.administrator/ -help getTaskIdByName
----------------------------------------------------------
  Command: getTaskIdByName
----------------------------------------------------------
Description             : Get task id by given taskName
Requires authentication : true
Since                   : 5.1
Sample                  :
{
  "actionName": "getTaskIdByName",
  "authPass": "admin",
  "authUser": "admin@company.com",
  "taskName": "task1"
}

Appel de l'API de Talend Administration Center de manière interactive

Subscription

Lorsque les développeurs utilisent l'API de la MetaServlet, il peut être pratique pour eux d'invoquer de manière interactive l'API de Talend Administration Center.

Procédure

Allez sur la page Job Conductor de Talend Administration Center, cochez la case de chaque colonne et assurez-vous que la case de la colonne Id est cochée afin qu'elle soit affichée.

Vous pouvez également récupérer l'ID de la tâche via la MetaServlet en exécutant la commande getTaskIdByName, consultez Commandes de l'API de la MetaServlet de Talend Administration Center.
Allez sur https://www.base64encode.org/ (en anglais) pour encoder les arguments de la MetaServlet JSON en base-64.

Collez le résultat encodé dans votre navigateur Web en utilisant la syntaxe suivante :

http://<host>:<port>/<TalendAdministrationCenter_name>/metaServlet?<base64_arguments>

http://localhost:8080/org.talend.administrator/metaServlet?ew0KICAiYWN0aW9uTmFtZSI6ICJydW5
UYXNrIiwNCiAgImF1dGhQYXNzIjogInRhZG1pbiIsDQogICJhdXRoVXNlciI6ICJ0YWRtaW5AZW9zdC5uZXQiLA0KI
CAibW9kZSI6ICJhc3luY2hyb25vdXMiLA0KICAidGFza0lkIjogIjgiDQp9DQo=

Conseil : Ajoutez cette URL comme marque-pages pour faciliter l'accès au site Web à l'avenir.

Le résultat du message GET HTTP est retourné en JSON à l'objet. Il inclut l'élément execRequestId qui gère la nouvelle instance de votre Job.

{ execRequestId: "1432855205979_a5zn8", executionTime: { millis: 564, seconds: 0 }, returnCode: 0 }

Une fois le message GET HTTP envoyé, monitorez la progression de l'exécution via la page Execution History de Talend Administration Center.

Appel de l'API de Talend Administration Center du code

Subscription

Une fois les arguments JSON encodés en base-64, ils peuvent être transmis en tant que paramètre unique à la requête GET HTTP. Si vous êtes dans Talend, votre application peut être écrite en Java ou dans un autre langage, ce qui ne doit poser aucun problème comme GET HTTP et base-64 sont devenus des standards interopérables.

Avant de commencer

Pour invoquer l'API de Talend Administration Center, les objets JSON doivent être encodés en base-64.

Procédure

Si êtes dans une application Java, utilisez la méthode de classe Apache Commons en base-64 : org.apache.commons.codec.binary.Base64.encodeBase64()
Si vous êtes dans Talend, utilisez le composant tLibraryLoad pour ajouter la bibliothèque Apache Commons.
Vous pouvez récupérer l'archive du Job de la MetaServlet dans l'onglet Téléchargements du panneau à gauche de cette page pour appeler l'API de Talend Administration Center dans le Job Talend.
Le Job utilise la méthode encodeBase64() dans un tMap avant invocation par le tRESTclient, des opérations de l'API de Talend Administration Center. Trois opérations sont invoquées et chaque opération est invoquée dans son sous-Job. Chaque sous-Job commence par l'initialisation de la requête dans les paramètres de contextes :
- Le premier appel cherche l'élément taskId en fonction du nom du Job lisible par un humain.
- Le deuxième appel utilise l'élément taskId retourné dans le premier appel pour déclencher le Job.
- Le troisième appel utilise l'élément execRequestId géré en tant qu'argument lors de l'opération getTaskExecutionStatus pour monitorer le statut du Job.

Problèmes connus

Subscription

Le résultat retourné par la commande getTaskIdByName n'est pas un format JSON correct. Il n'y a pas de guillemets autour du champ nommé task Id. Vous devez utiliser une expression régulière pour le remplacer avant d'analyser le JSON. Consultez TDI-32706 (en anglais).
La commande runTask ne documente pas l'argument de contexte mais elle le supporte. Consultez TDI-32519 (en anglais).
La commande runTask supporte l'argument de contexte, mais l'API de la Metaservlet ne le parse pas correctement s'il est le dernier argument du payload JSON soumis. Pour plus d'informations, consultez TDI-32380 (en anglais). Comme solution alternative, assurez-vous que la variable de contextes n'est pas le dernier argument (elle peut être transmise en deuxième au dernier argument par exemple).