From 7c9c9a9cc4fb897a6b3a1a03528140c4151aefd9 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 6 Aug 2019 11:05:01 -0700 Subject: [PATCH] [DOCS] Reformats ML update APIs (#45253) --- .../high-level/ml/update-filter.asciidoc | 21 ++++---- .../high-level/ml/update-job.asciidoc | 52 +++++++++---------- .../ml/update-model-snapshot.asciidoc | 24 ++++----- .../apis/update-job.asciidoc | 12 ++--- .../apis/update-snapshot.asciidoc | 6 +-- .../apis/validate-detector.asciidoc | 6 +-- .../apis/validate-job.asciidoc | 8 +-- 7 files changed, 64 insertions(+), 65 deletions(-) diff --git a/docs/java-rest/high-level/ml/update-filter.asciidoc b/docs/java-rest/high-level/ml/update-filter.asciidoc index b100000ddc1..516ab597b6c 100644 --- a/docs/java-rest/high-level/ml/update-filter.asciidoc +++ b/docs/java-rest/high-level/ml/update-filter.asciidoc @@ -4,14 +4,13 @@ :response: PutFilterResponse -- [id="{upid}-{api}"] -=== Update Filter API +=== Update filter API -The Update Filter API can be used to update an existing {ml} filter -in the cluster. The API accepts a +{request}+ object -as a request and returns a +{response}+. +Updates an existing {ml} filter in the cluster. The API accepts a +{request}+ +object as a request and returns a +{response}+. [id="{upid}-{api}-request"] -==== Update Filter Request +==== Update filter request A +{request}+ requires the following argument: @@ -19,28 +18,28 @@ A +{request}+ requires the following argument: -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-request] -------------------------------------------------- -<1> The id of the existing {ml} filter +<1> The id of the existing {ml} filter. -==== Optional Arguments +==== Optional arguments The following arguments are optional: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-description] -------------------------------------------------- -<1> The updated description of the {ml} filter +<1> The updated description of the {ml} filter. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-add-items] -------------------------------------------------- -<1> The list of items to add to the {ml} filter +<1> The list of items to add to the {ml} filter. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-remove-items] -------------------------------------------------- -<1> The list of items to remove from the {ml} filter +<1> The list of items to remove from the {ml} filter. include::../execution.asciidoc[] @@ -54,4 +53,4 @@ the updated {ml} filter if it has been successfully updated. -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-response] -------------------------------------------------- -<1> The updated `MlFilter` +<1> The updated `MlFilter`. diff --git a/docs/java-rest/high-level/ml/update-job.asciidoc b/docs/java-rest/high-level/ml/update-job.asciidoc index 90f9cf85c48..d9d47acaab7 100644 --- a/docs/java-rest/high-level/ml/update-job.asciidoc +++ b/docs/java-rest/high-level/ml/update-job.asciidoc @@ -4,14 +4,13 @@ :response: PutJobResponse -- [id="{upid}-{api}"] -=== Update Job API +=== Update {anomaly-job} API -The Update Job API provides the ability to update a {ml} job. -It accepts a +{request}+ object and responds -with a +{response}+ object. +Provides the ability to update an {anomaly-job}. +It accepts a +{request}+ object and responds with a +{response}+ object. [id="{upid}-{api}-request"] -==== Update Job Request +==== Update {anomaly-job} request An +{request}+ object gets created with a `JobUpdate` object. @@ -19,43 +18,44 @@ An +{request}+ object gets created with a `JobUpdate` object. -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-request] -------------------------------------------------- -<1> Constructing a new request referencing a `JobUpdate` object +<1> Constructing a new request referencing a `JobUpdate` object. -==== Optional Arguments +==== Optional arguments -The `JobUpdate` object has many optional arguments with which to update an existing {ml} -job. An existing, non-null `jobId` must be referenced in its creation. +The `JobUpdate` object has many optional arguments with which to update an +existing {anomaly-job}. An existing, non-null `jobId` must be referenced in its +creation. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-options] -------------------------------------------------- -<1> Mandatory, non-null `jobId` referencing an existing {ml} job -<2> Updated description -<3> Updated analysis limits -<4> Updated background persistence interval -<5> Updated analysis config's categorization filters -<6> Updated detectors through the `JobUpdate.DetectorUpdate` object -<7> Updated group membership -<8> Updated result retention -<9> Updated model plot configuration -<10> Updated model snapshot retention setting -<11> Updated custom settings -<12> Updated renormalization window +<1> Mandatory, non-null `jobId` referencing an existing {anomaly-job}. +<2> Updated description. +<3> Updated analysis limits. +<4> Updated background persistence interval. +<5> Updated analysis config's categorization filters. +<6> Updated detectors through the `JobUpdate.DetectorUpdate` object. +<7> Updated group membership. +<8> Updated result retention. +<9> Updated model plot configuration. +<10> Updated model snapshot retention setting. +<11> Updated custom settings. +<12> Updated renormalization window. Included with these options are specific optional `JobUpdate.DetectorUpdate` updates. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-detector-options] -------------------------------------------------- -<1> The index of the detector. `O` means unknown -<2> The optional description of the detector -<3> The `DetectionRule` rules that apply to this detector +<1> The index of the detector. `O` means unknown. +<2> The optional description of the detector. +<3> The `DetectionRule` rules that apply to this detector. include::../execution.asciidoc[] [id="{upid}-{api}-response"] -==== Update Job Response +==== Update {anomaly-job} response A +{response}+ contains the updated `Job` object @@ -63,4 +63,4 @@ A +{response}+ contains the updated `Job` object -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-response] -------------------------------------------------- -<1> `getResponse()` returns the updated `Job` object +<1> `getResponse()` returns the updated `Job` object. diff --git a/docs/java-rest/high-level/ml/update-model-snapshot.asciidoc b/docs/java-rest/high-level/ml/update-model-snapshot.asciidoc index b38539b0622..ec845b22137 100644 --- a/docs/java-rest/high-level/ml/update-model-snapshot.asciidoc +++ b/docs/java-rest/high-level/ml/update-model-snapshot.asciidoc @@ -4,14 +4,13 @@ :response: UpdateModelSnapshotResponse -- [id="{upid}-{api}"] -=== Update Model Snapshot API +=== Update model snapshot API -The Update Model Snapshot API provides the ability to update a {ml} model snapshot. -It accepts a +{request}+ object and responds -with a +{response}+ object. +Provides the ability to update a {ml} model snapshot. +It accepts a +{request}+ object and responds with a +{response}+ object. [id="{upid}-{api}-request"] -==== Update Model Snapshot Request +==== Update model snapshot request A +{request}+ requires the following arguments: @@ -19,9 +18,10 @@ A +{request}+ requires the following arguments: -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-request] -------------------------------------------------- -<1> Constructing a new request referencing existing `jobId` and `snapshotId` values. +<1> Constructing a new request referencing existing `jobId` and `snapshotId` +values. -==== Optional Arguments +==== Optional arguments The following arguments are optional: @@ -29,19 +29,19 @@ The following arguments are optional: -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-description] -------------------------------------------------- -<1> The updated description of the {ml} model snapshot +<1> The updated description of the {ml} model snapshot. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-retain] -------------------------------------------------- -<1> The updated `retain` property of the {ml} model snapshot +<1> The updated `retain` property of the {ml} model snapshot. include::../execution.asciidoc[] [id="{upid}-{api}-response"] -==== Update Job Response +==== Update model snapshot response A +{response}+ contains an acknowledgement of the update request and the full representation of the updated `ModelSnapshot` object @@ -49,5 +49,5 @@ A +{response}+ contains an acknowledgement of the update request and the full re -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-response] -------------------------------------------------- -<1> An acknowledgement of the request -<2> The updated `ModelSnapshot` +<1> An acknowledgement of the request. +<2> The updated `ModelSnapshot`. diff --git a/docs/reference/ml/anomaly-detection/apis/update-job.asciidoc b/docs/reference/ml/anomaly-detection/apis/update-job.asciidoc index 9dfb833ec9b..7098ba1ebbc 100644 --- a/docs/reference/ml/anomaly-detection/apis/update-job.asciidoc +++ b/docs/reference/ml/anomaly-detection/apis/update-job.asciidoc @@ -1,12 +1,12 @@ [role="xpack"] [testenv="platinum"] [[ml-update-job]] -=== Update jobs API +=== Update {anomaly-jobs} API ++++ Update jobs ++++ -Updates certain properties of a job. +Updates certain properties of an {anomaly-job}. [[ml-update-job-request]] ==== {api-request-title} @@ -25,7 +25,7 @@ Updates certain properties of a job. ==== {api-path-parms-title} ``:: - (Required, string) Identifier for the job. + (Required, string) Identifier for the {anomaly-job}. [[ml-update-job-request-body]] ==== {api-request-body-title} @@ -81,7 +81,7 @@ want to re-run this job with an increased `model_memory_limit`. -- [[ml-detector-update]] -==== Detector Update Objects +==== Detector update objects A detector update object has the following properties: @@ -128,8 +128,8 @@ POST _ml/anomaly_detectors/total-requests/_update // CONSOLE // TEST[skip:setup:server_metrics_job] -When the job is updated, you receive a summary of the job configuration -information, including the updated property values. For example: +When the {anomaly-job} is updated, you receive a summary of the job +configuration information, including the updated property values. For example: [source,js] ---- diff --git a/docs/reference/ml/anomaly-detection/apis/update-snapshot.asciidoc b/docs/reference/ml/anomaly-detection/apis/update-snapshot.asciidoc index 36e3e5e82f6..90438439de0 100644 --- a/docs/reference/ml/anomaly-detection/apis/update-snapshot.asciidoc +++ b/docs/reference/ml/anomaly-detection/apis/update-snapshot.asciidoc @@ -25,7 +25,7 @@ Updates certain properties of a snapshot. ==== {api-path-parms-title} ``:: - (Required, string) Identifier for the job. + (Required, string) Identifier for the {anomaly-job}. ``:: (Required, string) Identifier for the model snapshot. @@ -42,8 +42,8 @@ The following properties can be updated after the model snapshot is created: `retain`:: (Optional, boolean) If true, this snapshot will not be deleted during automatic cleanup of snapshots older than `model_snapshot_retention_days`. - Note that this snapshot will still be deleted when the job is deleted. - The default value is false. + Note that this snapshot will still be deleted when the {anomaly-job} is + deleted. The default value is false. [[ml-update-snapshot-example]] ==== {api-examples-title} diff --git a/docs/reference/ml/anomaly-detection/apis/validate-detector.asciidoc b/docs/reference/ml/anomaly-detection/apis/validate-detector.asciidoc index 2e5896b95cc..b1efc4dcb3b 100644 --- a/docs/reference/ml/anomaly-detection/apis/validate-detector.asciidoc +++ b/docs/reference/ml/anomaly-detection/apis/validate-detector.asciidoc @@ -3,7 +3,7 @@ [[ml-valid-detector]] === Validate detectors API ++++ -Validate detectors +Validate detectors ++++ Validates detector configuration information. @@ -23,8 +23,8 @@ Validates detector configuration information. [[ml-valid-detector-desc]] ==== {api-description-title} -The validate detectors API enables you validate the detector configuration -before you create a job. +This API enables you validate the detector configuration +before you create an {anomaly-job}. [[ml-valid-detector-request-body]] ==== {api-request-body-title} diff --git a/docs/reference/ml/anomaly-detection/apis/validate-job.asciidoc b/docs/reference/ml/anomaly-detection/apis/validate-job.asciidoc index faa7cab2f39..0d1ece9cf82 100644 --- a/docs/reference/ml/anomaly-detection/apis/validate-job.asciidoc +++ b/docs/reference/ml/anomaly-detection/apis/validate-job.asciidoc @@ -1,12 +1,12 @@ [role="xpack"] [testenv="platinum"] [[ml-valid-job]] -=== Validate jobs API +=== Validate {anomaly-jobs} API ++++ Validate jobs ++++ -Validates job configuration information. +Validates {anomaly-job} configuration information. [[ml-valid-job-request]] ==== {api-request-title} @@ -23,14 +23,14 @@ Validates job configuration information. [[ml-valid-job-desc]] ==== {api-description-title} -The validate jobs API enables you validate the job configuration before you +This API enables you validate the {anomaly-job} configuration before you create the job. [[ml-valid-job-request-body]] ==== {api-request-body-title} For a list of the properties that you can specify in the body of this API, -see <>. +see <>. [[ml-valid-job-example]] ==== {api-examples-title}