tRESTRequest - 6.3

Talend Components Reference Guide
EnrichVersion
6.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 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
Data Governance
Data Quality and Preparation
Design and Development
EnrichPlatform
Talend Studio

Warning

This component is relevant only when used with one of the Talend solutions with ESB, as it should be used with the Service Repository node and the Data Service creation related wizard(s).

Function

tRESTRequest is a server-side component which accepts the HTTP and/or HTTPS requests from the clients and support GET, POST, PUT, PATCH and DELETE HTTP methods.

Note

To enable the HTTPS support, you have to generate a keystore and add some HTTPS security configuration properties in the org.ops4j.pax.web.cfg file of your Runtime container before deploying the service on it. For more information, see the Talend ESB Container Administration Guide.

Purpose

This component allows you to receive GET/POST/PUT/PATCH/DELETE requests from the clients on the server end.

tRESTRequest properties

Component family

ESB/REST

 

Basic settings

REST Endpoint

Fill this field with the URI location where REST-ful web service will be accessible for requests.

Note

If you want your service to be available on both HTTP and HTTPS, fill the field with a relative path.

 

REST API Mapping

Click the [+] button beneath the mapping table to add lines to specify HTTP request:

Output Flow: Click the [...] button to specify the name of an output flow and set the schema for that output flow in the dialog box afterwards.

The schema is not mandatory, so if you do not need to pass additional parameters to the tRESTRequest component, you can leave the schema empty. However, you will have to populate the schema if you have URI Path parameters set in the URI Pattern field or if you need to add optional request parameters such as URI Query, HTTP Header or Form parameters, to the URI specified in the REST Endpoint field.

Add a schema with the name body to get the request body of POST and PUT methods. It supports Document, String, and Byte[] types.

If you specify URI parameters in the output flow schema, you might need to define what type of parameter it is in the Comment field of the schema. By default, if you leave the Comment field empty, the parameter is considered as a Path parameter. Below is a list of supported Comment values:

  • empty or path corresponds to the default @PathParam,

  • query corresponds to @QueryParam,

  • form corresponds to @FormParam,

  • header corresponds to @HeaderParam.

  • matrix corresponds to @MatrixParam.

  • multipart corresponds to the CXF specific @Multipart, representing the request body. It can be used only with POST and PUT HTTP methods.

Note

We recommend you to set the default values of your optional parameters (Header, Query, Form). To do so, fill in the Default columns of the schema.

HTTP Verb: Select a HTTP method (GET/POST/PUT/PATCH/DELETE/OPTIONS/HEAD) from the list.

URI pattern: Fill this field with REST-ful URIs that describe the resource.

Consumes: Select the format type of the consume content that the component will use from XML or JSON, XML, JSON, Form, Multipart and Any in the list when the HTTP method is POST, PUT or PATCH.

Produces: When the HTTP method is GET, POST, PUT, PATCH, or DELETE, select the format type of the produce content that the component will use from XML or JSON, XML, JSON, HTML and Any, or select <oneway> in the list to accept one way requests.

Streaming: Select this check box to stream the response data by chunks so that the large volumes of data can be processed efficiently.

  Use Service Locator Select this check box to enable the Service Locator. It maintains the availability of the service to help meet demands and service level agreements (SLAs). Specify the Service namespace and the Service name in the corresponding fields.
  Use Service Activity Monitor Select this check box to enable the Service Activity Monitor. It captures events and stores this information to facilitate in-depth analysis of service activity and track-and-trace of messages throughout a business transaction. This can be used to analyze service response times, identify traffic patterns, perform root cause analysis and more.

 

Use Authentication (ESB runtime only)

Select this check box to enable the authentication option for the current service. Select from Basic HTTP and SAML Token. This option works in runtime only.

 

Use Authorization

Select this check box to enable authorized call. This option appears when SAML Token (ESB runtime only) is selected in the Use Authentication list.

For more information about the management of user roles and rights, see the Talend Administration Center User Guide and Talend ESB Infrastructure Services Configuration Guide.

 

Use Business Correlation

Select this check box to enable the correlation option so that chained service calls will be grouped under the same correlation ID. tRESTRequest will extract the correlation ID from the request header and store it in the component variable for further use in the flow.

If this option is not enabled on the client side, a correlation ID will be generated automatically in tRESTRequest.

Advanced settings Log messages Select this check box to log the message exchange between the service provider and the consumer.
  Wrap JSON Request Select this check box to wrap the JSON request with a root element.
  Convert JSON values to String in responseSelect this check box to convert the JSON values to string format in the response.
  Service Locator Customer Properties This option appears when Use Service Locator is enabled in the Basic settings tab. Click [+] to add as many properties as needed to the table. Enter the name and the value of each property in the Property Name field and the Property Value field respectively to identify the service.
  Service Activity Customer Properties This option appears when Use Service Activity Monitor is enabled in the Basic settings tab. Click [+] to add as many properties as needed to the table. Enter the name and the value of each property in the Property Name field and the Property Value field respectively to identify the service.
 

tStatCatcher Statistics

Select this check box to gather the Job processing metadata at a Job level as well as at each component level.

Global Variables

NB_LINE: the number of rows processed. This is an After variable and it returns an integer.

URI: the URI of the REST request. This is a Flow variable and it returns a string.

URI_BASE: the base URI of the REST request. This is a Flow variable and it returns a string.

