tRESTClient - 6.1

Composants Talend Guide de référence

EnrichVersion
6.1
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 Open Studio for Big Data
Talend Open Studio for Data Integration
Talend Open Studio for Data Quality
Talend Open Studio for ESB
Talend Open Studio for MDM
Talend Real-Time Big Data Platform
task
Création et développement
Gouvernance de données
Qualité et préparation de données
EnrichPlatform
Studio Talend

Propriétés du tRESTClient

Famille du composant

ESB/REST

 

Fonction

Le composant tRESTClient envoie des requêtes HTTP et HTTPS à un fournisseur des services Web REST (REpresentational State Transfer) et obtient les réponses correspondantes. Ce composant s'intègre parfaitement dans Talend Runtime pour un support de HTTPS et, ultérieurement, le support de fonctionnalités de qualité de service.

Objectif

Le composant tRESTClient est utilisé pour interagir avec des fournisseurs de services Web RESTful, en envoyant des requêtes HTTP et HTTPS, à l'aide de CXF (JAX-RS).

Basic settings

URL

Saisissez l'URL du serveur REST à invoquer. Lorsque la case Use Service Locator est cochée, ce champ ne s'affiche pas et l'URL du serveur REST est obtenue automatiquement du serveur du Service Locator.

 Relative Path

Saisissez le chemin d'accès relatif au serveur REST à invoquer.

Par exemple, vous souhaitez accéder à http://localhost:8888/services/Customers/list :

Si la case Use Service Locator est décochée : vous pouvez saisir la première partie de l'adresse dans le champ URL et la seconde partie dans le champ Relative Path. Par exemple, saisissez http://localhost:8888 dans le champ URL et /services/Customers/list dans le champ Relative Path. Vous pouvez également saisir le chemin d'accès complet au serveur REST dans le champ URL et laisser vide le champ Relative Path.

Si la case Use Service Locator est cochée : la partie dans le champ URL est donnée par le Service Locator. Dans ce cas, vous devez connaître la partie URL et spécifier la suite dans le champ Relative Path. Elle dépend du service interrogé. Par exemple, dans le tRESTRequest, vous pouvez paramétrer l'endpoint REST Endpoint à http://localhost:8888/services et cocher la case Use Service Locator. Si vous souhaitez utiliser ce service, du côté tRESTClient, vous devez spécifier /customers/list dans le champ Relative Path.

 

HTTP Method

Dans cette liste, sélectionnez une méthode HTTP décrivant l'action souhaitée. Les significations des méthodes HTTP sont sujets aux définitions de votre fournisseur de service Web. Les définitions des méthodes HTTP généralement acceptées sont listées ci-dessous :

- GET : récupère des données du côté serveur selon les paramètres donnés.

- POST : charge des données dans le serveur selon les paramètres donnés.

- PUT : met à jour des données selon les paramètres donnés, ou crée les données, si elles n'existent pas.

- PATCH : modifie partiellement les données selon les paramètres donnés.

- DELETE : supprime les données selon les paramètres donnés.

 Content Type

Sélectionnez XML, JSON ou FORM selon le type de média du contenu à charger dans le serveur.

Cette liste apparaît lorsque vous sélectionnez la méthode HTTP POST, PUT ou PATCH.

 Accept Type

Sélectionnez le type de média que le côté client est préparé à accepter pour la réponse, du côté serveur.

Les options disponibles sont : XML, JSON et ANY. Lorsque ANY est sélectionnée, le message de réponse peut être de tout type et sera transformé en une chaîne de caractères (string).

 Query parameters

Spécifiez les paramètres de la requête sous forme de paires nom-valeur.

Cette option est généralement utilisée avec la méthode GET.

Schema et Edit Schema

Un schéma est une description de lignes, il définit le nombre de champs qui sont traités et passés au composant suivant.

Ce composant utilise trois schémas built-in, en lecture seule.

Cliquez sur Edit Schema pour visualiser la structure du schéma.

Avertissement

Modifier le type du schéma peut conduire à une perte de cette structure et à un échec de l'exécution du composant.

 Input Schema

Schéma des données d'entrée. Le schéma contient deux colonnes :

- body : stocke le contenu des données d'entrée structurées

