API de Talend Administration Center - 7.3

author
Talend Documentation Team
EnrichVersion
7.3
EnrichProdName
Talend Big Data
Talend Big Data Platform
Talend Data Fabric
Talend Data Integration
Talend Data Management Platform
Talend Data Services Platform
Talend ESB
Talend MDM Platform
Talend Real-Time Big Data Platform
task
Administration et monitoring > Gestion des projets
Administration et monitoring > Gestion des utilisateurs
Administration et monitoring > Monitoring des exécutions
Déploiement > Ordonnancement > Ordonnancement de Jobs
EnrichPlatform
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.

Talend Administration Center MetaServlet API

The Talend Administration Center MetaServlet API is an RPC style HTTP API, (not restful) that it is very easy to use and can be easily wrapped with a RESTful interface if desired.

MetaServlet API

All MetaServlet operations can be invoked via an HTTP POST or GET request. All parameters to the operation are encoded as a single, unnamed base-64 encoded parameter to the request.

The Talend Administration Center MetaServlet command-line tool is available in the following folder of the Talend Administration Center installation directory:

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

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

Running the MetaServletCaller with no arguments shows the top level help message:
<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

In order to get the full detailed help message, the Talend Administration Center service must be up and running and you must pass the --tac-url parameter.

--help all, -h all

Use --help all to get the full help, and the -h all for an abbreviated version. The examples below capture the output to a text file for subsequent reference.
<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

Runs a task based on its 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
}

In order to run a task, you need to know its system generated taskId. This information can be retrieved by executing the getTaskIdByName command.

getTaskIdByName

Gets the corresponding ID of the task by looking for its 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"
}

Invoking the Talend Administration Center API interactively

When developers work with the MetaServlet API, it can be useful for them to interactively invoke the Talend Administration Center API.

Procédure

  1. Go to the Job Conductor page of Talend Administration Center, select the arrow icon next to any of the columns and make sure the Id column is checked so that it will be displayed.

    Note that you can also retrieve the ID of the task using MetaServlet by executing the getTaskIdByName command, see Talend Administration Center MetaServlet API commands.

  2. Go to https://www.base64encode.org/ to encode the MetaServlet JSON arguments in base64.
  3. Send the encoded result with the POST or GET operation to the http://<host>:<port>/<TalendAdministrationCenter_name>/metaServlet URL. It is recommended to use the POST operation with the parameters in the body instead of GET for additional security.
    The result of the HTTP message is returned as JSON to the object. It includes the execRequestId which is the handle for your new Job instance.
    { execRequestId: "1432855205979_a5zn8", executionTime: { millis: 564, seconds: 0 }, returnCode: 0 }
  4. Once the HTTP message is sent, monitor the progress of the execution through the Execution History page of Talend Administration Center.

Invoking the Talend Administration Center API programmatically

Once the JSON arguments are base-64 encoded, they can be passed as the sole parameter to the HTTP request. If you are integrating with Talend, your application might be written in regular Java, or possibly some other language, which should not cause any issues since the HTTP and base-64 are interoperable standards.

Avant de commencer

To invoke the Talend Administration Center API, the JSON objects must be base-64 encoded.

Procédure

  1. If you happen to be integrating with a Java application, use the following Apache Commons Base64 class method: org.apache.commons.codec.binary.Base64.encodeBase64()
  2. If you are using Talend, use the tLibraryLoad component to add the Apache Commons library.

    You can retrieve the MetaServlet Job archive attached to the Downloads tab on the left panel of this page to invoke the Talend Administration Center API from the Talend Job.

    It uses the encodeBase64() method within a tMap prior to the tRESTclient invocation of the Talend Administration Center API operations. Three operations are invoked, and each operation is invoked within its own SubJob. Each SubJob starts by initializing the request from the Context Parameters:
    • The first invocation looks up the taskId based on the human readable Job name.
    • The second invocation uses the taskId returned from the first invocation to trigger the Job.
    • The third invocation uses the returned execRequestId handle as the argument to the getTaskExecutionStatus operation to monitor the Job status.

Problèmes connus

  • 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).