tRESTClient Standard properties - Cloud - 8.0

ESB REST

Version
Cloud
8.0
Language
English
Product
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
Module
Talend Studio
Content
Data Governance > Third-party systems > ESB components > ESB REST components
Data Quality and Preparation > Third-party systems > ESB components > ESB REST components
Design and Development > Third-party systems > ESB components > ESB REST components
Last publication date
2024-02-20

These properties are used to configure tRESTClient running in the Standard Job framework.

The Standard tRESTClient component belongs to the ESB family.

The component in this framework is available in all Talend products.

Basic settings

URL

Type in the URL address of the REST server to be invoked. When the Use Service Locator check box is selected, this field will not show and the URL of the REST server will be obtained from the Service Locatorserver automatically.

Relative Path

Enter the relative path of the REST server to be invoked.

For example, if you want to access http://localhost:8888/services/Customers/list:

If Use Service Locator is disabled: You can enter any of the first part of the address in the URL field, and the second part in the Relative Path field. For example, you can enter http://localhost:8888 in URL and /services/Customers/list in Relative Path. You can also enter the full path of the REST server in URL and leave Relative Path blank.

If Use Service Locator is enabled: The URL part will be given by the Service Locator. In this case, you need to know the URL part, and specify the rest part in Relative Path. This depends on the service you request. For example, on tRESTRequest, you specify REST Endpoint as http://localhost:8888/services and enable Use Service Locator. Then, if you want to use this service, on tRESTClient side, you should specify /customers/list in Relative Path.
Warning: When using relative path, you should specify at least one sub-directory in the URL field instead of only host:port to avoid compiling issues. For example, use http://localhost:8888/services instead of http://localhost:8888.

HTTP Method

From this list, select an HTTP method that describes the desired action. The specific meanings of the HTTP methods are subject to definitions of your Web service provider. Listed below are the generally accepted HTTP method definitions:

- GET: retrieves data from the server end based on the given parameters.

- POST: uploads data to the server end based on the given parameters.

- PUT: updates data based on the given parameters, or if the data does not exist, creates it.

- PATCH: modifies data partially based on the given parameters.

- DELETE: removes data based on the given parameters.

Content Type

Select XML, JSON, or FORM according to the media type of the content to be uploaded to the server end.

This list appears only when you select the POST, PUT, or PATCH HTTP method.

Accept Type

Select the media type the client end is prepared to accept for the response from the server end.

Available options are XML, JSON, and ANY. When ANY is selected, the response message can be of any type and will be transformed into a string.

Query parameters

Specify the URI query parameters in the form of name-value pairs.

This option is mostly used with the GET method.

Schema and Edit Schema

A schema is a row description, it defines the number of fields that will be processed and passed on to the next component.

This component uses three built-in, read-only schemas.

Click Edit Schema to view the schema structure.

Warning:

Changing the schema type may result in loss of the schema structure and therefore failure of the component.

Input Schema

Schema for the input data. This schema contains two columns:

- body: stores the content of structured input data

- string: stores the input content when it is, or is handled as, a string.

Response Schema

Schema for server response. This schema is passed onto the next component via a Row > Response link, and it contains three columns:

- statusCode: stores the HTTP status code from the server end.

- body: stores the content of a structured response from the server end.

- string: stores the response content from the server end when it is, or is handled as, a string.

Error Schema

Schema for error information. This schema is passed onto the next component via a Row > Error link, and it contains two columns:

- errorCode: stores the HTTP status code from the server end when an error occurs during the invocation process. The specific meanings of the errors codes are subject to definitions of your Web service provider. For reference information, visit en.wikipedia.org/wiki/List_of_HTTP_status_codes.

- errorMessage: stores the error message corresponding the error code.

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

Select this check box if authentication is required on the REST server end. Select the authentication type from:

  • Basic HTTP: Fill the Username and Password fields with your credentials.
  • HTTP Digest: Fill the Username and Password fields with your credentials.
  • SAML Token (ESB runtime only): Fill the Username and Password fields with your credentials.
  • OAuth2 Bearer: Fill the Bearer Token field with a base64-encoded credential string.
  • Open ID Connect: Fill the Username and Password fields with your credentials. For more information, see Talend Identity and Access Management and Managing ESB Resources and authorizations.

To enter the password, click the [...] button next to the password field, enter the password in double quotes in the pop-up dialog box, and click OK to save the settings.

Use Authorization

Select this check box to enable authorized call. Specify the client's role in the Role field. 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 Managing ESB Resources and authorizations and Talend Identity and Access Management.

Use Business Correlation

Select this check box to create a correlation ID in this component.

You can specify a correlation ID in the Correlation Value field. In this case the correlation ID will be passed on to the service it calls so that chained service calls will be grouped under this correlation ID. If you leave this field empty, this value will be generated automatically at runtime.

When this option is enabled, tRESTClient will also extract the correlation ID from the response header and store it in the component variable for further use in the flow.

Check Server Identity

Select this check box to verify the match between the hostname of the URL and the Common Name (CN) on the server certificate. If they mismatch, an error java.io.IOException: HTTPS hostname wrong will be returned.

