From 1bb3ad38c7128c67440b396af2fcebaa15bae201 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 9 Aug 2017 08:30:21 -0700 Subject: [PATCH] [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@1a9137a5a7e4efd309dccf7b3632e70fc9311b11 --- docs/en/rest-api/ml/close-job.asciidoc | 18 ++++++++----- .../rest-api/ml/get-datafeed-stats.asciidoc | 22 +++++++++++----- docs/en/rest-api/ml/get-datafeed.asciidoc | 22 +++++++++++----- docs/en/rest-api/ml/get-job-stats.asciidoc | 24 +++++++++++++----- docs/en/rest-api/ml/get-job.asciidoc | 23 +++++++++++------ docs/en/rest-api/ml/stop-datafeed.asciidoc | 25 +++++++++++++++---- 6 files changed, 98 insertions(+), 36 deletions(-) diff --git a/docs/en/rest-api/ml/close-job.asciidoc b/docs/en/rest-api/ml/close-job.asciidoc index 5644ed721e0..1e6ac728268 100644 --- a/docs/en/rest-api/ml/close-job.asciidoc +++ b/docs/en/rest-api/ml/close-job.asciidoc @@ -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//_close` +`POST _xpack/ml/anomaly_detectors//_close` + + +`POST _xpack/ml/anomaly_detectors/,/_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 ``. 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]. -//<>. ==== Examples diff --git a/docs/en/rest-api/ml/get-datafeed-stats.asciidoc b/docs/en/rest-api/ml/get-datafeed-stats.asciidoc index 1d4a62a3179..bb6e9bfafa2 100644 --- a/docs/en/rest-api/ml/get-datafeed-stats.asciidoc +++ b/docs/en/rest-api/ml/get-datafeed-stats.asciidoc @@ -8,13 +8,24 @@ The get {dfeed} statistics API enables you to retrieve usage information for ==== Request -`GET _xpack/ml/datafeeds/_stats` + -`GET _xpack/ml/datafeeds//_stats` +`GET _xpack/ml/datafeeds//_stats` + + +`GET _xpack/ml/datafeeds/,/_stats` + + +`GET _xpack/ml/datafeeds/_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 +``, or by omitting the ``. + 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]. -//<>. ==== Examples diff --git a/docs/en/rest-api/ml/get-datafeed.asciidoc b/docs/en/rest-api/ml/get-datafeed.asciidoc index a51aa3f5cbd..0f06bd0064e 100644 --- a/docs/en/rest-api/ml/get-datafeed.asciidoc +++ b/docs/en/rest-api/ml/get-datafeed.asciidoc @@ -7,18 +7,29 @@ The get {dfeeds} API enables you to retrieve configuration information for ==== Request + +`GET _xpack/ml/datafeeds/` + + +`GET _xpack/ml/datafeeds/,` + + `GET _xpack/ml/datafeeds/` + -`GET _xpack/ml/datafeeds/` +`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 +``, or by omitting 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 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]. -//<>. ==== Examples diff --git a/docs/en/rest-api/ml/get-job-stats.asciidoc b/docs/en/rest-api/ml/get-job-stats.asciidoc index 7bd477f0cba..ae9e8881803 100644 --- a/docs/en/rest-api/ml/get-job-stats.asciidoc +++ b/docs/en/rest-api/ml/get-job-stats.asciidoc @@ -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//_stats` -//===== Description +`GET _xpack/ml/anomaly_detectors/,/_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 +``, or by omitting the ``. + ==== 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]. -//<>. ==== Examples diff --git a/docs/en/rest-api/ml/get-job.asciidoc b/docs/en/rest-api/ml/get-job.asciidoc index 391fdd0d927..5ad036692e2 100644 --- a/docs/en/rest-api/ml/get-job.asciidoc +++ b/docs/en/rest-api/ml/get-job.asciidoc @@ -7,19 +7,29 @@ The get jobs API enables you to retrieve configuration information for jobs. ==== Request +`GET _xpack/ml/anomaly_detectors/` + + +`GET _xpack/ml/anomaly_detectors/,` + + `GET _xpack/ml/anomaly_detectors/` + -`GET _xpack/ml/anomaly_detectors/` +`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 +``, or by omitting the ``. -//===== 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]. -//<>. ==== Examples diff --git a/docs/en/rest-api/ml/stop-datafeed.asciidoc b/docs/en/rest-api/ml/stop-datafeed.asciidoc index 3a13a0f148b..0648559c939 100644 --- a/docs/en/rest-api/ml/stop-datafeed.asciidoc +++ b/docs/en/rest-api/ml/stop-datafeed.asciidoc @@ -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//_stop` +`POST _xpack/ml/datafeeds//_stop` + + +`POST _xpack/ml/datafeeds/,/_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 ``. -//===== 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]. -//<>. + ==== Examples