mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-03-09 14:34:43 +00:00
c346a0f027
This adds a `wait_for_completion` flag which allows the user to block the Stop API until the task has actually moved to a stopped state, instead of returning immediately. If the flag is set, a `timeout` parameter can be specified to determine how long (at max) to block the API call. If unspecified, the timeout is 30s. If the timeout is exceeded before the job moves to STOPPED, a timeout exception is thrown. Note: this is just signifying that the API call itself timed out. The job will remain in STOPPING and evenutally flip over to STOPPED in the background. If the user asks the API to block, we move over the the generic threadpool so that we don't hold up a networking thread.
117 lines
3.4 KiB
Plaintext
117 lines
3.4 KiB
Plaintext
[role="xpack"]
|
|
[testenv="basic"]
|
|
[[rollup-stop-job]]
|
|
=== Stop Job API
|
|
++++
|
|
<titleabbrev>Stop Job</titleabbrev>
|
|
++++
|
|
|
|
experimental[]
|
|
|
|
This API stops an existing, started rollup job. If the job does not exist an exception will be thrown.
|
|
Stopping an already stopped job has no action.
|
|
|
|
==== Request
|
|
|
|
`POST _xpack/rollup/job/<job_id>/_stop`
|
|
|
|
//===== Description
|
|
|
|
==== Path Parameters
|
|
|
|
`job_id` (required)::
|
|
(string) Identifier for the job
|
|
|
|
==== Query Parameters
|
|
|
|
`wait_for_completion` (optional)::
|
|
(boolean) if set to true, causes the API to block until the indexer state completely stops. If set to false, the
|
|
API returns immediately and the indexer will be stopped asynchronously in the background. Defaults to `false`.
|
|
|
|
`timeout` (optional)::
|
|
(TimeValue) if `wait_for_completion=true`, the API will block for (at maximum)
|
|
the specified duration while waiting for the job to stop. If more than `timeout` time has passed, the API
|
|
will throw a timeout exception. Note: even if a timeout exception is thrown, the stop request is still processing and
|
|
will eventually move the job to `STOPPED`. The timeout simply means the API call itself timed out while waiting
|
|
for the status change. Defaults to `30s`
|
|
|
|
==== Request Body
|
|
|
|
There is no request body for the Stop Job API.
|
|
|
|
==== Authorization
|
|
|
|
You must have `manage` or `manage_rollup` cluster privileges to use this API.
|
|
For more information, see
|
|
{xpack-ref}/security-privileges.html[Security Privileges].
|
|
|
|
|
|
==== Examples
|
|
|
|
If we have an already-started rollup job named `sensor`, it can be stopped with:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/rollup/job/sensor/_stop
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:sensor_started_rollup_job]
|
|
|
|
Which will return the response:
|
|
|
|
[source,js]
|
|
----
|
|
{
|
|
"stopped": true
|
|
}
|
|
----
|
|
// TESTRESPONSE
|
|
|
|
If however we try to stop a job which doesn't exist:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/rollup/job/does_not_exist/_stop
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[catch:missing]
|
|
|
|
A 404 `resource_not_found` exception will be thrown:
|
|
|
|
[source,js]
|
|
----
|
|
{
|
|
"error" : {
|
|
"root_cause" : [
|
|
{
|
|
"type" : "resource_not_found_exception",
|
|
"reason" : "Task for Rollup Job [does_not_exist] not found",
|
|
"stack_trace": ...
|
|
}
|
|
],
|
|
"type" : "resource_not_found_exception",
|
|
"reason" : "Task for Rollup Job [does_not_exist] not found",
|
|
"stack_trace": ...
|
|
},
|
|
"status": 404
|
|
}
|
|
----
|
|
// TESTRESPONSE[s/"stack_trace": .../"stack_trace": $body.$_path/]
|
|
|
|
===== Waiting for the job to stop
|
|
|
|
Since only a stopped job can be deleted, it can be useful to block the StopJob API until the indexer has fully
|
|
stopped. This is accomplished with the `wait_for_completion` query parameter, and optionally a `timeout`:
|
|
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/rollup/job/sensor/_stop?wait_for_completion=true&timeout=10s
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:sensor_started_rollup_job]
|
|
|
|
The parameter will block the API call from returning until either the job has moved to `STOPPED`, or the specified
|
|
time has elapsed. If the specified time elapses without the job moving to `STOPPED`, a timeout exception will be thrown.
|
|
|
|
If `wait_for_completion=true` is specified without a `timeout`, a default timeout of 30 seconds is used. |