URI_ABSOLUTE: the absolute URI of the REST request. This is a Flow variable and it returns a string.

HTTP_METHOD: the http method. This is a Flow variable and it returns a string.

ATTACHMENT_HEADERS: the attachment headers from the REST request. This is a Flow variable and it returns a list of attachment header values.

ATTACHMENT_FILENAMES: the attachment filenames from the REST request. This is a Flow variable and it returns all attachment filenames.

PRINCIPAL_NAME: the principal name of the REST request. This is a Flow variable and it returns a string.

CORRELATION_ID: the correlation ID by which chained service calls will be grouped. This is a Flow variable and it returns a string.

ERROR_MESSAGE: the error message generated by the component when an error occurs. This is an After variable and it returns a string. This variable functions only if the Die on error check box is cleared, if the component has this check box.

A Flow variable functions during the execution of a component while an After variable functions after the execution of the component.

To fill up a field or expression with a variable, press Ctrl + Space to access the variable list and choose the variable to use from it.

For further information about variables, see Talend Studio User Guide.

Usage

This component covers the possibility that a Talend Job can be wrapped as a service, with the ability to input a request to a service into a Job and return the Job result as a service response.

The tRESTRequest component should be used with the tRESTResponse component to provide a Job result as a response, in case of a request-response communication style.

Limitation

Using context variables for dynamic endpoint or Service Locator namespace works in the Studio only. It is not supported in Runtime.

Scenario 1: REST service accepting HTTP GET requests and sending responses

This scenario describes the process of accepting an HTTP request from the client, processing it and sending the response back.

Configuring the tRESTRequest component

  1. Drop the following components from the Palette onto the design workspace: a tRESTRequest, two tXMLMap and two tRESTResponse.

  2. Double-click tRESTRequest in the design workspace to display its Basic settings view.

  3. Fill the REST Endpoint field with the URI location where the REST-ful web service will be accessible for requests. For example, "http://192.168.0.235:8088/user".

    Note

    If you want your service to be available on both HTTP and HTTPS, fill the field with a relative path. For example, if you type in "/test", your service will be available on both http://<DefaultHTTPEnpointAddress>/test and https://<DefaultHTTPSEnpointAddress>/test, provided that you have configured your Runtime container to support HTTPS. For more information, see the Talend ESB Container Administration Guide.

  4. Click the [+] button to add one line in the REST API Mapping table.

  5. Select the newly-added line and click the [...] button in the Output Flow column to add a schema for the output flow.

    In this scenario, the output flow will be named as GetOneUser.

    Then click the [+] button to add a new line id to the schema in the dialog box.

  6. Click OK to save the schema.

  7. Select GET from the list in the HTTP Verb column.

  8. Fill the field in the URI Pattern column with "/{id}/".

  9. In the same way, add another line in the REST API Mapping table and name this schema GetUserNumber. Add a line string of String type to the schema. Enter query in the Comment field to get the number parameter in the request.

    Select GET from the list in the HTTP Verb column. Fill the field in the URI Pattern column with "/number".

Configuring the first tXMLMap component

  1. Connect tRESTRequest to a tXMLMap using the Row > GetOneUser connection.

  2. Double-click tXMLMap in the design workspace to open the Map Editor.

  3. Click the [+] button on the top right to add an output and name it as ResponseUsers.

  4. Click the [+] button on the bottom right to add two columns for the output.

    Name the first column as body and set the Type to Document.

    Name the second column as string and set the Type to String.

  5. Right-click on the node root and select Create Sub-Element to create a sub-element. Name the sub-element as foo in the popup dialog box.

  6. Right-click on the foo node created in the previous step and select As loop element.

  7. Select the id column of the GetOneUser table to the left and drop it onto the Expression field of the foo node of the ResponseUsers table to the right.

  8. Click OK to save the settings.

Configuring the second tXMLMap component

  1. Connect tRESTRequest to the other tXMLMap using the Row > GetUserNumber connection.

  2. Double-click the first tXMLMap in the design workspace to open the Map Editor.

  3. Click the [+] button on the top right to add an output and name it as ResponseUserNumber.

  4. Click the [+] button on the bottom right to add one column for the output.

    Name the first column as body and set the Type to Document.

  5. Right-click on the node root and select Create Sub-Element to create a sub-element. Name the sub-element as number in the popup dialog box.

  6. Right-click on the number node created in the previous step and select As loop element.

  7. Select the string column of the GetUserNumber table to the left and drop it onto the Expression field of the number node of the ResponseUserNumber table to the right.

  8. Click OK to save the settings.

Configuring the tRESTResponse component

  1. Connect tXMLMap to a tRESTResponse using Row > ResponseUsers connection.

    The schema defined in tXMLMap is retrieved in tRESTResponse automatically.

  2. Select OK(200) from the Return status code list.

  3. Leave the rest of the settings as they are.

  4. Connect tRESTRequest to the other tRESTResponse using the Row > GetUserNumber connection.

Saving and executing the Job

  1. Save the Job and press F6 to execute it.

  2. Go to your browser if you want to test the service.

    The HTTP request for a user id is accepted by the REST service and the HTTP response is sent back to the server.

  3. Repeat this step and type in http://localhost:8088/user/number?string=123 in the address bar. Press Enter.

    You can see that 123 is returned in the response.