- string : stocke le contenu d'entrée lorsqu'il est de type string, ou est géré comme tel.

 Response Schema

Schéma pour la réponse du serveur. Ce schéma est passé au composant suivant à l'aide d'un lien Row > Response et contient trois colonnes:

- statusCode : stocke le code de statut HTTP du serveur.

- body : stocke le contenu d'une réponse structurée du serveur.

- string : stocke le contenu de la réponse du serveur, lorsqu'elle est de type string ou gérée comme telle.

 Error Schema

Schéma pour les informations d'erreur. Ce schéma est passé au composant suivant via un lien Row > Error et contient deux colonnes :

- errorCode : stocke le code de statut HTTP du serveur lorsqu'une erreur survient durant le processus d'invocation. L'interprétation des codes d'erreur spécifiques est soumise aux définitions de votre fournisseur de services Web. Pour des informations de référence, consultez le site http://fr.wikipedia.org/wiki/Liste_des_codes_HTTP.

- errorMessage : stocke le message d'erreur correspondant au code d'erreur.

 Use Service Locator

Cochez cette case pour activer le Service Locator. Cela maintient la disponibilité du service et permet de répondre aux demandes et de respecter les (SLAs). Spécifiez l'espace de noms du Service ainsi que le nom du Service dans les champs correspondants.

 Use Service Activity Monitor

Cochez cette case pour activer le Service Activity Monitor. Il capture les événements et stocke les informations afin de faciliter les analyses en profondeur de l'activité des services et de suivre les messages via une transaction métier. Cette option peut être utilisée, entre autres, pour analyser le temps de réponse du service, identifier les modèles de trafic ou effectuer une analyse de cause racine.

 Use Authentication

Cochez cette case si l'authentification est requise du côté du serveur REST. Sélectionnez Basic HTTP, HTTP Digest, SAML Token (ESB runtime only) ou OAuth2 Bearer dans la liste. L'authentification SAML Token fonctionne uniquement avec le Runtime. Si vous sélectionnez Basic HTTP, HTTP Digest ou SAML Token (ESB Runtime only), vous devez saisir votre identifiant et votre mot de passe.

Pour saisir le mot de passe, cliquez sur le bouton [...] à côté du champ Password, puis, dans la boîte de dialogue qui s'ouvre, saisissez le mot de passe entre guillemets doubles, puis cliquez sur OK afin de sauvegarder les paramètres.

Si vous utilisez OAuth2 Bearer, renseignez le champ Bearer Token avec votre jeton d'authentification encodé en base64.

 

Use Authorization

Cochez cette case pour activer les appels autorisés. Spécifiez le rôle du client dans le champ Role. Cette option apparaît lorsque l'option SAML Token (ESB runtime only) est sélectionnée dans la liste Use Authentication.

Pour plus d'informations concernant la gestion des rôles et des droits des utilisateurs, consultez le Guide utilisateur de Talend Administration Center et le Guide Talend ESB Infrastructure Services Configuration Guide (en anglais).

 

Use Business Correlation

Cochez cette case pour créer un ID de corrélation dans ce composant.

Vous pouvez spécifier un ID de corrélation ID dans le champ Correlation Value. Dans ce cas, l'ID de corrélation est passé au service qu'il appelle, afin que les appels en chaîne des services soient groupés sous cet ID de corrélation. Si vous laissez ce champ vide, cette valeur est générée automatiquement lors de l'exécution.

Lorsque cette option est activée, le tRESTClient extrait également l'ID de corrélation de l'en-tête de réponse et le stocke dans la variable du composant pour usage ultérieur dans le flux.

 

Die on error

Cette case est cochée par défaut et stoppe le Job en cas d'erreur. Décochez cette case pour terminer le traitement avec les lignes sans erreur, et ignorer les lignes en erreur.

Advanced settings

Log messages

Cochez cette case pour enregistrer l'échange de messages entre le service et le consommateur.

 

Convert Response To DOM Document

Cochez cette case afin de convertir la réponse du serveur en type Document.

