[DOCS] Update APIs for multiple jobs or datafeeds (elastic/x-pack-elasticsearch#2105)

* [DOCS] Update APIs for multiple jobs or datafeeds

* [DOCS] Fix syntax diagrams for ML stop/close APIs

* [DOCS] Removed TBD authorization for ML APIs

Original commit: elastic/x-pack-elasticsearch@1a9137a5a7
This commit is contained in:
Lisa Cawley 2017-08-09 08:30:21 -07:00 committed by GitHub
parent a4dd177978
commit 1bb3ad38c7
6 changed files with 98 additions and 36 deletions

View File

@ -2,7 +2,7 @@
[[ml-close-job]]
=== Close Jobs
The close job API enables you to close a job.
The close job API enables you to close one or more jobs.
A job can be opened and closed multiple times throughout its lifecycle.
A closed job cannot receive data or perform analysis
@ -11,12 +11,18 @@ operations, but you can still explore and navigate results.
==== Request
`POST _xpack/ml/anomaly_detectors/<job_id>/_close`
`POST _xpack/ml/anomaly_detectors/<job_id>/_close` +
`POST _xpack/ml/anomaly_detectors/<job_id>,<job_id>/_close` +
`POST _xpack/ml/anomaly_detectors/_all/_close` +
==== Description
//A job can be closed once all data has been analyzed.
You can close multiple jobs in a single API request by using a group name, a
comma-separated list of jobs, or a wildcard expression. You can close all jobs
by using `_all` or by specifying `*` as the `<job_id>`.
When you close a job, it runs housekeeping tasks such as pruning the model history,
flushing buffers, calculating final results and persisting the model snapshots.
@ -40,8 +46,9 @@ results the job might have recently produced or might produce in the future.
==== Path Parameters
`job_id` (required)::
(string) Identifier for the job
`job_id`::
(string) Identifier for the job. It can be a job identifier, a group name, or
a wildcard expression.
==== Query Parameters
@ -59,7 +66,6 @@ results the job might have recently produced or might produce in the future.
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see {xpack-ref}/security-privileges.html[Security Privileges].
//<<privileges-list-cluster>>.
==== Examples

View File

@ -8,13 +8,24 @@ The get {dfeed} statistics API enables you to retrieve usage information for
==== Request
`GET _xpack/ml/datafeeds/<feed_id>/_stats` +
`GET _xpack/ml/datafeeds/<feed_id>,<feed_id>/_stats` +
`GET _xpack/ml/datafeeds/_stats` +
`GET _xpack/ml/datafeeds/<feed_id>/_stats`
`GET _xpack/ml/datafeeds/_stats/_all` +
==== Description
You can get statistics for multiple {dfeeds} in a single API request by using a
comma-separated list of {dfeeds} or a wildcard expression. You can get
statistics for all {dfeeds} by using `_all`, by specifying `*` as the
`<feed_id>`, or by omitting the `<feed_id>`.
If the {dfeed} is stopped, the only information you receive is the
`datafeed_id` and the `state`.
@ -22,9 +33,9 @@ If the {dfeed} is stopped, the only information you receive is the
==== Path Parameters
`feed_id`::
(string) Identifier for the {dfeed}.
This parameter does not support wildcards, but you can specify `_all` or
omit the `feed_id` to get information about all {dfeeds}.
(string) Identifier for the {dfeed}. It can be a {dfeed} identifier or a
wildcard expression. If you do not specify one of these options, the API
returns statistics for all {dfeeds}.
==== Results
@ -41,7 +52,6 @@ The API returns the following information:
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
//<<privileges-list-cluster>>.
==== Examples

View File

@ -7,18 +7,29 @@ The get {dfeeds} API enables you to retrieve configuration information for
==== Request
`GET _xpack/ml/datafeeds/<feed_id>` +
`GET _xpack/ml/datafeeds/<feed_id>,<feed_id>` +
`GET _xpack/ml/datafeeds/` +
`GET _xpack/ml/datafeeds/<feed_id>`
`GET _xpack/ml/datafeeds/_all` +
//===== Description
===== Description
You can get information for multiple {dfeeds} in a single API request by using a
comma-separated list of {dfeeds} or a wildcard expression. You can get
information for all {dfeeds} by using `_all`, by specifying `*` as the
`<feed_id>`, or by omitting the `<feed_id>`.
==== Path Parameters
`feed_id`::
(string) Identifier for the {dfeed}.
This parameter does not support wildcards, but you can specify `_all` or
omit the `feed_id` to get information about all {dfeeds}.
(string) Identifier for the {dfeed}. It can be a {dfeed} identifier or a
wildcard expression. If you do not specify one of these options, the API
returns information about all {dfeeds}.
==== Results
@ -35,7 +46,6 @@ The API returns the following information:
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
//<<privileges-list-cluster>>.
==== Examples

View File

@ -7,18 +7,31 @@ The get jobs API enables you to retrieve usage information for jobs.
==== Request
`GET _xpack/ml/anomaly_detectors/_stats` +
`GET _xpack/ml/anomaly_detectors/<job_id>/_stats`
//===== Description
`GET _xpack/ml/anomaly_detectors/<job_id>,<job_id>/_stats` +
`GET _xpack/ml/anomaly_detectors/_stats` +
`GET _xpack/ml/anomaly_detectors/_stats/_all` +
===== Description
You can get statistics for multiple jobs in a single API request by using a
group name, a comma-separated list of jobs, or a wildcard expression. You can
get statistics for all jobs by using `_all`, by specifying `*` as the
`<job_id>`, or by omitting the `<job_id>`.
==== Path Parameters
`job_id`::
(string) A required identifier for the job.
This parameter does not support wildcards, but you can specify `_all` or omit
the `job_id` to get information about all jobs.
(string) An identifier for the job. It can be a job identifier, a group name,
or a wildcard expression. If you do not specify one of these options, the API
returns statistics for all jobs.
==== Results
@ -35,7 +48,6 @@ The API returns the following information:
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
//<<privileges-list-cluster>>.
==== Examples

View File

@ -7,19 +7,29 @@ The get jobs API enables you to retrieve configuration information for jobs.
==== Request
`GET _xpack/ml/anomaly_detectors/<job_id>` +
`GET _xpack/ml/anomaly_detectors/<job_id>,<job_id>` +
`GET _xpack/ml/anomaly_detectors/` +
`GET _xpack/ml/anomaly_detectors/<job_id>`
`GET _xpack/ml/anomaly_detectors/_all`
===== Description
You can get information for multiple jobs in a single API request by using a
group name, a comma-separated list of jobs, or a wildcard expression. You can
get information for all jobs by using `_all`, by specifying `*` as the
`<job_id>`, or by omitting the `<job_id>`.
//===== Description
==== Path Parameters
`job_id`::
(string) Identifier for the job.
This parameter does not support wildcards, but you can specify `_all` or omit
the `job_id` to get information about all jobs.
(string) Identifier for the job. It can be a job identifier, a group name,
or a wildcard expression. If you do not specify one of these options, the API
returns information for all jobs.
==== Results
@ -35,7 +45,6 @@ The API returns the following information:
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
//<<privileges-list-cluster>>.
==== Examples

View File

@ -2,19 +2,34 @@
[[ml-stop-datafeed]]
=== Stop {dfeeds-cap}
The stop {dfeeds} API enables you to stop one or more {dfeeds}.
A {dfeed} that is stopped ceases to retrieve data from {es}.
A {dfeed} can be started and stopped multiple times throughout its lifecycle.
==== Request
`POST _xpack/ml/datafeeds/<feed_id>/_stop`
`POST _xpack/ml/datafeeds/<feed_id>/_stop` +
`POST _xpack/ml/datafeeds/<feed_id>,<feed_id>/_stop` +
`POST _xpack/ml/datafeeds/_all/_stop`
//TBD: Can there be spaces between the items in the list?
===== Description
You can stop multiple {dfeeds} in a single API request by using a
comma-separated list of {dfeeds} or a wildcard expression. You can close all
{dfeeds} by using `_all` or by specifying `*` as the `<feed_id>`.
//===== Description
==== Path Parameters
`feed_id` (required)::
(string) Identifier for the {dfeed}
`feed_id`::
(string) Identifier for the {dfeed}. It can be a {dfeed} identifier or a
wildcard expression.
==== Request Body
@ -31,7 +46,7 @@ A {dfeed} can be started and stopped multiple times throughout its lifecycle.
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
//<<privileges-list-cluster>>.
==== Examples