Unlock a world of possibilities! Login now and discover the exclusive benefits awaiting you.
The Talend Cloud Management Console Public API enables users to manage Talend Management Console (TMC) from an external system (for example, a scheduler, script, or program).
Environment
This article uses Talend Cloud API 1.2, which supports operations for tasks, plans, and promotions in Talend Cloud. Note: Talend Cloud API 1.1 only supports operations on tasks, and version 1.0 has been deprecated.
Content:
- Prerequisites
- Executables and executions
- Generating a token
- API operations for tasks in Talend Cloud
- Get available Tasks - /executables
- Get Task details - /executables/{id}
- Execute Task - /executions
- Terminate Task execution - /executions/{id}
- Get Task execution status - /executions/{id}
- API operations for plans in Talend Cloud
- Get available Plans - /executables/plans
- Get Plan details - /executables/plans/{id}
- Execute Plan - /executions/plans
- Get Plan execution status - /executions/plans/{id}
- API operations for promotions in Talend Cloud
- Get available Promotions - /executables/promotions
- Get Promotion details - /executables/promotions/{id}
- Execute Promotion - /executions/promotions
- Get Promotion execution status - /executions/promotions/{id}
- Conclusion
Prerequisites
- Talend Cloud subscription
- Talend Cloud Management Console access credentials (can also be used to access API)
Executables and executions
A list of supported operations is available on the API documentation page. There are three URLs, each for a different region of Talend Cloud. However, the list of operations does not vary by region.
The API operations consist of executables and executions, with a separate set of operations available for each.
- Operations related to executables use the GET method to get information about executables, such as tasks, plans, and promotions.
- Operations related to executions perform actions such as execute or terminate using the POST, DELETE, or GET method.
- Supported operations on executables get lists of tasks, plans, or promotions, as well as details for these by ID, for instance, using "Get task details by task ID".
- The POST method is used for an operation that supports execution of a task, plan, or promotion.
- The DELETE method is used for deleting a task.
Generating a token
The first step in using the API is generating a personal access token; then you can start managing TMC through the API. Follow the detailed steps for Generating a personal access token in the Talend Help Center. You get a token that looks like this:
As mentioned in the help, you can use this token for authorization, for example in a curl command:
curl -X GET 'https://api.us.cloud.talend.com/tmc/v1.2/executables' \ -H 'Authorization: Bearer eyJraWQiOiJpYW0tb2lpYy1jbG91ZCIsImQu2WembcCB'
This article references the Swagger UI available as part of API documentation authorization; it uses email and password login credentials instead of a token.
API operations for tasks in Talend Cloud
Here are the operations available for accessing a task or its details, and for managing task execution:
Here are details on how to perform each operation with different scenarios:
Get available Tasks - /executables
/executables lists available tasks in all environments using the GET method.
The HTTPS URL for this operation is https://api.eu.cloud.talend.com/tmc/v1.2/executables.
To try this in the Swagger UI:
- Click the name of the operation to expand it.
- Click the Try it out! button.
Notice that /executables is highlighted in the Curl and Request URL sections:
The Response Body section lists all tasks in all environments of the Talend Cloud subscription. In this operation, a Response Code of 200 indicates that the API call is successful.
Get Task details - /executables/{id}
To get task details by task ID instead of getting all tasks, you use the /executables/{id} operation. The HTTPS URL for this operation is https://api.eu.cloud.talend.com/tmc/v1.2/executables/5c275067e91341357ef0b86b.
Execute Task - /executions
To execute a task, use /executions and specify the execution ID. In the example below, the parameter required for execution is the executable ID. In this case, the task is executable. Specify the parameter in JSON format. The response is the execution ID.
You can verify the execution logs in TMC by opening the task and viewing the run history. The execution ID returned as part of Response Body is used to find the execution. The screenshot shows the log for the sample task execution:
Terminate Task execution - /executions/{id}
To terminate a task in execution, use /executions/{id} called using the DELETE method. For example, in the Swagger UI as below, using the f88b8a8f-4a51-4ac5-9453-2c8eaf1e01a4 execution ID returned as part of a previous request (in the Execute Task example) terminates task execution. Because task execution in the previous API call was successful, the response returned for this terminate operation is Nothing to do for the task: its status is EXECUTION_SUCCESS.
In a real-world scenario, the terminate task would help stop execution of any long-running task.
Get Task execution status - /executions/{id}
Before terminating a task, calling /executions/{id} using the GET method returns the status of the task. This operation of getting the execution status by ID tells you whether the task is in progress, has been completed, or has failed. In the screenshot below, for the f88b8a8f-4a51-4ac5-9453-2c8eaf1e01a4 sample execution ID, notice the detailed status returned by the operation as part of Response Body:
API operations for plans in Talend Cloud
Get available Plans - /executables/plans
Like tasks, the cloud API allows you to manage plans externally. A plan is the step-by-step execution of one or more tasks. To list all plans created in all environments, the request URL, submitted using the GET method, is https://api.eu.cloud.talend.com/tmc/v1.2/executables/plans. Response Body lists plans in JSON format:
Get Plan details - /executables/plans/{id}
To get details on a particular plan using the executable ID, the request URL, submitted using a GET method, is https://api.eu.cloud.talend.com/tmc/v1.2/executables/plans/{id}. In this example, the executable ID is 49fe0c6d-95e8-413c-aa97-13a15e506350, so the request URL is https://api.eu.cloud.talend.com/tmc/v1.2/executables/plans/49fe0c6d-95e8-413c-aa97-13a15e506350.
The response for this operation consists of detailed plan information in JSON format:
Execute Plan - /executions/plans
To execute a plan from an external system, the request URL format is https://api.eu.cloud.talend.com/tmc/v1.2/executions/plans. This URL is submitted using the POST method. The parameter required for this operation consists of an executable ID in JSON format:
Just as with a task execution using the POST method, a plan execution returns an execution ID as the response. A plan execution generates logs for every task in the steps in the plan:
Get Plan execution status - /executions/plans/{id}
To get the execution status of a plan, the request URL format is https://api.eu.cloud.talend.com/tmc/v1.2/executions/plans/{id}. For this example, the request URL is https://api.eu.cloud.talend.com/tmc/v1.2/executions/plans/67975122-8e92-4b81-8818-6ce161763ece.
Response Body contains detailed information about the plan execution:
API operations for promotions in Talend Cloud
Get available Promotions - /executables/promotions
To get a list of all promotions, the request URL is https://api.eu.cloud.talend.com/tmc/v1.2/executables/promotions. Whether it is a list of promotions, tasks, or plans, the API call returns the response based on the credentials or token permissions (based on user access). This screenshot shows the sample get available promotions operation:
Get Promotion details - /executables/promotions/{id}
You can get the details of a promotion from the executable ID. Notice the highlighted Request URL and Response Body sections:
Execute Promotion - /executions/promotions
For the execute promotion operation, the request URL is https://api.eu.cloud.talend.com/tmc/v1.2/executions/promotions, called using a POST method that requires a JSON parameter:
{
"executable": "5ce39250b0daaa43cfc64271",
"keepTargetResources": true,
"advanced": {
"artifactId": "5d5bc62796184c43f45d310e",
"artifactType": "ACTION"
}
}
The value for artifactType in the JSON parameter determines the scope of the promotion. Refer to Managing promotions in the Talend Help Center for details about promoting artifacts, tasks, plans, workspaces, and environments.
The ACTION value promotes an artifact.
You are ready to explore the execute promotion operation in more detail. For the promotion in this article, the source environment is Vpdev and the target environment is VPProd. An artifact is promoted using artifact ID 5d5bc62796184c43f45d310e in the VPdev environment:
The target environment does not have this artifact before executing the promotion:
When you execute the promotion, Response Body for the execute promotion operation contains the execution ID:
The artifact has been promoted:
Get Promotion execution status - /executions/promotions/{id}
Using the execution ID returned as the response with the previous execute promotion operation, you can obtain the execution status of another operation, Get Promotion execution status. The request URL format is https://api.eu.cloud.talend.com/tmc/v1.2/executions/promotions/{id}. For example, the URL for the execution ID in the previous operation is https://api.eu.cloud.talend.com/tmc/v1.2/executions/promotions/5d5c0223780a65440e3fed53:
Conclusion
You have learned how to use the Talend Cloud Management Console Public API to manage tasks, plans, and promotions from an external system. You can use either a personal access token or Talend Cloud access credentials. The best practice is to use a personal access token to manage Talend Cloud tasks, plans, and promotions. Performing a combination of operations through the API is ideal for most use cases that require external management.
