ComposantsComponents › ESB › Web Services
Fait d'un job le fournisseur d'une opération d'un service web SOAP. Le composant publie le service décrit par un WSDL du référentiel, attend les requêtes et passe le corps de chacune, un document XML, à la suite du job dans la colonne payload. La réponse part par un tESBProviderResponse, une erreur métier par un tESBProviderFault. Tant que Continuer à écouter est cochée, le job ne se termine pas : il traite les requêtes une par une.
Turns a job into the provider of one operation of a SOAP web service. The component publishes the service described by a WSDL of the repository, waits for requests and passes the body of each one, an XML document, to the rest of the job in the payload column. The response leaves through a tESBProviderResponse, a business fault through a tESBProviderFault. As long as Keep Listening is checked, the job does not end: it handles the requests one by one.
EntréeInput
Aucun flux Il commence son sous-job. Il accepte un déclencheur entrant (On Subjob Ok, Run if…), par exemple pour ouvrir une connexion avant d'écouter. No flow It starts its subjob. It accepts an incoming trigger (On Subjob Ok, Run if…), for instance to open a connection before listening.
SortieOutput
Un lien Main : une ligne par requête, colonne payload (Document). Ou un lien Iterate.
One Main link: one row per request, payload column (Document). Or one Iterate link.
Déclencheurs en sortieOutput triggers
On Subjob Ok On Subjob Error On Component Ok Run if
Le tXMLMap lit la requête dans payload, interroge au besoin une base en Lookup, et construit le document de la réponse. Une seconde sortie du tXMLMap peut mener à un tESBProviderFault pour les cas d'erreur prévus par le WSDL.
The tXMLMap reads the request from payload, queries a database as a Lookup if needed, and builds the document of the response. A second output of the tXMLMap can lead to a tESBProviderFault for the error cases the WSDL provides for.
Sans tESBProviderResponse ni tESBProviderFault dans le job, l'appelant reçoit tout de suite un accusé de réception (HTTP 202) et le job traite le message ensuite. With no tESBProviderResponse and no tESBProviderFault in the job, the caller at once receives an acknowledgement (HTTP 202) and the job processes the message afterwards.
http://localhost:8090/services/<Service>.
Create a service in the repository (Services): its WSDL describes the operations, their messages and the address of the service. The WSDL offered at creation publishes one operation at http://localhost:8090/services/<Service>.
web service [endpoint: …] published quand le service répond. Arrêtez le job pour arrêter le service.
Run the job: the console prints web service [endpoint: …] published once the service answers. Stop the job to stop the service.
Les libellés sont ceux de l'onglet Composant ; le nom technique, en gris, est celui du paramètre dans le fichier du job. Labels are those of the Component tab; the technical name, in grey, is the parameter name in the job file.
| ParamètreSetting | DéfautDefault | VisibleShown | Description |
|---|---|---|---|
| Type de propriétéProperty TypePROPERTY | Built-In | ToujoursAlways | Référentiel : l'opération d'un service que ce job sert. C'est ce choix, ou Assigner un job depuis le service, qui remplit les réglages du service (voir Ce que le service apporte) : ils n'ont pas de champ dans le formulaire. Repository: the operation of a service this job serves. This choice, or Assign Job from the service, is what fills the service settings (see What the service brings): they have no field in the form. |
| SchémaSchemaSCHEMA | payload (Document) |
ToujoursAlways |
En lecture seule : une colonne payload, de type Document. Elle contient le contenu de soap:Body, sans l'enveloppe ; sa racine est l'élément de la requête.
Read-only: one payload column, of type Document. It holds the content of soap:Body, without the envelope; its root is the element of the request.
|
| Continuer à écouterKeep ListeningKEEPLISTENING | OuiYes | ToujoursAlways | Cochée, le job attend la requête suivante après chaque réponse, jusqu'à son arrêt. Décochée, il traite une seule requête, arrête le service et se termine : la suite du job (On Subjob Ok) s'exécute alors. Checked, the job waits for the next request after each response, until it is stopped. Unchecked, it handles a single request, stops the service and ends: the rest of the job (On Subjob Ok) then runs. |
Ces quatre réglages ne servent qu'à l'exécution du job dans le Studio ou en job autonome : dans le Talend Runtime, c'est le conteneur qui reçoit les requêtes (voir Studio et Runtime). These four settings only apply when the job runs in the Studio or as a standalone job: in the Talend Runtime, the container is what receives the requests (see Studio and Runtime).
| ParamètreSetting | DéfautDefault | VisibleShown | Description |
|---|---|---|---|
| Messages de log (Studio uniquement)Log messages (Studio only)LOG_MESSAGES | NonNo | ToujoursAlways |
Ajoute au service la journalisation des messages de CXF (requêtes et réponses SOAP), qui masque l'en-tête Authorization et les éléments password. Les messages passent par le journal du job (log4j) : ils n'apparaissent que si son niveau les laisse passer. Lancé depuis Talaxie sans configuration de journal, le job n'en a rien affiché dans la console lors de nos essais.
Adds the CXF message logging (SOAP requests and responses) to the service, which masks the Authorization header and the password elements. The messages go through the log of the job (log4j): they only show if its level lets them through. Started from Talaxie with no log configuration, the job displayed none of it in the console in our runs.
|
| Délai avant expiration de la réponse (sec)Response timeout, secEXCHANGE_TIMEOUT | 50 |
ToujoursAlways | Temps pendant lequel le job, au moment d'envoyer sa réponse, attend que le service la prenne. Passé ce délai, le composant de réponse échoue. Time during which the job, when it sends its response, waits for the service to take it. After that delay, the response component fails. |
| Taille de la file de traitement des requêtesRequest processing queue sizeMAX_PARALLEL_REQUESTS | 1000 |
ToujoursAlways |
Nombre de requêtes qui peuvent attendre leur tour pendant que le job en traite une. Au-delà, l'appelant reçoit une erreur SOAP Can't queue request, queue size of … is exceeded.
Number of requests that can wait for their turn while the job handles one. Beyond it, the caller receives a SOAP fault Can't queue request, queue size of … is exceeded.
|
| Délai avant expiration du traitement des requêtes (sec)Request processing timeout, secREQUEST_PROCESSING_TIMEOUT | 120 |
ToujoursAlways | Temps laissé au job pour répondre, attente dans la file comprise. Une réponse plus tardive est remplacée par une erreur SOAP (voir Pièges). Time given to the job to answer, waiting in the queue included. A later response is replaced with a SOAP fault (see Pitfalls). |
Neuf paramètres du composant ne sont jamais affichés. Ils sont écrits dans le job quand il est rattaché à une opération, d'après le WSDL du service, et mis à jour quand le WSDL change. Exemple : le service Clients, opération getClient.
Nine parameters of the component are never displayed. They are written to the job when it is assigned to an operation, from the WSDL of the service, and updated when the WSDL changes. Example: the Clients service, getClient operation.
| ParamètreParameter | Sans serviceWithout a service | Avec le service de l'exempleWith the service of the example |
|---|---|---|
| WSDL_LOCATION | videempty | Chemin du WSDL dans le projet : …/services/Clients_0.1.wsdlPath of the WSDL in the project: …/services/Clients_0.1.wsdl |
| ENDPOINT_URI | /esb/provider |
Adresse du port dans le WSDL (soap:address) : http://localhost:8090/services/ClientsAddress of the port in the WSDL (soap:address): http://localhost:8090/services/Clients |
| SERVICE_NS SERVICE_NAME |
http://talend.org/esb/service/job--DEFAULT-- (à la génération : <projet>_<job>)(at generation: <project>_<job>) |
http://www.talend.org/service/Clients |
| PORT_NS PORT_NAME |
http://talend.org/esb/service/job--DEFAULT-- (à la génération : le service suivi de _Port)(at generation: the service followed by _Port) |
http://www.talend.org/service/ClientsPort |
| OPERATION_NS OPERATION_NAME |
vide (celui du service)empty (the one of the service)invoke |
videemptygetClient |
| COMMUNICATION_STYLE | vide : one-way si le job n'a ni tESBProviderResponse ni tESBProviderFault, request-response sinonempty: one-way if the job has neither a tESBProviderResponse nor a tESBProviderFault, request-response otherwise |
request-response (l'opération a une sortie ou une erreur dans le WSDL)(the operation has an output or a fault in the WSDL) |
tESBProviderRequest_1_NB_LINE (Integer) · nombre de requêtes déjà traitées ; absente pendant la première.number of requests already handled; missing during the first one.tESBProviderRequest_1_HEADERS_HTTP (Map<String, List<String>>) · en-têtes HTTP de la requête en cours.HTTP headers of the current request.tESBProviderRequest_1_HEADERS_SOAP (Collection<org.apache.cxf.headers.Header>) · en-têtes SOAP de la requête ; liste vide s'il n'y en a pas.SOAP headers of the request; empty list if there are none.tESBProviderRequest_1_SECURITY_TOKEN (org.w3c.dom.Element) · l'assertion SAML 2 de l'en-tête wsse:Security, si la requête en porte une.the SAML 2 assertion of the wsse:Security header, if the request carries one.tESBProviderRequest_1_CORRELATION_ID (String) · identifiant de corrélation de la requête, quand la corrélation est activée sur le service.correlation identifier of the request, when correlation is enabled on the service.http://localhost:8090/services/Clients.The job itself starts an HTTP server (CXF and Jetty) at the full address of the WSDL: http://localhost:8090/services/Clients.?wsdl.The WSDL is served at the same address followed by ?wsdl./services : du WSDL il ne garde que le chemin de l'adresse (/services/Clients donne http://<hôte du Runtime>:8040/services/Clients avec le port par défaut), et remet chaque requête au job de son opération.The job starts no server. The container publishes the service once, under its /services root: from the WSDL it only keeps the path of the address (/services/Clients gives http://<Runtime host>:8040/services/Clients with the default port), and hands each request to the job of its operation.
Service Clients du référentiel, deux opérations : getClient (requête, réponse, erreur clientNotFound) et notifyClient (sans réponse). Les jobs ont été exécutés dans Talaxie et appelés en local par un client HTTP ; les messages et les consoles sont copiés tels quels. Le nom des jobs est remplacé par MyService et les piles d'appels sont abrégées (…). Pour ces essais, un tJavaRow et un tFilterRow tiennent la place du tXMLMap. Dans Talaxie, ces jobs chargent aussi deux bibliothèques par des tLibraryLoad (cxf-rt-features-logging et wss4j-ws-security-common) : sans elles, un job dont le tESBProviderRequest est le seul composant ESB n'y compile pas.
Clients service of the repository, two operations: getClient (request, response, clientNotFound fault) and notifyClient (no response). The jobs were run in Talaxie and called locally by an HTTP client; messages and consoles are copied as they are. The job names are replaced with MyService and the stack traces are shortened (…). For these tests, a tJavaRow and a tFilterRow stand in for the tXMLMap. In Talaxie, these jobs also load two libraries through tLibraryLoad components (cxf-rt-features-logging and wss4j-ws-security-common): without them, a job whose only ESB component is the tESBProviderRequest does not compile there.
Le tJavaRow lit l'identifiant demandé et construit la réponse ; le rejet du tFilterRow mène à un tESBProviderFault quand le client n'existe pas. Lecture de la requête dans le tJavaRow : The tJavaRow reads the requested identifier and builds the response; the reject of the tFilterRow leads to a tESBProviderFault when the client does not exist. Reading the request in the tJavaRow:
String id = input_row.payload.getDocument().getRootElement().elementText("id");
L'appel et sa réponse : The call and its response:
POST http://localhost:8090/services/Clients SOAPAction: "http://www.talend.org/service/getClient" <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><tns:getClientRequest xmlns:tns="http://www.talend.org/service/"><id>1</id></tns:getClientRequest></soap:Body></soap:Envelope> HTTP 200 OK <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><tns:getClientResponse xmlns:tns="http://www.talend.org/service/"><id>1</id><name>Alice Martin</name><city>Lyon</city></tns:getClientResponse></soap:Body></soap:Envelope>
La console du job après cinq appels : le client 1, le client 99 (erreur métier), l'identifiant boom pour lequel le tJavaRow lève une exception, le client 1 de nouveau, puis un message de l'autre opération, notifyClient.
The console of the job after five calls: client 1, client 99 (business fault), the boom identifier for which the tJavaRow throws an exception, client 1 again, then a message of the other operation, notifyClient.
web service [endpoint: http://localhost:8090/services/Clients] published <?xml version="1.0" encoding="UTF-8"?> <tns:getClientRequest xmlns:tns="http://www.talend.org/service/"><id>1</id></tns:getClientRequest> <?xml version="1.0" encoding="UTF-8"?> <tns:getClientRequest xmlns:tns="http://www.talend.org/service/"><id>99</id></tns:getClientRequest> <?xml version="1.0" encoding="UTF-8"?> <tns:getClientRequest xmlns:tns="http://www.talend.org/service/"><id>boom</id></tns:getClientRequest> Exception in component tJavaRow_1 (MyService) java.lang.RuntimeException: Clients database is unreachable at demo.myservice_0_1.MyService.tESBProviderRequest_1_LoopProcess(MyService.java:2963) … <?xml version="1.0" encoding="UTF-8"?> <tns:getClientRequest xmlns:tns="http://www.talend.org/service/"><id>1</id></tns:getClientRequest> <?xml version="1.0" encoding="UTF-8"?> <tns:notifyClientRequest xmlns:tns="http://www.talend.org/service/"><id>1</id><event>address changed</event></tns:notifyClientRequest>
Le tLogRow affiche chaque payload : le corps de la requête, sans l'enveloppe SOAP. L'exception n'arrête pas le job, qui sert la requête suivante. Le dernier message montre que le job reçoit tout ce qui arrive à l'adresse, quelle que soit l'opération : à lui de ne répondre qu'à la sienne.
The tLogRow prints each payload: the body of the request, without the SOAP envelope. The exception does not stop the job, which serves the next request. The last message shows that the job receives whatever arrives at the address, whatever the operation: it is up to the job to answer only its own.
Le troisième appel de l'exemple précédent. Le tJavaRow exécute throw new RuntimeException("Clients database is unreachable"); :
The third call of the previous example. The tJavaRow runs throw new RuntimeException("Clients database is unreachable");:
POST http://localhost:8090/services/Clients SOAPAction: "http://www.talend.org/service/getClient" <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><tns:getClientRequest xmlns:tns="http://www.talend.org/service/"><id>boom</id></tns:getClientRequest></soap:Body></soap:Envelope> HTTP 500 Server Error <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><soap:Fault><faultcode>soap:Server</faultcode><faultstring>Clients database is unreachable</faultstring></soap:Fault></soap:Body></soap:Envelope>
L'appelant reçoit une erreur SOAP de code soap:Server, avec le message de l'exception pour texte et sans détail. Pour une erreur prévue, avec un code et un détail choisis, utilisez un tESBProviderFault.
The caller receives a SOAP fault with code soap:Server, the message of the exception as its text and no detail. For an expected error, with a chosen code and detail, use a tESBProviderFault.
Le même job, case décochée, appelé une fois : The same job, box unchecked, called once:
web service [endpoint: http://localhost:8090/services/Clients] published <?xml version="1.0" encoding="UTF-8"?> <tns:getClientRequest xmlns:tns="http://www.talend.org/service/"><id>1</id></tns:getClientRequest> web service [endpoint: http://localhost:8090/services/Clients] unpublished
L'appelant reçoit sa réponse, puis le service s'arrête et le job se termine avec le code 0. Un second appel, trois secondes plus tard, est refusé : plus rien n'écoute sur le port. The caller receives its response, then the service stops and the job ends with code 0. A second call, three seconds later, is refused: nothing listens on the port any more.
Job rattaché à notifyClient, sans tESBProviderResponse. Deux appels ; chacun reçoit :
Job assigned to notifyClient, with no tESBProviderResponse. Two calls; each one receives:
POST http://localhost:8090/services/Clients SOAPAction: "http://www.talend.org/service/notifyClient" <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><tns:notifyClientRequest xmlns:tns="http://www.talend.org/service/"><id>1</id><event>address changed</event></tns:notifyClientRequest></soap:Body></soap:Envelope> HTTP 202 Accepted
Pas de corps dans la réponse. Console du job : No body in the response. Console of the job:
web service [endpoint: http://localhost:8090/services/Clients] published <?xml version="1.0" encoding="UTF-8"?> <tns:notifyClientRequest xmlns:tns="http://www.talend.org/service/"><id>1</id><event>address changed</event></tns:notifyClientRequest> <?xml version="1.0" encoding="UTF-8"?> <tns:notifyClientRequest xmlns:tns="http://www.talend.org/service/"><id>2</id><event>address changed</event></tns:notifyClientRequest>
Un tJavaRow après le tESBProviderRequest affiche les variables. La requête vient d'un tESBConsumer réglé sur l'authentification Basic HTTP (utilisateur demo) avec un en-tête HTTP X-Request-Source. Lecture d'un en-tête :
A tJavaRow after the tESBProviderRequest prints the variables. The request comes from a tESBConsumer set to Basic HTTP authentication (user demo) with an HTTP header X-Request-Source. Reading one header:
java.util.Map<String, java.util.List<String>> http =
(java.util.Map<String, java.util.List<String>>) globalMap.get("tESBProviderRequest_1_HEADERS_HTTP");
String source = http.get("X-Request-Source").get(0);
web service [endpoint: http://localhost:8090/services/Clients] published NB_LINE = null CORRELATION_ID = null SECURITY_TOKEN = null HEADERS_SOAP = [] HEADERS_HTTP is a java.util.TreeMap Accept = [*/*] Authorization = [Basic ZGVtbzpkZW1vLXBhc3M=] Content-Length = [207] HTTP2-Settings = [AAEAAEAAAAIAAAAAAAMAAAAAAAQBAAAAAAUAAEAAAAYABgAA] Host = [localhost:8090] SOAPAction = ["http://www.talend.org/service/getClient"] Upgrade = [h2c] User-Agent = [Apache-CXF/4.1.0] X-Request-Source = [billing] connection = [Upgrade, HTTP2-Settings] content-type = [text/xml; charset=UTF-8]
L'en-tête Authorization arrive tel quel : à l'exécution du job, rien ne vérifie l'utilisateur ni le mot de passe. NB_LINE vaut null pendant la première requête, 1 pendant la deuxième.
The Authorization header arrives as it is: when the job runs, nothing checks the user or the password. NB_LINE is null during the first request, 1 during the second.
Le job a un tESBProviderResponse, mais la ligne ne l'atteint pas : ici le client 99 est rejeté par le tFilterRow et le rejet n'est relié à rien. Le composant envoie alors un document vide à sa place, et l'appelant reçoit : The job has a tESBProviderResponse, but the row does not reach it: here client 99 is rejected by the tFilterRow and the reject is connected to nothing. The component then sends an empty document in its place, and the caller receives:
POST http://localhost:8090/services/Clients
SOAPAction: "http://www.talend.org/service/getClient"
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><tns:getClientRequest xmlns:tns="http://www.talend.org/service/"><id>99</id></tns:getClientRequest></soap:Body></soap:Envelope>
HTTP 500 Server Error
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><soap:Fault><faultcode>soap:Server</faultcode><faultstring>Could not generate the XML stream caused by: com.ctc.wstx.exc.WstxEOFException: Unexpected EOF in prolog
at [row,col {unknown-source}]: [2,0].</faultstring></soap:Fault></soap:Body></soap:Envelope>
Rien n'est écrit dans la console du job. Faites aboutir chaque chemin du flux à un tESBProviderResponse ou à un tESBProviderFault. Nothing is written to the console of the job. Make every path of the flow end at a tESBProviderResponse or a tESBProviderFault.
Un autre programme écoute sur le port 8090, par exemple le job d'une autre opération du même service : Another program listens on port 8090, for instance the job of another operation of the same service:
Exception in thread "Thread-1" java.lang.IllegalArgumentException: Cannot start provider with uri: http://localhost:8090/services/Clients. Port 8090 already in use. at demo.myservice_0_1.MyService$HandlerThread_tESBProviderRequest_1.run(MyService.java:815)
Le service n'est pas publié, mais le job ne s'arrête pas : il attend des requêtes qui ne viendront pas. Arrêtez-le à la main. La ligne published est le seul signe d'un service prêt.
The service is not published, but the job does not stop: it waits for requests that will not come. Stop it by hand. The published line is the only sign of a ready service.
Délai avant expiration du traitement des requêtes à 1, et un job qui met trois secondes à répondre. L'appelant reçoit :
Request processing timeout set to 1, and a job that takes three seconds to answer. The caller receives:
HTTP 500 Server Error <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><soap:Fault><faultcode>soap:Server</faultcode><faultstring>no response provided by Talend job</faultstring></soap:Fault></soap:Body></soap:Envelope>
L'erreur n'arrive pas au bout d'une seconde mais quand le job a fini, trois secondes plus tard ; sa réponse, elle, est perdue. Le job n'écrit rien. Ce délai protège donc mal l'appelant : réglez aussi le délai de réception du client. The fault does not arrive after one second but when the job is done, three seconds later; its response is lost. The job writes nothing. This timeout thus protects the caller poorly: also set the receive timeout of the client.
Un tESBProviderRequest posé dans un job sans être rattaché à une opération garde l'adresse par défaut, relative. Le job affiche : A tESBProviderRequest dropped in a job without being assigned to an operation keeps the default, relative address. The job prints:
web service [endpoint: /esb/provider] published
mais aucun port n'est ouvert : un appel à http://localhost:8090/… est refusé. Rattachez le job à une opération.
but no port is open: a call to http://localhost:8090/… is refused. Assign the job to an operation.
Avec deux tESBProviderRequest, le job échoue au démarrage : cannot instantiate Web Service: job contains more than one tESBProviderRequest component. Avec un tRESTRequest dans le même job : cannot instantiate service: job contains both tESBProviderRequest and tRESTRequest components.
With two tESBProviderRequest components, the job fails at start: cannot instantiate Web Service: job contains more than one tESBProviderRequest component. With a tRESTRequest in the same job: cannot instantiate service: job contains both tESBProviderRequest and tRESTRequest components.
À l'exécution du job, les requêtes passent une par une : dix appels simultanés à un job qui met deux secondes sont servis en vingt secondes. Gardez le traitement court, ou déployez le service dans le Runtime. When the job runs, requests go through one by one: ten simultaneous calls to a job that takes two seconds are served in twenty seconds. Keep the processing short, or deploy the service in the Runtime.
Le composant n'a pas ce déclencheur. Une erreur du traitement est déjà rattrapée par la boucle, qui répond une erreur SOAP ; un tLogCatcher posé dans le job la reçoit. The component does not have this trigger. An error of the processing is already caught by the loop, which answers a SOAP fault; a tLogCatcher placed in the job receives it.
L'adresse et le port viennent de soap:address dans le WSDL du service. Modifiez le WSDL : le job rattaché est mis à jour. Dans le Runtime, seul le chemin compte.
The address and the port come from soap:address in the WSDL of the service. Edit the WSDL: the assigned job is updated. In the Runtime, only the path matters.
Lancez le job, attendez la ligne published, puis appelez le service depuis un second job avec un tESBConsumer, ou depuis un client SOAP en lui donnant l'adresse suivie de ?wsdl. Un tLogRow juste après le tESBProviderRequest montre chaque requête reçue.
Start the job, wait for the published line, then call the service from a second job with a tESBConsumer, or from a SOAP client given the address followed by ?wsdl. A tLogRow right after the tESBProviderRequest shows each received request.
tESBProviderResponse · envoyer la réponse de l'opérationsend the response of the operationtESBProviderFault · répondre une erreur métieranswer a business faulttESBConsumer · appeler un service SOAP depuis un jobcall a SOAP service from a jobtRESTRequest · le même principe pour un service RESTthe same principle for a REST servicetRouteInput · un job appelé par une routea job called by a routetLogCatcher · recevoir les exceptions du traitementreceive the exceptions of the processing