Re-use SSL connection

This option is disabled by default. When enabled, if the same server is called multiple times in a Job, SSL configuration will be created once and reused for every other calls.

Note that this option does not support having query parameters set in the URL or Relative Path fields. To have this option working correctly, all query parameters must be added to the Query parameters table.

Die on error This check box is selected to kill the Job when an error occurs. Clear the check box to skip the row on error and complete the process for error-free rows.

Advanced settings

Log messages

Select this check box to log the message exchange between the service provider and the consumer.

Follow redirects Select this check box to follow auto-redirects.
Allow non-same host redirects This option appears when Follow redirects is enabled. Select this check box to allow redirects on different host.
Maintain session
This option appears when Follow redirects is enabled. Select this check box to enable sharing session cookies in case of multiple redirects. Session cookies will be collected and available for further processing in the same way as other cookies after message exchange is finished.
Note: This option is available only if you have installed the R2022-12 Talend Studio Monthly update or a later one delivered by Talend. For more information, check with your administrator.

Enable WebClient Operation Reporting

If this check box is selected, a CXF endpoint property will be set on the client side which may be used by some outgoing CXF metrics interceptors, to track requests to services using their URL's.

The property set is org.apache.cxf.resource.operation.name and it contains service URL together with the HTTP method name, for example GET:http: //example.com:8080/service/.

If this check box is not selected, the property will not be set and some metrics will not be counted, which may increase the performance.

Convert Response To DOM Document

Select this check box to convert the response from the server to document type.

Clear this check box if you want the response to be handled as a string.

Convert Types To Strings

This option appears when Content Type is JSON, or Accept Type is JSON or any. Select this check box to convert all values in JSON to string between quotation marks. For example, with this option enabled, the JSON data:

 "root": {
      "test": 111
    }

will be changed to:

"root": {
      "test": "111"
    }
Drop JSON Request Root

This option appears when HTTP Method is POST, PUT or PATCH and Content Type is JSON. Select this check box to drop root JSON elements.

Wrap JSON Response

This option appears and is enabled by default when JSON is selected from the Accept Type list in the Basic settings view.

With this check box selected, the response is wrapped with a root element. Clear this check box to remove the root element from the response.

HTTP Headers

Type in the name-value pair(s) for HTTP headers to define the parameters of the requested HTTP operation.

For the specific definitions of HTTP headers, consult your REST Web service provider. For reference information, visit en.wikipedia.org/wiki/List_of_HTTP_headers.

Disable chunked encoding

This option appears when HTTP Method is POST, PUT or PATCH. Select this check box to disable encoding the payload as chunks.

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.

Connection timeout

Set the amount of time, in seconds, that the client will attempt to establish a connection before it times out. If set to 0, the client will continue to attempt to open a connection indefinitely. (default: 30)

This option does not work in Talend Runtime. For ESB Deployments to Talend Runtime, this parameter will have no effect. In the configuration file <TalendRuntimePath>/container/etc/org.apache.cxf.http.conduits-common.cfg, you need a URL which covers you service, for example, url = http://.* to handle both HTTP and HTTPS requests, and specify the client.ConnectionTimeout parameter in milliseconds in this HTTP Conduit file. If you need to use the Receive timeout option, specify the client.ReceiveTimeout in milliseconds too.

Receive timeout

Set the amount of time, in seconds, that the client will wait for a response before it times out. If set to 0, the client will wait indefinitely. (default: 60)

This option works similarly to the Connection timeout option. For how to use it after the component is deployed in Talend Runtime, see the Connection timeout option.

Use HTTP proxy Select this check box if you are using a proxy server. Once selected, you need to provide the connection details: host, port, username and password.
tStatCatcher Statistics Select this check box to gather the Job processing metadata at the Job level as well as at each component level.

Global Variables

Global Variables

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

HEADERS: the HTTP response headers. This is a Flow variable and it returns a list of HTTP response header values.

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 more information about variables, see Using contexts and variables.

Usage

Usage rule

This component is used as a RESTful Web service client to communicate with a RESTful service provider, with the ability to input a request to a service into a Job and return the Job result as a service response. Depending on the actions to perform, it usually works as a start or middle component in a Job or subJob.

Dynamic settings

Click the [+] button to add a row in the table and fill the Code field with a context variable to turn on or off the Log messages, Use Authentication or Use HTTP proxy option dynamically at runtime. You can add three rows in the table to set all options.

Once a dynamic parameter is defined, the corresponding option becomes highlighted and unusable in the Basic settings view or Advanced settings view.

For examples on using dynamic parameters, see Reading data from databases through context-based dynamic connections and Reading data from different MySQL databases using dynamically loaded connection parameters. For more information on Dynamic settings and context variables, see Dynamic schema and Creating a context group and define context variables in it.

Connections

Outgoing links:

Row: Response; Error.

Trigger: On Subjob Ok; On Subjob Error; Run if; On Component Ok; On Component Error.

Incoming links:

Row: Main; Reject.

Trigger: Run if; On Subjob Ok; On Subjob Error; On component Ok; On Component Error.

For further information regarding connections, see Using connections in a Job.

Limitation

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