diff --git a/docs/api-ref.md b/docs/api-ref.md index f0109bdac..b4316a122 100644 --- a/docs/api-ref.md +++ b/docs/api-ref.md @@ -2709,6 +2709,215 @@ The `SubscriptionItem`. See [SubscriptionItem class](#subscriptionitem-class)

+--- + +## Tasks + +Using the TSC library, you can get information about all the tasks on a site and you can remove tasks. To create new tasks see [Schedules](#schedules). + +The task resources for Tableau Server are defined in the `TaskItem` class. The class corresponds to the task resources you can access using the Tableau Server REST API. The task methods are based upon the endpoints for tasks in the REST API and operate on the `TaskItem` class. + +### TaskItem class + +```py +TaskItem(id, task_type, priority, consecutive_failed_count=0, schedule_id=None, target=None) +``` + +**Attributes** + +Name | Description +:--- | :--- +`consecutive_failed_count` | The number of failed consecutive executions. +`id` | The id of the task on the site. +`priority` | The priority of the task on the server. +`schedule_id` | The id of the schedule on the site. +`target` | An object, `datasource` or `workbook` which is associated to the task. Source file: models/target.py +`task_type` | Type of extract task - full or incremental refresh. + + +**Example** + +```py +# import tableauserverclient as TSC +# server = TSC.Server('server') + + task = server.tasks.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d') + print(task) + +``` + +Source file: models/task_item.py + +
+
+ + +### Tasks methods + +The Tableau Server Client provides several methods for interacting with task resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API. + +Source file: server/endpoint/tasks_endpoint.py +
+
+ +#### tasks.get + +```py +tasks.get(req_options=None) +``` + +Returns information about the tasks on the specified site. + +REST API: [Get Extract Refresh Tasks on Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#get_extract_refresh_tasks){:target="_blank"} + + +**Parameters** + +Name | Description + :--- | : --- +`req_option` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. + + +**Returns** + +Returns a list of `TaskItem` objects and a `PaginationItem` object. Use these values to iterate through the results. + + +**Example** + + +```py +import tableauserverclient as TSC +tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +server = TSC.Server('https://SERVERURL') + +with server.auth.sign_in(tableau_auth): + all_tasks, pagination_item = server.tasks.get() + print("\nThere are {} tasks on site: ".format(pagination_item.total_available)) + print([task.id for task in all_tasks]) +``` + +
+
+ +#### tasks.get_by_id + + +```py +tasks.get_by_id(task_id) +``` + +Returns information about the specified task. + +REST API: [Query Extract Refresh Task On Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#get_extract_refresh_task){:target="_blank"} + + +**Parameters** + +Name | Description + :--- | : --- +`task_id` | The `task_id` specifies the task to query. + + +**Exceptions** + +Error | Description + :--- | : --- +`Task ID undefined.` | Raises an exception if a valid `task_id` is not provided. + + +**Returns** + +The `TaskItem`. See [TaskItem class](#taskitem-class) + + +**Example** + +```py + task1 = server.tasks.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d') + print(task1.task_type) + +``` + +
+
+ +#### tasks.run + + +```py +tasks.run(task_item) +``` + +Runs the specified extract refresh task. + +To run a extract refresh task you need to first lookup the task `task_item` (`TaskItem` class). + +REST API: [Run Extract Refresh Task](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#run_extract_refresh_task){:target="_blank"} + + +**Parameters** + +Name | Description + :--- | : --- +`task_item` | You can pass the method a task object. + + +**Returns** + +Returns the REST API response. + +**Example** + +```py +# import tableauserverclient as TSC +# server = TSC.Server('server') +# login, etc. + + task = server.tasks.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d') + server.tasks.run(task) + +``` + +
+
+ +#### tasks.delete + + +```py +tasks.delete(task_id) +``` + +Deletes an extract refresh task. + +REST API: [Run Extract Refresh Task](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobstasksschedules.htm#delete_workbook){:target="_blank"} + +**Parameters** + +Name | Description + :--- | : --- +`task_id` | The `task_id` specifies the task to delete. + + +**Exceptions** + +Error | Description + :--- | : --- +`Task ID undefined.` | Raises an exception if a valid `task_id` is not provided. + + +**Example** + +```py + server.tasks.delete('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d') + +``` + +
+
+ + --- ## Users