Warning
This component is available only to users of Talend Studio with ESB.
Component family |
ESB/REST |
|
Function |
tRESTRequest is a server-side NoteTo enable the HTTPS support, you have to generate a keystore |
|
Purpose |
This component allows you to receive GET/POST/PUT/DELETE requests |
|
Basic settings |
REST Endpoint |
Fill this field with the URI location where REST-ful web service NoteIf you want your service to be available on both HTTP and |
|
REST API Mapping |
Click the [+] button beneath the Output Flow: Click the […] button to specify the name of an The schema is not mandatory, so if you do not need to pass Add a schema with the name body to get the If you specify URI parameters in the output flow schema, you might
NoteWe recommend you to set the default values of your HTTP Verb: Select a HTTP method URI pattern: Fill this field with Consumes: Select the format type Produces: When the HTTP method is GET, POST, PUT, or |
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 |
Use Authorization |
Select this check box to enable authorized call. This option For more information about the management of user roles and |
|
Use Business Correlation |
Select this check box to enable the correlation option so that If this option is not enabled on the client side, a correlation ID |
|
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 response |
Select 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 |
|
Global Variables |
NB_LINE: the number of rows processed. This is an After URI: the URI of the REST request. This is a Flow variable URI_BASE: the base URI of the REST request. This is a URI_ABSOLUTE: the absolute URI of the REST request. This HTTP_METHOD: the http method. This is a Flow variable and ATTACHMENT_HEADERS: the attachment headers from the REST ATTACHMENT_FILENAMES: the attachment filenames from the PRINCIPAL_NAME: the principal name of the REST request. CORRELATION_ID: the correlation ID by which chained ERROR_MESSAGE: the error message generated by the A Flow variable functions during the execution of a component while an After variable To fill up a field or expression with a variable, press Ctrl + For further information about variables, see Talend Studio |
|
Usage |
This component covers the possibility that a Talend Job can be wrapped as a service, The tRESTRequest component |
|
Limitation |
n/a |
This scenario describes the process of accepting an HTTP request from the client,
processing it and sending the response back.
-
Drop the following components from the Palette onto the design workspace: a tRESTRequest, a tXMLMap and
two tRESTResponse. -
Double-click tRESTRequest in the design
workspace to display its Basic settings
view. -
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. -
Click the [+] button to add one line in
the REST API Mapping table. -
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. -
Click OK to save the schema.
-
Select GET from the list in the HTTP Verb column.
-
Fill the field in the URI Pattern column
with"/{id}/"
. -
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.Select GET from the list in the HTTP Verb column. Fill the field in the URI Pattern column with
"/number"
.
-
Connect tRESTRequest to tXMLMap using the Row > GetOneUser
connection. -
Double-click tXMLMap in the design
workspace to open the Map Editor. -
Click the [+] button on the top right to
add an output and name it as ResponseUsers. -
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. -
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. -
Right-click on the foo node created in the previous
step and select As loop element. -
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. -
Click OK to save the settings.
-
Connect tXMLMap to a tRESTResponse using Row > ResponseUsers
connection.The schema defined in tXMLMap is
retrieved in tRESTResponse
automatically. -
Select OK(200) from the Return status code list.
-
Leave the rest of the settings as they are.
-
Connect tRESTRequest to the other
tRESTResponse using the Row > GetUserNumber connection.
-
Save the Job and press F6 to execute
it. -
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. -
Repeat this step and type in http://localhost:8088/user/number?string=123 in the address
bar. Press Enter.An XML parsing error is reported because the returned body content is
String type. Right-click the browser an
select View Page Source in the context
menu.You can see that 123 is returned in the
response.
This scenario describes how to use URI query parameters in tRESTRequest to explore data of a database, and send the response via
the tRESTResponse.
To do so, you can create two subjobs linked together by an OnSubjobOk connection; this way the two subjobs will be executed
sequentially. For more information on Trigger connection, see the Talend Studio User
Guide. The first subjob will create and populate the database and the
second one will allow to explore the database through the REST service.
To do this, proceed as follows:
-
Drop the following components from the Palette onto the design workspace: tFixedFlowInput from the Misc family and tMysqlOutput from the Databases > Mysql
family. -
Link tFixedFlowInput to tMysqlOutput using a Row > Main
connection. -
Double-click tFixedFlowInput to display
its Basic settings view: -
Click the […] button next to Edit schema to open the schema editor.
-
In the schema editor, click the [+]
button three times to add three lines and set them as displayed in the above
screenshot. -
Click Ok.
-
Back to tFixedFlowInput
Basic settings view, in the Mode area, select the Use
inline table option. -
Under the inline table, click the [+]
button three times to add three rows in the table. -
In the inline table, click the id field
of the first row and type in 1. -
Click the firstname field of the first
row, press Ctrl+Space to display the
autocompletion list and select the TalendDataGenerator.getFirstName() variable in the
list. -
Click the lastname field of the first
row, press Ctrl+Space to display the
autocompletion list and select the TalendDataGenerator.getLastName() variable in the
list. -
Do the same for the two following rows to obtain the settings displayed in
the screenshot. -
Double-click tMysqlOutput to display its
Basic settings view: -
From the Property Type list, leave
Built-in and fill in the Host, Port,
Database, Username and Password
fields manually. If you centralized your connection information to the
database in the Metadata > DB Connections node of the Repository, you can select Repository from the list and the fields will be
automatically filled in.For more information about storing metadata, see Talend Studio User Guide.
-
In the Table field, type in the name of
the table in which the data will be loaded, for example: users. -
From the Action on table list, select
Drop table if exists and create, select
Insert from the Action on data list. -
Click Sync columns to retrieve the schema
coming from the previous component.
To do this, proceed as follows:
-
Drop and place the following components as displayed in the first
screenshot:-
tRESTRequest and
tRESTResponse from the
ESB > REST family, -
tFlowToIterate from the
Orchestration
family, -
tMysqlInput from the
Databases > Mysql family, -
tXMLMap from the
Processing
family.
-
To do this, proceed as follows:
-
Double-click tRESTRequest in the
design workspace to display its Basic
settings view: -
Fill the REST Endpoint field with
the URI location where the REST-ful web service will be accessible
for requests. For example, “http://localhost:8088/users”. -
Click the [+] button to add one
line in the REST API Mapping
table. -
Select the newly-added line and click the […] button in the Output
Flow column to add a schema for the output
flow. -
In the dialog box, name the output flow getUsers. A schema editor dialog box appears.
-
In the schema editor, click the [+] button twice to add two lines and set them as
displayed in the above screenshot. -
Click OK.
-
Back to tRESTRequest
Basic settings view, select
GET from the list in the
HTTP Verb column. -
Leave the URI Pattern column as
is.
Now that you created the tRESTRequest output
flow, you can use the corresponding link to connect to the following component:
-
Connect tRESTRequest to tFlowToIterate using Row > getUsers connection.
-
Leave the tFlowToIterate settings
as is. -
Connect tFlowToIterate to
tMysqlInput using Row > Iterate connection.
To do this, proceed as follows:
-
Double-click tMysqlInput to
display its Basic settings
view: -
From the Property Type list,
leave Built-in and fill in the
Host, Port, Database,
Username and Password fields manually. If you
centralized your connection information to the database in the
Metadata > DB Connections node of the Repository, you can select Repository from the list and the fields
will be automatically filled in.For more information about storing metadata, see Talend Studio User
Guide. -
Leave the Schema list as
Built-in and click the
[…] button next to the
Edit schema field. -
In the schema editor, define the schema exactly like the one of
the tFixedFlowInput. -
In the Table Name field, fill in
the name of the table in which the data are stored: users. -
Leave the Query Type list as
Built-in and fill in the
Query field with the following
SQL query allowing to explore the database data with the URI query
set in the tRESTRequest component:1"select * from users where id >= " + globalMap.get("getUsers.from") + " and id <= " + globalMap.get("getUsers.to")
-
Right-click tMysqlInput, hold and
drag to tXMLMap to connect the two
components together. -
Double-click tXMLMap in the design
workspace to open the Map Editor. -
Click the [+] button on the top right
to add an output and name it as ResponseUsers. -
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. -
Right-click on the root node, select
Rename in the list and rename it
users -
Right-click on the users node and
select Create Sub-Element to create a
sub-element. Name the sub-element user in the popup
dialog box. -
Right-click on the user node created in the
previous step and select As loop
element. -
Select the id column of the
row2 table to the left and drop
it onto the user node of the
ResponseUsers table to the
right. -
In the [Selection] dialog box, select
the Create as attribute of target node
option and click OK. -
Select the firstname and lastname columns of the row2 table to the left and drop it onto the
user node of the ResponseUsers table to the right. -
In the [Selection] dialog box, select
the Create as sub-element of target
node option and click OK. -
Click the wrench icon on the top of the ResponseUsers table to open the setting panel.
-
Set the All in one feature as
true, this way all XML data is
outputted in one single flow. -
Click OK to save the settings.
Now that the two subjobs are created, you can connect them together:
-
Right-click the tFixedFlowInput
component of the first subjob. -
Select Trigger > OnSubjobOk on the list.
-
Click the tRESTRequest component of
the second subjob.
This way, when executing the job, the second subjob will be executed only if the
first one’s execution succeeded.
-
Save the Job and press F6 to execute
it. -
Go to your browser if you want to test the service.
For example, use the URI query
?to=2
to retrieve the data of
the two first users.The HTTP request for a user id is accepted by the REST service and the
HTTP response is sent back to the server.For a use case that calls this REST service using Talend ESB components, see Scenario 1: Getting user information by interacting with a RESTful service.
This scenario describes a Job composed of two subjobs: the first subjob exposes a REST
service that accepts HTTP POST requests from REST clients, writes data to a database
upon receiving an HTTP request, and displays the server-client exchange information on
the Run console; the second subjob displays the results
of database updates.
-
Create a Job and add the following components to the Job by typing their names in the
design workspace or dropping them from the Palette: a tRESTRequest, a
tMysqlOutput, a tXMLMap, and a tRESTResponse. -
Connect the tRESTRequest to the tMysqlOutput component using a Row > Main connection, and
give the output flow a name, request in
this example. -
Connect the tMysqlOutput component to the tXMLMap component using a Row > Main
connection. -
Connect the tXMLMap component to the tRESTResponse component using a Row > Main
connection, and give it a name, response
in this example. Click OK in the pop-up
dialog box to accept the schema propagation from the tRESTResponse component. -
Add a tMysqlInput component and a
tLogRow component to the Job by typing
their names in the design workspace or dropping them from the Palette, and connect the tMysqlInput to the tLogRow
using a Row > Main connection. -
Connect the tMysqlOutput to the tMysqlInput using a Trigger
> OnComponentOk connection to link the two
subjobs.
Configuring REST request parameters
-
Double-click the tRESTRequest component
to open its Basic settings view. -
Fill the REST Endpoint field with the URI location where
the REST service will be accessible for requests, “http://localhost:8045/users” in this example. -
Click the output flow name, which is request in this
example, in the Output Flow column of the
REST API Mapping table to show the
[…] button, and click the button to
open the [Schema] dialog box. Then define
the schema for the request flow as
follows:-
id, type Integer, 2 characters
long, set as the key column -
first_name, type String
-
last_name, type String
When done, click OK to validate the
schema setting and close the dialog box. -
-
Click the HTTP Verb column and select
POST from the list. -
In the URI Pattern column, enter the
acceptable URI pattern of POST requests,
"/post/{id}/{first_name}/{last_name}"
in this
example.Leave the rest parameters as they are.
-
Click the Advanced settings tab, and select the
Log messages check box.
Configuring the database and the response parameters
-
Double-click the tMysqlOutput component to open its
Basic settings view. -
Leave the Property Type as Built-in and fill in the database connection
details manually in the Host, Port, Database,
Username and Password fields.If you have centralized your connection information
to the database in the Metadata > DB Connections node of the Repository, you can select Repository from the Property
Type list and browse to the centralized connection to have
the fields automatically filled in. For more information about storing
metadata, see Talend Studio User
Guide. -
Fill in the Table field with the target database table
name, users in this example. -
Select the actions to be carried out on the database table and data
according to your needs from the corresponding lists. In this example, the
target table will be created if it does not exist in the specified database,
and data from client requests will be inserted, or updated if it already
exists, to the database table. -
Click the Sync columns button to synchronize the table
schema with the input schema. -
Double-click the tXMLMap component to open the Map
Editor. -
Rename the root node in the output table: right-click
the node, select Rename from the contextual
menu, and specify a new name in the pop-up dialog box, user in this example. -
Select all the three columns in the input table and drop them onto the user node, and select the Create as sub-element of target node option from the pop-up
dialog box to set these columns as sub-elements of the user node. When done, click OK to validate the mappings and close the Map
Editor. -
Double-click the tRESTResponse component
and set the response parameters according to your needs. In this example, we
keep the default settings for all the parameters.
Configuring result display
-
Double-click the tMysqlInput component to open its
Basic settings view. -
Specify the database connection details, table name and table schema, which are the same
as in the tMysqlOutput component. -
Click the Guess Query button to fill the
Query field with the query
statement. -
Double-click the tLogRow component and select the
Table option to display the content of
the database in table cells.
-
Press Ctrl+S to save your Job.
-
Click the Run button on the Run tab or press F6 to run it.
The console displays the service implementation information, including the
service URL.When an HTTP POST request is received from a client, the console displays the relevant
exchange information and the database update result.For a use case that calls this REST service using the HTTP POST method,
see Scenario 2: Updating user information by interacting with a RESTful service.