1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
|
# Licensed to Elasticsearch B.V. under one or more contributor
# license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright
# ownership. Elasticsearch B.V. licenses this file to you under
# the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.
import typing as t
from elastic_transport import ObjectApiResponse
from ._base import NamespacedClient
from .utils import (
SKIP_IN_PATH,
Stability,
_quote,
_rewrite_parameters,
_stability_warning,
)
class TasksClient(NamespacedClient):
@_rewrite_parameters()
@_stability_warning(Stability.EXPERIMENTAL)
def cancel(
self,
*,
task_id: t.Optional[str] = None,
actions: t.Optional[t.Union[str, t.Sequence[str]]] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
human: t.Optional[bool] = None,
nodes: t.Optional[t.Sequence[str]] = None,
parent_task_id: t.Optional[str] = None,
pretty: t.Optional[bool] = None,
wait_for_completion: t.Optional[bool] = None,
) -> ObjectApiResponse[t.Any]:
"""
.. raw:: html
<p>Cancel a task.</p>
<p>WARNING: 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.</p>
<p>A task may continue to run for some time after it has been cancelled because it may not be able to safely stop its current activity straight away.
It is also possible that Elasticsearch must complete its work on other tasks before it can process the cancellation.
The get task information API will continue to list these cancelled tasks until they complete.
The cancelled flag in the response indicates that the cancellation command has been processed and the task will stop as soon as possible.</p>
<p>To troubleshoot why a cancelled task does not complete promptly, use the get task information API with the <code>?detailed</code> parameter to identify the other tasks the system is running.
You can also use the node hot threads API to obtain detailed information about the work the system is doing instead of completing the cancelled task.</p>
`<https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-tasks>`_
:param task_id: The task identifier.
:param actions: A comma-separated list or wildcard expression of actions that
is used to limit the request.
:param nodes: A comma-separated list of node IDs or names that is used to limit
the request.
:param parent_task_id: A parent task ID that is used to limit the tasks.
:param wait_for_completion: If true, the request blocks until all found tasks
are complete.
"""
__path_parts: t.Dict[str, str]
if task_id not in SKIP_IN_PATH:
__path_parts = {"task_id": _quote(task_id)}
__path = f'/_tasks/{__path_parts["task_id"]}/_cancel'
else:
__path_parts = {}
__path = "/_tasks/_cancel"
__query: t.Dict[str, t.Any] = {}
if actions is not None:
__query["actions"] = actions
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
__query["filter_path"] = filter_path
if human is not None:
__query["human"] = human
if nodes is not None:
__query["nodes"] = nodes
if parent_task_id is not None:
__query["parent_task_id"] = parent_task_id
if pretty is not None:
__query["pretty"] = pretty
if wait_for_completion is not None:
__query["wait_for_completion"] = wait_for_completion
__headers = {"accept": "application/json"}
return self.perform_request( # type: ignore[return-value]
"POST",
__path,
params=__query,
headers=__headers,
endpoint_id="tasks.cancel",
path_parts=__path_parts,
)
@_rewrite_parameters()
@_stability_warning(Stability.EXPERIMENTAL)
def get(
self,
*,
task_id: str,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
human: t.Optional[bool] = None,
pretty: t.Optional[bool] = None,
timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
wait_for_completion: t.Optional[bool] = None,
) -> ObjectApiResponse[t.Any]:
"""
.. raw:: html
<p>Get task information.
Get information about a task currently running in the cluster.</p>
<p>WARNING: 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.</p>
<p>If the task identifier is not found, a 404 response code indicates that there are no resources that match the request.</p>
`<https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-tasks>`_
:param task_id: The task identifier.
:param timeout: The period to wait for a response. If no response is received
before the timeout expires, the request fails and returns an error.
:param wait_for_completion: If `true`, the request blocks until the task has
completed.
"""
if task_id in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'task_id'")
__path_parts: t.Dict[str, str] = {"task_id": _quote(task_id)}
__path = f'/_tasks/{__path_parts["task_id"]}'
__query: t.Dict[str, t.Any] = {}
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
__query["filter_path"] = filter_path
if human is not None:
__query["human"] = human
if pretty is not None:
__query["pretty"] = pretty
if timeout is not None:
__query["timeout"] = timeout
if wait_for_completion is not None:
__query["wait_for_completion"] = wait_for_completion
__headers = {"accept": "application/json"}
return self.perform_request( # type: ignore[return-value]
"GET",
__path,
params=__query,
headers=__headers,
endpoint_id="tasks.get",
path_parts=__path_parts,
)
@_rewrite_parameters()
@_stability_warning(Stability.EXPERIMENTAL)
def list(
self,
*,
actions: t.Optional[t.Union[str, t.Sequence[str]]] = None,
detailed: t.Optional[bool] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
group_by: t.Optional[
t.Union[str, t.Literal["nodes", "none", "parents"]]
] = None,
human: t.Optional[bool] = None,
nodes: t.Optional[t.Union[str, t.Sequence[str]]] = None,
parent_task_id: t.Optional[str] = None,
pretty: t.Optional[bool] = None,
timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
wait_for_completion: t.Optional[bool] = None,
) -> ObjectApiResponse[t.Any]:
"""
.. raw:: html
<p>Get all tasks.
Get information about the tasks currently running on one or more nodes in the cluster.</p>
<p>WARNING: 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.</p>
<p><strong>Identifying running tasks</strong></p>
<p>The <code>X-Opaque-Id header</code>, 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 enables you to track certain calls or associate certain tasks with the client that started them.
For example:</p>
<pre><code>curl -i -H "X-Opaque-Id: 123456" "http://localhost:9200/_tasks?group_by=parents"
</code></pre>
<p>The API returns the following result:</p>
<pre><code>HTTP/1.1 200 OK
X-Opaque-Id: 123456
content-type: application/json; charset=UTF-8
content-length: 831
{
"tasks" : {
"u5lcZHqcQhu-rUoFaqDphA:45" : {
"node" : "u5lcZHqcQhu-rUoFaqDphA",
"id" : 45,
"type" : "transport",
"action" : "cluster:monitor/tasks/lists",
"start_time_in_millis" : 1513823752749,
"running_time_in_nanos" : 293139,
"cancellable" : false,
"headers" : {
"X-Opaque-Id" : "123456"
},
"children" : [
{
"node" : "u5lcZHqcQhu-rUoFaqDphA",
"id" : 46,
"type" : "direct",
"action" : "cluster:monitor/tasks/lists[n]",
"start_time_in_millis" : 1513823752750,
"running_time_in_nanos" : 92133,
"cancellable" : false,
"parent_task_id" : "u5lcZHqcQhu-rUoFaqDphA:45",
"headers" : {
"X-Opaque-Id" : "123456"
}
}
]
}
}
}
</code></pre>
<p>In this example, <code>X-Opaque-Id: 123456</code> is the ID as a part of the response header.
The <code>X-Opaque-Id</code> in the task <code>headers</code> is the ID for the task that was initiated by the REST request.
The <code>X-Opaque-Id</code> in the children <code>headers</code> is the child task of the task that was initiated by the REST request.</p>
`<https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-tasks>`_
:param actions: A comma-separated list or wildcard expression of actions used
to limit the request. For example, you can use `cluser:*` to retrieve all
cluster-related tasks.
:param detailed: If `true`, the response includes detailed information about
the running tasks. This information is useful to distinguish tasks from each
other but is more costly to run.
:param group_by: A key that is used to group tasks in the response. The task
lists can be grouped either by nodes or by parent tasks.
:param nodes: A comma-separated list of node IDs or names that is used to limit
the returned information.
:param parent_task_id: A parent task identifier that is used to limit returned
information. To return all tasks, omit this parameter or use a value of `-1`.
If the parent task is not found, the API does not return a 404 response code.
:param timeout: The period to wait for each node to respond. If a node does not
respond before its timeout expires, the response does not include its information.
However, timed out nodes are included in the `node_failures` property.
:param wait_for_completion: If `true`, the request blocks until the operation
is complete.
"""
__path_parts: t.Dict[str, str] = {}
__path = "/_tasks"
__query: t.Dict[str, t.Any] = {}
if actions is not None:
__query["actions"] = actions
if detailed is not None:
__query["detailed"] = detailed
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
__query["filter_path"] = filter_path
if group_by is not None:
__query["group_by"] = group_by
if human is not None:
__query["human"] = human
if nodes is not None:
__query["nodes"] = nodes
if parent_task_id is not None:
__query["parent_task_id"] = parent_task_id
if pretty is not None:
__query["pretty"] = pretty
if timeout is not None:
__query["timeout"] = timeout
if wait_for_completion is not None:
__query["wait_for_completion"] = wait_for_completion
__headers = {"accept": "application/json"}
return self.perform_request( # type: ignore[return-value]
"GET",
__path,
params=__query,
headers=__headers,
endpoint_id="tasks.list",
path_parts=__path_parts,
)
|