Décochez cette case si vous souhaitez que la réponse soit traitée comme une chaîne de caractères.

 Drop JSON Request RootCette option apparaît lorsque vous avez sélectionné POST, PUT ou PATCH dans la liste HTTP Method et JSON dans la liste Content Type. Cochez cette case pour supprimer les éléments JSON racine.
 

Wrap JSON Response

Cette option est disponible et activée par défaut lorsque l'option JSON est sélectionnée dans la liste Accept Type de la vue Basic settings.

Lorsque cette case est cochée, la réponse est entourée d'un élément root. Décochez cette case si vous souhaitez supprimer cet élément root de la réponse.

 HTTP Headers

Saisissez la (les) paire(s) nom-valeur des en-têtes HTTP pour définir les paramètres de l'opération HTTP demandée.

Pour les définitions spécifiques des en-têtes HTTP, consultez votre fournisseur de services Web REST. Pour des informations de référence, consultez en.wikipedia.org/wiki/List_of_HTTP_headers (en anglais).

 

Disable chunked encoding

Cette option apparaît uniquement lorsque la méthode dans la liste HTTP Method est POST, PUT ou PATCH. Cochez cette case pour désactiver l'encodage des payloads par morceaux.

Service Locator Customer PropertiesCette table apparaît lorsque la case Use Service Locator est cochée. Vous pouvez ajouter autant de lignes que nécessaire afin de personnaliser les propriétés correspondantes. Saisissez entre guillemets le nom et la valeur de chaque propriété dans le champ Property Name et Property Value respectivement.
 Service Activity Customer PropertiesCette table apparaît lorsque la case Use Service Activity Monitor est cochée. Vous pouvez ajouter autant de lignes que nécessaire afin de personnaliser les propriétés correspondantes. Saisissez entre guillemets le nom et la valeur de chaque propriété dans le champ Property Name et Property Value respectivement.
 

Connection timeout

Configurez le temps, en secondes, avant suspension, durant lequel le client attend pour établir une connexion. Si ce champ est configuré à 0, le client continue indéfiniment à essayer d'ouvrir une connexion.

 Receive timeoutConfigurez le temps, en secondes, durant lequel le client attend pour obtenir une réponse, avant suspension de la connexion. Si ce champ est configuré à 0, le client attend indéfiniment.
 Use HTTP proxyCochez cette case si vous utilisez un serveur proxy. Une fois cochée, vous devez saisir les informations de connexion : hôte, port, identifiant et mot de passe.
 tStatCatcher Statistics

Cochez cette case pour collecter les données de log, aussi bien au niveau du Job qu'au niveau de chaque composant.

Dynamic settings

Cliquez sur le bouton [+] pour ajouter une ligne à la table et renseignez le champ Code avec une variable de contexte, afin d'activer ou désactiver dynamiquement l'option Use Authentication ou Use HTTP proxy lors de l'exécution. Vous pouvez ajouter deux lignes à la table afin de configurer les deux options.

Une fois qu'un paramètre dynamique est défini, l'option correspondante est mise en relief et devient inutilisable dans les vues Basic settings et Advanced settings.

Pour des exemples sur l'usage des paramètres dynamiques, consultez Scénario 3 : Lire des données dans des bases de données MySQL à l'aide de connexions dynamiques basées sur les variables de contexte et Scénario : Lire des données à partir de différentes bases de données MySQL à l'aide de paramètres de connexion chargés dynamiquement. Pour plus d'informations concernant les Dynamic settings et les variables de contexte, consultez le Guide utilisateur du Studio Talend.

Utilisation

Ce composant est utilisé comme client de service Web RESTful pour communiquer avec un fournisseur de services RESTful, avec la possibilité de saisir une requête dans un service, à l'intérieur d'un Job et de retourner le résultat du Job comme réponse du service. Selon les actions à effectuer, le composant peut être un composant de début ou intermédiaire.

Connections

Liens de sortie :

Row : Response ; Error.

Trigger : OnSubjobOk ; OnSubjobError ; Run if ; OnComponentOk ; OnComponentError.

Liens d'entrée :

Row : Main ; Reject.

Trigger : Run if ; OnSubjobOk ; OnSubjobError ; OnComponentOk ; OnComponentError.

Pour plus d'informations concernant les connexions, consultez le Guide utilisateur du Studio Talend.

Global Variables

