84 lines
2.6 KiB
Plaintext
84 lines
2.6 KiB
Plaintext
[role="xpack"]
|
|
[testenv="basic"]
|
|
[[rollup-stop-job]]
|
|
=== Stop {rollup-jobs} API
|
|
[subs="attributes"]
|
|
++++
|
|
<titleabbrev>Stop {rollup-jobs}</titleabbrev>
|
|
++++
|
|
|
|
Stops an existing, started {rollup-job}.
|
|
|
|
experimental[]
|
|
|
|
[[rollup-stop-job-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST _rollup/job/<job_id>/_stop`
|
|
|
|
[[rollup-stop-job-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have `manage` or
|
|
`manage_rollup` cluster privileges to use this API. For more information, see
|
|
<<security-privileges>>.
|
|
|
|
[[rollup-stop-job-desc]]
|
|
===== {api-description-title}
|
|
|
|
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.
|
|
|
|
[[rollup-stop-job-path-parms]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<job_id>`::
|
|
(Required, string) Identifier for the {rollup-job}.
|
|
|
|
[[rollup-stop-job-query-parms]]
|
|
==== {api-query-parms-title}
|
|
|
|
`timeout`::
|
|
(Optional, TimeValue) 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.
|
|
|
|
--
|
|
|
|
`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 is stopped asynchronously in the background. Defaults to
|
|
`false`.
|
|
|
|
[[rollup-stop-job-response-codes]]
|
|
==== {api-response-codes-title}
|
|
|
|
`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.
|
|
|
|
[[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,console]
|
|
--------------------------------------------------
|
|
POST _rollup/job/sensor/_stop?wait_for_completion=true&timeout=10s
|
|
--------------------------------------------------
|
|
// TEST[setup:sensor_started_rollup_job]
|
|
|
|
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.
|