|
|
@@ -1,108 +1,75 @@
|
|
|
[role="xpack"]
|
|
|
[testenv="basic"]
|
|
|
[[rollup-stop-job]]
|
|
|
-=== Stop rollup job API
|
|
|
+=== Stop {rollup-jobs} API
|
|
|
+[subs="attributes"]
|
|
|
++++
|
|
|
-<titleabbrev>Stop job</titleabbrev>
|
|
|
+<titleabbrev>Stop {rollup-jobs}</titleabbrev>
|
|
|
++++
|
|
|
|
|
|
-experimental[]
|
|
|
+Stops an existing, started {rollup-job}.
|
|
|
|
|
|
-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.
|
|
|
+experimental[]
|
|
|
|
|
|
-==== Request
|
|
|
+[[rollup-stop-job-request]]
|
|
|
+==== {api-request-title}
|
|
|
|
|
|
`POST _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`.
|
|
|
+[[rollup-stop-job-prereqs]]
|
|
|
+==== {api-prereq-title}
|
|
|
|
|
|
-`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.
|
|
|
+* You must have `manage` or `manage_rollup` cluster privileges to use this API.
|
|
|
For more information, see
|
|
|
-{xpack-ref}/security-privileges.html[Security Privileges].
|
|
|
+{stack-ov}/security-privileges.html[Security privileges].
|
|
|
|
|
|
+[[rollup-stop-job-desc]]
|
|
|
+===== {api-description-title}
|
|
|
|
|
|
-==== Examples
|
|
|
+If you try to stop a job that does not exist, an exception occurs. If you try
|
|
|
+to stop a job that is already stopped, nothing happens.
|
|
|
|
|
|
-If we have an already-started rollup job named `sensor`, it can be stopped with:
|
|
|
+[[rollup-stop-job-path-parms]]
|
|
|
+==== {api-path-parms-title}
|
|
|
|
|
|
-[source,js]
|
|
|
---------------------------------------------------
|
|
|
-POST _rollup/job/sensor/_stop
|
|
|
---------------------------------------------------
|
|
|
-// CONSOLE
|
|
|
-// TEST[setup:sensor_started_rollup_job]
|
|
|
-// TEST[s/_stop/_stop?wait_for_completion=true&timeout=10s/]
|
|
|
+`<job_id>`::
|
|
|
+ (string) Required. Identifier for the {rollup-job}.
|
|
|
|
|
|
-Which will return the response:
|
|
|
+[[rollup-stop-job-query-parms]]
|
|
|
+==== {api-query-parms-title}
|
|
|
|
|
|
-[source,js]
|
|
|
-----
|
|
|
-{
|
|
|
- "stopped": true
|
|
|
-}
|
|
|
-----
|
|
|
-// TESTRESPONSE
|
|
|
+`timeout`::
|
|
|
+ (TimeValue) Optional. If `wait_for_completion` is `true`, the API blocks for
|
|
|
+ (at maximum) the specified duration while waiting for the job to stop. If more
|
|
|
+ than `timeout` time has passed, the API throws a timeout exception. Defaults
|
|
|
+ to `30s`.
|
|
|
++
|
|
|
+--
|
|
|
+NOTE: Even if a timeout exception is thrown, the stop request is still
|
|
|
+processing and eventually moves the job to `STOPPED`. The timeout simply means
|
|
|
+the API call itself timed out while waiting for the status change.
|
|
|
|
|
|
-If however we try to stop a job which doesn't exist:
|
|
|
+--
|
|
|
+
|
|
|
+`wait_for_completion`::
|
|
|
+ (boolean) Optional. 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 is stopped asynchronously in the background. Defaults to
|
|
|
+ `false`.
|
|
|
|
|
|
-[source,js]
|
|
|
---------------------------------------------------
|
|
|
-POST _rollup/job/does_not_exist/_stop
|
|
|
---------------------------------------------------
|
|
|
-// CONSOLE
|
|
|
-// TEST[catch:missing]
|
|
|
+[[rollup-stop-job-response-codes]]
|
|
|
+==== {api-response-codes-title}
|
|
|
|
|
|
-A 404 `resource_not_found` exception will be thrown:
|
|
|
+`404` (Missing resources)::
|
|
|
+ This code indicates that there are no resources that match the request. It
|
|
|
+ occurs if you try to stop a job that doesn't exist.
|
|
|
|
|
|
-[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`:
|
|
|
+[[rollup-stop-job-examples]]
|
|
|
+==== {api-examples-title}
|
|
|
+
|
|
|
+Since only a stopped job can be deleted, it can be useful to block the API until
|
|
|
+the indexer has fully stopped. This is accomplished with the
|
|
|
+`wait_for_completion` query parameter, and optionally a `timeout`:
|
|
|
|
|
|
|
|
|
[source,js]
|
|
|
@@ -112,7 +79,6 @@ POST _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.
|
|
|
+The parameter blocks 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 is thrown.
|
Lisa Cawley