NB_LINE : nombre de lignes traitées. Cette variable est une variable After et retourne un entier.

HEADERS : en-têtes des réponses HTTP. Cette variable est une variable Flow et retourne une liste des valeurs des en-têtes des réponses HTTP.

CORRELATION_ID : l'ID de corrélation par lequel regrouper les appels de services en chaîne. Cette variable est une variable Flow et retourne une chaîne de caractères.

ERROR_MESSAGE : message d'erreur généré par le composant lorsqu'une erreur survient. Cette variable est une variable After et retourne une chaîne de caractères. Cette variable fonctionne uniquement si la case Die on error est décochée, si le composant a cette option.

Une variable Flow fonctionne durant l'exécution d'un composant. Une variable After fonctionne après l'exécution d'un composant.

Pour renseigner un champ ou une expression à l'aide d'une variable, appuyez sur les touches Ctrl+Espace pour accéder à la liste des variables. A partir de cette liste, vous pouvez choisir la variable que vous souhaitez utiliser.

Pour plus d'informations concernant les variables, consultez le Guide utilisateur du Studio Talend.

Scénario 1 : Obtenir des informations sur un utilisateur en interagissant avec un service RESTful

Ce scénario décrit un Job composé de trois composants qui récupère des informations sur un utilisateur en se basant sur l'identifiant de l'utilisateur depuis un service REST via HTTP GET. Les informations récupérées, ainsi que l'échange de messages entre le client et le serveur, sont affichés dans la console Run.

Prérequis

Si vous êtes un utilisateur de la solution ESB de Talend, créez un Job comme décrit dans Scénario 2 : Utiliser les paramètres URI Query pour explorer les données d'une base de données, exécutez le Job afin d'exposer un service REST et saisissez l'URL du service REST dans votre navigateur Web, http://localhost:8088/users dans cet exemple. Vous devriez voir des informations telles que les suivantes :

Si vous n'êtes pas un utilisateur de la solution ESB de Talend, vous devez obtenir l'URL, la structure des données et les paramètres requis par le service REST appelé depuis votre fournisseur de service REST. Vous devez également apporter les modifications nécessaires aux configurations présentées dans le scénario.

Construire le Job

  1. Déposez les composants suivants de la Palette dans l'espace de modélisation graphique :

    • un tRESTClient, utilisé pour appeler le service REST et récupérer les informations sur l'utilisateur depuis le serveur,

    • un tXMLMap, utilisé pour adapter l'arborescence du service REST

    • et un tLogRow afin d'afficher les informations sur l'utilisateur récupérées dans la console Run.

  2. Reliez le tRESTClient au tXMLMap à l'aide d'un lien Row > Response.

  3. Reliez le premier tXMLMap au tLogRow à l'aide d'un lien Row > Main. Nommez cette connexion out dans cet exemple.

  4. Reliez le second tXMLMap au tFileOutputDelimited à l'aide d'un lien Row > Main et renommez ce lien out.

  5. Afin de mieux identifier le rôle de chaque composant, renommez-les comme suit :

Configurer les composants

Configurer l'appel du service

  1. Double-cliquez sur le tRESTClient pour ouvrir sa vue Basic settings.

  2. Dans le champ URL, saisissez l'URL du service REST invoqué, "http://localhost:8088/users" dans cet exemple. Notez que l'URL utilisée dans ce scénario est donnée uniquement à titre d'exemple.

  3. Dans la liste HTTP Method, sélectionnez GET pour envoyer une requête HTTP afin de récupérer les enregistrements existants.

    Dans la liste Accept Type, sélectionnez le type accepté par le côté client pour la réponse du côté serveur, XML. Laissez les autres paramètres tels qu'ils sont.

  4. Cliquez sur le bouton [+] situé sous la table Query parameters afin d'ajouter deux paramètres, from et to. Définissez la valeur de ces paramètres à 2 afin d'obtenir les informations de l'utilisateur ayant pour identifiant 2.

    Sinon, vous pouvez également obtenir les informations de l'utilisateur ayant pour identifiant 2 en ajoutant ?from=2&to=2 à l'URL du service.

  5. Dans la vue Advanced settings du tRESTClient, cochez les cases Log messages et Convert Response To DOM Document afin d'enregistrer le contenu de l'échange de messages avec le serveur et convertir les réponses du serveur en type Document.

