[DOCS] Reformats task management API (#45549)
This PR updates the task management API to align with the new API reference template.
This commit is contained in:
István Zoltán Szabó
parent
4a67645e5d
commit
da03a5d8d1
|
|
@ -3,12 +3,52 @@
|
|||
|
||||
beta[The Task Management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible]
|
||||
|
||||
[float]
|
||||
==== Current Tasks Information
|
||||
Returns information about the tasks currently executing in the cluster.
|
||||
|
||||
[[tasks-api-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET /_tasks` +
|
||||
|
||||
`GET /_tasks/{task_id}`
|
||||
|
||||
|
||||
[[tasks-api-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
The task management API allows to retrieve information about the tasks currently
|
||||
executing on one or more nodes in the cluster.
|
||||
|
||||
|
||||
[[tasks-api-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
{task_id}
|
||||
(Optional, string) The ID of the task to return (`node_id:task_number`).
|
||||
|
||||
|
||||
[[tasks-api-query-params]]
|
||||
==== {api-query-parms-title}
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
||||
|
||||
`wait_for_completion`::
|
||||
(Optional, boolean) If `true`, it waits for the matching tasks to complete.
|
||||
Defaults to `false`.
|
||||
|
||||
|
||||
|
||||
[[tasks-api-response-codes]]
|
||||
==== {api-response-codes-title}
|
||||
|
||||
`404` (Missing resources)::
|
||||
If `{task_id}` is specified but not found, this code indicates that there
|
||||
are no resources that match the request.
|
||||
|
||||
|
||||
[[tasks-api-examples]]
|
||||
==== {api-examples-title}
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET _tasks <1>
|
||||
|
|
@ -22,7 +62,7 @@ GET _tasks?nodes=nodeId1,nodeId2&actions=cluster:* <3>
|
|||
<2> Retrieves all tasks running on nodes `nodeId1` and `nodeId2`. See <<cluster-nodes>> for more info about how to select individual nodes.
|
||||
<3> Retrieves all cluster-related tasks running on nodes `nodeId1` and `nodeId2`.
|
||||
|
||||
The result will look similar to the following:
|
||||
The API returns the following result:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -60,6 +100,8 @@ The result will look similar to the following:
|
|||
--------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
===== Retrieve information from a particular task
|
||||
|
||||
It is also possible to retrieve information for a particular task. The following
|
||||
example retrieves information about task `oTUltX4IQMOUUVeiohTt8A:124`:
|
||||
|
||||
|
|
@ -82,6 +124,9 @@ GET _tasks?parent_task_id=oTUltX4IQMOUUVeiohTt8A:123
|
|||
|
||||
If the parent isn't found, the API does not return a 404.
|
||||
|
||||
|
||||
===== Get more information about tasks
|
||||
|
||||
You can also use the `detailed` request parameter to get more information about
|
||||
the running tasks. This is useful for telling one task from another but is more
|
||||
costly to execute. For example, fetching all searches using the `detailed`
|
||||
|
|
@ -94,7 +139,7 @@ GET _tasks?actions=*search&detailed
|
|||
// CONSOLE
|
||||
// TEST[skip:No tasks to retrieve]
|
||||
|
||||
The results might look like:
|
||||
The API returns the following result:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -145,6 +190,9 @@ releases.
|
|||
|
||||
==============================
|
||||
|
||||
|
||||
===== Wait for completion
|
||||
|
||||
The task API can also be used to wait for completion of a particular task. The
|
||||
following call will block for 10 seconds or until the task with id
|
||||
`oTUltX4IQMOUUVeiohTt8A:12345` is completed.
|
||||
|
|
@ -156,8 +204,8 @@ GET _tasks/oTUltX4IQMOUUVeiohTt8A:12345?wait_for_completion=true&timeout=10s
|
|||
// CONSOLE
|
||||
// TEST[catch:missing]
|
||||
|
||||
You can also wait for all tasks for certain action types to finish. This
|
||||
command will wait for all `reindex` tasks to finish:
|
||||
You can also wait for all tasks for certain action types to finish. This command
|
||||
will wait for all `reindex` tasks to finish:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -165,6 +213,9 @@ GET _tasks?actions=*reindex&wait_for_completion=true&timeout=10s
|
|||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
|
||||
===== Listing tasks by using _cat
|
||||
|
||||
Tasks can be also listed using _cat version of the list tasks command, which
|
||||
accepts the same arguments as the standard list tasks command.
|
||||
|
||||
|
|
@ -175,9 +226,8 @@ GET _cat/tasks?detailed
|
|||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
[float]
|
||||
[[task-cancellation]]
|
||||
==== Task Cancellation
|
||||
===== Task Cancellation
|
||||
|
||||
If a long-running task supports cancellation, it can be cancelled with the cancel
|
||||
tasks API. The following example cancels task `oTUltX4IQMOUUVeiohTt8A:12345`:
|
||||
|
|
@ -188,8 +238,9 @@ POST _tasks/oTUltX4IQMOUUVeiohTt8A:12345/_cancel
|
|||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
The task cancellation command supports the same task selection parameters as the list tasks command, so multiple tasks
|
||||
can be cancelled at the same time. For example, the following command will cancel all reindex tasks running on the
|
||||
The task cancellation command supports the same task selection parameters as the
|
||||
list tasks command, so multiple tasks can be cancelled at the same time. For
|
||||
example, the following command will cancel all reindex tasks running on the
|
||||
nodes `nodeId1` and `nodeId2`.
|
||||
|
||||
[source,js]
|
||||
|
|
@ -198,11 +249,11 @@ POST _tasks/_cancel?nodes=nodeId1,nodeId2&actions=*reindex
|
|||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
[float]
|
||||
==== Task Grouping
|
||||
===== Task Grouping
|
||||
|
||||
The task lists returned by task API commands can be grouped either by nodes (default) or by parent tasks using the `group_by` parameter.
|
||||
The following command will change the grouping to parent tasks:
|
||||
The task lists returned by task API commands can be grouped either by nodes
|
||||
(default) or by parent tasks using the `group_by` parameter. The following
|
||||
command will change the grouping to parent tasks:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -218,12 +269,13 @@ GET _tasks?group_by=none
|
|||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
[float]
|
||||
==== Identifying running tasks
|
||||
|
||||
The `X-Opaque-Id` header, when provided on the HTTP request header, is going to be returned as a header in the response as well as
|
||||
in the `headers` field for in the task information. This allows to track certain calls, or associate certain tasks with
|
||||
a the client that started them:
|
||||
===== Identifying running tasks
|
||||
|
||||
The `X-Opaque-Id` header, when provided on the HTTP request header, is going to
|
||||
be returned as a header in the response as well as in the `headers` field for in
|
||||
the task information. This allows to track certain calls, or associate certain
|
||||
tasks with a the client that started them:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
|
|
@ -231,7 +283,7 @@ curl -i -H "X-Opaque-Id: 123456" "http://localhost:9200/_tasks?group_by=parents"
|
|||
--------------------------------------------------
|
||||
//NOTCONSOLE
|
||||
|
||||
The result will look similar to the following:
|
||||
The API returns the following result:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue