From a79adca7e3774058b83d11a3ef7d6885c5c6ffd0 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Thu, 25 Jul 2019 08:58:16 -0700 Subject: [PATCH] [DOCS] Updates terms in anomaly detection job APIs (#44839) --- .../high-level/ml/close-job.asciidoc | 10 +++----- .../high-level/ml/delete-job.asciidoc | 25 +++++++++++-------- .../java-rest/high-level/ml/open-job.asciidoc | 11 ++++---- docs/java-rest/high-level/ml/put-job.asciidoc | 19 +++++++------- .../anomaly-detection/apis/close-job.asciidoc | 14 +++++------ .../apis/delete-job.asciidoc | 14 +++++------ .../anomaly-detection/apis/open-job.asciidoc | 11 ++++---- .../anomaly-detection/apis/put-job.asciidoc | 4 +-- 8 files changed, 54 insertions(+), 54 deletions(-) diff --git a/docs/java-rest/high-level/ml/close-job.asciidoc b/docs/java-rest/high-level/ml/close-job.asciidoc index 8a38b498629..bf14fa0f21a 100644 --- a/docs/java-rest/high-level/ml/close-job.asciidoc +++ b/docs/java-rest/high-level/ml/close-job.asciidoc @@ -4,14 +4,12 @@ :response: CloseJobResponse -- [id="{upid}-{api}"] -=== Close Job API +=== Close {anomaly-job} API -The Close Job API provides the ability to close {ml} jobs in the cluster. -It accepts a +{request}+ object and responds -with a +{response}+ object. +Closes {anomaly-jobs} in the cluster. It accepts a +{request}+ object and responds with a +{response}+ object. [id="{upid}-{api}-request"] -==== Close Job Request +==== Close {anomaly-job} request A +{request}+ object gets created with an existing non-null `jobId`. @@ -28,7 +26,7 @@ which has not responded to its initial close request. execution should wait for the job to be closed. [id="{upid}-{api}-response"] -==== Close Job Response +==== Close {anomaly-job} response ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- diff --git a/docs/java-rest/high-level/ml/delete-job.asciidoc b/docs/java-rest/high-level/ml/delete-job.asciidoc index a8c6b276dd4..06c82c0a112 100644 --- a/docs/java-rest/high-level/ml/delete-job.asciidoc +++ b/docs/java-rest/high-level/ml/delete-job.asciidoc @@ -4,10 +4,12 @@ :response: AcknowledgedResponse -- [id="{upid}-{api}"] -=== Delete Job API +=== Delete {anomaly-job} API + +Deletes an {anomaly-job} that exists in the cluster. [id="{upid}-{api}-request"] -==== Delete Job Request +==== Delete {anomaly-job} request A +{request}+ object requires a non-null `jobId` and can optionally set `force`. @@ -17,7 +19,7 @@ include-tagged::{doc-tests-file}[{api}-request] --------------------------------------------------- <1> Constructing a new request referencing an existing `jobId` -==== Optional Arguments +==== Optional arguments The following arguments are optional: @@ -33,21 +35,24 @@ Defaults to `false`. --------------------------------------------------- include-tagged::{doc-tests-file}[{api}-request-wait-for-completion] --------------------------------------------------- -<1> Use to set whether the request should wait until the operation has completed before returning. -Defaults to `true`. +<1> Use to set whether the request should wait until the operation has completed +before returning. Defaults to `true`. [id="{upid}-{api}-response"] -==== Delete Job Response +==== Delete {anomaly-job} response -The returned +{response}+ object indicates the acknowledgement of the job deletion or -the deletion task depending on whether the request was set to wait for completion: +The returned +{response}+ object indicates the acknowledgement of the job +deletion or the deletion task depending on whether the request was set to wait +for completion: ["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- include-tagged::{doc-tests-file}[{api}-response] --------------------------------------------------- -<1> whether was job deletion was acknowledged or not; will be `null` when set not to wait for completion -<2> the id of the job deletion task; will be `null` when set to wait for completion +<1> whether was job deletion was acknowledged or not; will be `null` when set +not to wait for completion +<2> the id of the job deletion task; will be `null` when set to wait for +completion include::../execution.asciidoc[] diff --git a/docs/java-rest/high-level/ml/open-job.asciidoc b/docs/java-rest/high-level/ml/open-job.asciidoc index 9b3ec11a7cc..b6f4e8ed1eb 100644 --- a/docs/java-rest/high-level/ml/open-job.asciidoc +++ b/docs/java-rest/high-level/ml/open-job.asciidoc @@ -4,14 +4,13 @@ :response: OpenJobResponse -- [id="{upid}-{api}"] -=== Open Job API +=== Open {anomaly-job} API -The Open Job API provides the ability to open {ml} jobs in the cluster. -It accepts a +{request}+ object and responds -with a +{response}+ object. +Opens {anomaly-jobs} in the cluster. It accepts a +{request}+ object and +responds with a +{response}+ object. [id="{upid}-{api}-request"] -==== Open Job Request +==== Open {anomaly-job} request An +{request}+ object gets created with an existing non-null `jobId`. @@ -24,7 +23,7 @@ include-tagged::{doc-tests-file}[{api}-request] execution should wait for the job to be opened. [id="{upid}-{api}-response"] -==== Open Job Response +==== Open {anomaly-job} response ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- diff --git a/docs/java-rest/high-level/ml/put-job.asciidoc b/docs/java-rest/high-level/ml/put-job.asciidoc index 9934fc6b94a..081c94782fa 100644 --- a/docs/java-rest/high-level/ml/put-job.asciidoc +++ b/docs/java-rest/high-level/ml/put-job.asciidoc @@ -4,14 +4,13 @@ :response: PutJobResponse -- [id="{upid}-{api}"] -=== Put Job API +=== Put {anomaly-job} API -The Put Job API can be used to create a new {ml} job -in the cluster. The API accepts a +{request}+ object +Creates a new {anomaly-job} in the cluster. The API accepts a +{request}+ object as a request and returns a +{response}+. [id="{upid}-{api}-request"] -==== Put Job Request +==== Put {anomaly-job} request A +{request}+ requires the following argument: @@ -19,12 +18,12 @@ A +{request}+ requires the following argument: -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-request] -------------------------------------------------- -<1> The configuration of the {ml} job to create as a `Job` +<1> The configuration of the {anomaly-job} to create as a `Job` [id="{upid}-{api}-config"] -==== Job Configuration +==== Job configuration -The `Job` object contains all the details about the {ml} job +The `Job` object contains all the details about the {anomaly-job} configuration. A `Job` requires the following arguments: @@ -39,9 +38,9 @@ include-tagged::{doc-tests-file}[{api}-config] <4> Optionally, a human-readable description [id="{upid}-{api}-analysis-config"] -==== Analysis Configuration +==== Analysis configuration -The analysis configuration of the {ml} job is defined in the `AnalysisConfig`. +The analysis configuration of the {anomaly-job} is defined in the `AnalysisConfig`. `AnalysisConfig` reflects all the configuration settings that can be defined using the REST API. @@ -86,7 +85,7 @@ include-tagged::{doc-tests-file}[{api}-analysis-config] <3> The bucket span [id="{upid}-{api}-data-description"] -==== Data Description +==== Data description After defining the analysis config, the next thing to define is the data description, using a `DataDescription` instance. `DataDescription` diff --git a/docs/reference/ml/anomaly-detection/apis/close-job.asciidoc b/docs/reference/ml/anomaly-detection/apis/close-job.asciidoc index de64754b098..4bdabd3ce91 100644 --- a/docs/reference/ml/anomaly-detection/apis/close-job.asciidoc +++ b/docs/reference/ml/anomaly-detection/apis/close-job.asciidoc @@ -1,12 +1,12 @@ [role="xpack"] [testenv="platinum"] [[ml-close-job]] -=== Close jobs API +=== Close {anomaly-jobs} API ++++ Close jobs ++++ -Closes one or more jobs. +Closes one or more {anomaly-jobs}. A job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis @@ -31,9 +31,9 @@ operations, but you can still explore and navigate results. [[ml-close-job-desc]] ==== {api-description-title} -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 ``. +You can close multiple {anomaly-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. @@ -58,8 +58,8 @@ results the job might have recently produced or might produce in the future. ==== {api-path-parms-title} ``:: - (Required, string) Identifier for the job. It can be a job identifier, a group - name, or a wildcard expression. + (Required, string) Identifier for the {anomaly-job}. It can be a job + identifier, a group name, or a wildcard expression. [[ml-close-job-query-parms]] ==== {api-query-parms-title} diff --git a/docs/reference/ml/anomaly-detection/apis/delete-job.asciidoc b/docs/reference/ml/anomaly-detection/apis/delete-job.asciidoc index bd5a74e50e8..506e224f943 100644 --- a/docs/reference/ml/anomaly-detection/apis/delete-job.asciidoc +++ b/docs/reference/ml/anomaly-detection/apis/delete-job.asciidoc @@ -1,12 +1,12 @@ [role="xpack"] [testenv="platinum"] [[ml-delete-job]] -=== Delete jobs API +=== Delete {anomaly-jobs} API ++++ Delete jobs ++++ -Deletes an existing anomaly detection job. +Deletes an existing {anomaly-job}. [[ml-delete-job-request]] ==== {api-request-title} @@ -25,14 +25,14 @@ cluster privileges to use this API. See All job configuration, model state and results are deleted. -IMPORTANT: Deleting a job must be done via this API only. Do not delete the -job directly from the `.ml-*` indices using the Elasticsearch delete document +IMPORTANT: Deleting an {anomaly-job} must be done via this API only. Do not +delete the job directly from the `.ml-*` indices using the {es} delete document API. When {es} {security-features} are enabled, make sure no `write` privileges are granted to anyone over the `.ml-*` indices. Before you can delete a job, you must delete the {dfeeds} that are associated -with it. See <>. Unless the `force` parameter -is used the job must be closed before it can be deleted. +with it. See <>. Unless the `force` +parameter is used the job must be closed before it can be deleted. It is not currently possible to delete multiple jobs using wildcards or a comma separated list. @@ -41,7 +41,7 @@ separated list. ==== {api-path-parms-title} ``:: - (Required, string) Identifier for the job. + (Required, string) Identifier for the {anomaly-job}. [[ml-delete-job-query-parms]] ==== {api-query-parms-title} diff --git a/docs/reference/ml/anomaly-detection/apis/open-job.asciidoc b/docs/reference/ml/anomaly-detection/apis/open-job.asciidoc index 23ccd1586ed..8761bf83428 100644 --- a/docs/reference/ml/anomaly-detection/apis/open-job.asciidoc +++ b/docs/reference/ml/anomaly-detection/apis/open-job.asciidoc @@ -1,12 +1,12 @@ [role="xpack"] [testenv="platinum"] [[ml-open-job]] -=== Open jobs API +=== Open {anomaly-jobs} API ++++ Open jobs ++++ -Opens one or more jobs. +Opens one or more {anomaly-jobs}. [[ml-open-job-request]] ==== {api-request-title} @@ -23,8 +23,9 @@ Opens one or more jobs. [[ml-open-job-desc]] ==== {api-description-title} -A job must be opened in order for it to be ready to receive and analyze data. -A job can be opened and closed multiple times throughout its lifecycle. +An {anomaly-job} must be opened in order for it to be ready to receive and +analyze data. It can be opened and closed multiple times throughout its +lifecycle. When you open a new job, it starts with an empty model. @@ -36,7 +37,7 @@ data is received. ==== {api-path-parms-title} ``:: - (Required, string) Identifier for the job + (Required, string) Identifier for the {anomaly-job}. [[ml-open-job-request-body]] ==== {api-request-body-title} diff --git a/docs/reference/ml/anomaly-detection/apis/put-job.asciidoc b/docs/reference/ml/anomaly-detection/apis/put-job.asciidoc index 3d1f309b673..ade033f83ee 100644 --- a/docs/reference/ml/anomaly-detection/apis/put-job.asciidoc +++ b/docs/reference/ml/anomaly-detection/apis/put-job.asciidoc @@ -2,10 +2,8 @@ [testenv="platinum"] [[ml-put-job]] === Create {anomaly-jobs} API - -[subs="attributes"] ++++ -Create {anomaly-jobs} +Create jobs ++++ Instantiates an {anomaly-job}.