Mapper la structure du service et afficher les informations de l'utilisateur récupérées

  1. Double-cliquez sur le tXMLMap pour ouvrir l'éditeur de mapping.

  2. Si vous avez sélectionné XML dans la liste Accept Type du composant tRESTClient, définissez la structure de l'arbre XML selon la structure du service.

    1. Dans la table d'entrée, dans la colonne body, cliquez-droit sur le nœud root. Dans le menu contextuel, cliquez sur Rename et renommez le nœud users.

    2. Cliquez-droit sur le nœud users. Dans le menu contextuel, cliquez sur Create Sub-Element et créez un sous-élément nommé users. Définissez l'élément user en tant qu'élément de boucle car la structure XML du service Web à invoquer effectue une boucle sur cet élément.

    3. Cliquez-droit sur le nœud user. Dans le menu contextuel, cliquez sur Create Attribute et saisissez id dans la boîte de dialogue [Create New Attribute] afin de créer un attribut nommé id pour le nœud user.

    4. Cliquez-droit à nouveau sur le nœud user. Dans le menu contextuel, cliquez sur Create Sub-Element et saisissez first_name dans la boîte de dialogue [Create New Element] afin de créer un sous-élément nommé first_name pour le nœud user.

      Répétez cette opération afin de créer un autre sous-élément last_name sous le nœud user.

    5. Déposez les colonnes id, first_name et last_name de la table d'entrée dans la table de sortie. Cliquez ensuite sur OK pour valider le mapping et fermer l'éditeur.

    Si vous avez sélectionné JSON dans la liste Accept Type du composant tRESTClient, la réponse du serveur est renvoyée au format JSON et convertie en type Document. Dans cet exemple, la structure de la réponse convertie se présente comme suit :

    <root>
        <users>
            <user>
                <id>2</id>
                <first_name>Theodore</first_name>
                <last_name>Harding</last_name>
            </user>
        </users>
    </root>

    Notez que l'élément <root> est supprimé si la case Wrap JSON Response est cochée dans la vue Advanced settings du composant tRESTClient.

    Définissez la structure XML en conséquence et mappez-la comme décrit précédemment.

  3. Double-cliquez sur le tLogRow afin d'ouvrir sa vue Basic settings.

  4. Cliquez sur le bouton Sync columns afin de vous assurer que le schéma du composant est synchronisé avec le schéma de sortie du tXMLMap.

  5. Dans le champ Mode, sélectionnez l'option Table afin d'afficher le résultat de l'opération GET sous forme de tableau.

Sauvegarder et exécuter le Job

  1. Appuyez sur les touches Ctrl+S pour sauvegarder votre Job.

  2. Appuyez sur la touche F6 ou sur le bouton Run de la vue Run pour exécuter le Job.

    La console montre que le tRESTClient lit les informations sur l'utilisateur correspondant à l'identifiant spécifié depuis le serveur.

    Si vous avez sélectionné XML dans la liste Accept Type du composant tRESTClient, les résultats d'exécution se présentent comme suit :

    Si vous avez sélectionné JSON dans la liste Accept Type du composant tRESTClient, les résultats d'exécution se présentent comme suit :

Scénario 2 : Mettre à jour les informations des utilisateurs via une interaction avec un service RESTful

Ce scénario décrit un Job à trois composants mettant à jour, dans une base de données distante, les informations d'une liste d'utilisateurs via un service REST, à l'aide de la méthode HTTP POST. Une fois exécuté, le Job affiche les informations de l'échange serveur-client dans la console de la vue Run.

Les informations à mettre à jour sur le serveur sont stockées dans un fichier CSV, qui se présente comme suit :

id;first_name;last_name
1;John;Smith
2;Martin;Reagan
3;James;White
4;Jenny;Jackson
5;Robert;Thomson

Prérequis:

Si vous êtes un utilisateur de la solution ESB de Talend, créez un Job comme décrit dans Scénario 3 : Service REST acceptant des requêtes HTTP POST et exécutez le Job en tant que serveur REST afin d'exposer un service REST acceptant les requêtes HTTP POST. Une fois le Job exécuté, la console affiche les informations relatives à l'implémentation du service, notamment l'URL de l'endpoint du service, http://localhost:8045/users dans cet exemple. Si vous saisissez http://localhost:8045/users?_wadl dans votre navigateur Web, les informations de définition du service s'affichent comme ceci :

Si vous n'utilisez pas la solution ESB de Talend, vous devez obtenir les informations relatives au service à partir de votre fournisseur de services REST, comme l'URL, le chemin d'accès à la ressource, ainsi que la structure des données. Vous devez également apporter au scénario les modifications nécessaires à vos configurations.

Construire le Job

  1. Créez un Job et ajoutez les composants suivants en saisissant leur nom dans l'espace de modélisation graphique ou en les déposant depuis la Palette:

    • un tFileInputDelimited, pour lire les informations des utilisateurs à partir d'un fichier local,

    • un tXMLMap, pour adapter la structure d'entrée à la structure du service REST,

    • et un tRESTClient, utilisé pour appeler le service REST afin d'envoyer des données à la base de données distante.

  2. Connectez le tFileInputDelimited au tXMLMap à l'aide d'un lien Row > Main.

  3. Connectez le tXMLMap au tRESTClient à l'aide d'un lien Row > Main et renommez le flux de sortie, request dans cet exemple.

  4. Renommez les composants afin mieux identifier leur rôle.

Configurer les composants

Configurer les données d'entrée et les mappings de structure

  1. Double-cliquez sur le tFileInputDelimited pour ouvrir sa vue Basic settings.

  2. Spécifiez le fichier d'entrée dans le champ File name, renseignez le champ Header en saisissant 1 afin d'ignorer l'en-tête et laissez les autres paramètres tels qu'ils sont.

  3. Cliquez sur le bouton [...] à côté du champ Edit schema afin d'ouvrir la boîte de dialogue [Schema] et de modifier le schéma d'entrée comme suit. Ajoutez les colonnes suivantes :

    • id, de type Integer, de longueur (Length) 2. Cochez la case Key pour en faire la colonne clé,

    • first_name, de type String,

    • last_name, de type String.

  4. Double-cliquez sur le composant tXMLMap pour ouvrir son éditeur.

  5. Renommez le nœud root dans la table de sortie : cliquez-droit sur le nœud, sélectionnez Rename dans le menu contextuel et spécifiez un nouveau nom dans la boîte de dialogue, user dans cet exemple.

  6. Sélectionnez les trois colonnes de la table d'entrée et déposez-les sur le nœud user, puis sélectionnez l'option Create as sub-element of target node dans la boîte de dialogue afin de configurer ces colonnes comme des sous-éléments du nœud user. Cela fait, cliquez sur OK afin de valider les mappings et fermer l'éditeur.

Configurer l'appel du service

  1. Double-cliquez sur le composant tRESTClient pour ouvrir sa vue Basic settings.

  2. Renseignez le champ URL avec l'emplacement de l'URI où est accessible le service REST, "http://localhost:8088/users" dans cet exemple.

  3. Dans le champ Relative Path, saisissez le chemin d'accès à la ressource, "/post/" + row1.id+ "/" + row1.first_name + "/" + row1.last_name dans cet exemple. Cela va envoyer les données de la ligne d'entrée au serveur via le chemin de la ressource.

  4. Dans la liste HTTP Method, sélectionnez GET afin d'envoyer une requête HTTP pour récupérer les enregistrements existants.

    Dans la liste Accept Type, sélectionnez le type que le côté client accepte pour la réponse du côté serveur, XML.

  5. Dans la vue Advanced settings du composant tRESTClient, cochez la case Log messages afin d'enregistrer les informations relatives à l'échange de messages avec le serveur.

    Laissez les autres paramètres tels qu'ils sont.

Exécuter le Job et vérifier les résultats

Appuyez sur les touches Ctrl+S afin de sauvegarder votre Job et appuyez sur F6 pour l'exécuter.

La console affiche les informations relatives à l'échange client serveur :

La console du Job utilisé en tant que serveur affiche les informations relatives à l'échange, ainsi que le résultat de la mise à jour de la base de données.