[DOCS] Move anomaly detection job resource definitions into APIs (#49700) (#50513)

Author: lcawl

docs/build.gradle

@@ -29,6 +29,7 @@ buildRestTests.expectedUnconvertedCandidates = [
         'reference/ml/anomaly-detection/apis/get-category.asciidoc',
         'reference/ml/anomaly-detection/apis/get-influencer.asciidoc',
         'reference/ml/anomaly-detection/apis/get-job-stats.asciidoc',
+        'reference/ml/anomaly-detection/apis/get-job.asciidoc',
         'reference/ml/anomaly-detection/apis/get-overall-buckets.asciidoc',
         'reference/ml/anomaly-detection/apis/get-record.asciidoc',
         'reference/ml/anomaly-detection/apis/get-snapshot.asciidoc',

docs/reference/ml/anomaly-detection/apis/close-job.asciidoc

@@ -60,33 +60,23 @@ results the job might have recently produced or might produce in the future.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the {anomaly-job}. It can be a job
-  identifier, a group name, or a wildcard expression.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection-wildcard]
 
 [[ml-close-job-query-parms]]
 ==== {api-query-parms-title}
 
 `allow_no_jobs`::
-  (Optional, boolean) Specifies what to do when the request:
-+
---
-* Contains wildcard expressions and there are no jobs that match.
-* Contains the `_all` string or no identifiers and there are no matches.
-* Contains wildcard expressions and there are only partial matches.
-
-The default value is `true`, which returns an empty `jobs` array 
-when there are no matches and the subset of results when there are partial 
-matches. If this parameter is `false`, the request returns a `404` status code
-when there are no matches or only partial matches.
---
+(Optional, boolean)
+include::{docdir}/ml/ml-shared.asciidoc[tag=allow-no-jobs]
 
 `force`::
-  (Optional, boolean) Use to close a failed job, or to forcefully close a job
-  which has not responded to its initial close request.
+(Optional, boolean) Use to close a failed job, or to forcefully close a job
+which has not responded to its initial close request.
 
 `timeout`::
-  (Optional, <<time-units, time units>>) Controls the time to wait until a job 
-  has closed. The default value is 30 minutes.
+(Optional, <<time-units, time units>>) Controls the time to wait until a job 
+has closed. The default value is 30 minutes.
 
 [[ml-close-job-response-codes]]
 ==== {api-response-codes-title}

docs/reference/ml/anomaly-detection/apis/datafeedresource.asciidoc

@@ -50,7 +50,7 @@ A {dfeed} resource has the following properties:
 `script_fields`::
   (object) Specifies scripts that evaluate custom expressions and returns
   script fields to the {dfeed}.
-  The <<ml-detectorconfig,detector configuration objects>> in a job can contain
+  The detector configuration objects in a job can contain
   functions that use these script fields.
   For more information, see
   {ml-docs}/ml-configuring-transform.html[Transforming data with script fields].

docs/reference/ml/anomaly-detection/apis/delete-job.asciidoc

@@ -39,18 +39,19 @@ separated list.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the {anomaly-job}.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 [[ml-delete-job-query-parms]]
 ==== {api-query-parms-title}
 
 `force`::
-  (Optional, boolean) Use to forcefully delete an opened job; this method is
-  quicker than closing and deleting the job.
+(Optional, boolean) Use to forcefully delete an opened job; this method is
+quicker than closing and deleting the job.
 
 `wait_for_completion`::
-  (Optional, boolean) Specifies whether the request should return immediately or
-  wait until the job deletion completes. Defaults to `true`.
+(Optional, boolean) Specifies whether the request should return immediately or
+wait until the job deletion completes. Defaults to `true`.
 
 [[ml-delete-job-example]]
 ==== {api-examples-title}

docs/reference/ml/anomaly-detection/apis/flush-job.asciidoc

@@ -37,7 +37,8 @@ opened again before analyzing further data.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-(string) Required. Identifier for the job.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 [[ml-flush-job-query-parms]]
 ==== {api-query-parms-title}

docs/reference/ml/anomaly-detection/apis/forecast.asciidoc

@@ -29,15 +29,16 @@ See {ml-docs}/ml-overview.html#ml-forecasting[Forecasting the future].
 ===============================
 
 * If you use an `over_field_name` property in your job, you cannot create a
-forecast. For more information about this property, see <<ml-job-resource>>.
+forecast. For more information about this property, see <<ml-put-job>>.
 * The job must be open when you create a forecast. Otherwise, an error occurs.
 ===============================
 
 [[ml-forecast-path-parms]]
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the job.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 [[ml-forecast-request-body]]
 ==== {api-request-body-title}

docs/reference/ml/anomaly-detection/apis/get-bucket.asciidoc

@@ -36,7 +36,8 @@ bucket.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the {anomaly-job}.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 `<timestamp>`::
   (Optional, string) The timestamp of a single bucket result. If you do not

docs/reference/ml/anomaly-detection/apis/get-category.asciidoc

@@ -35,7 +35,8 @@ For more information about categories, see
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the {anomaly-job}.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 `<category_id>`::
   (Optional, long) Identifier for the category. If you do not specify this

docs/reference/ml/anomaly-detection/apis/get-influencer.asciidoc

@@ -27,7 +27,8 @@ privileges. See <<security-privileges>> and
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the {anomaly-job}.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 [[ml-get-influencer-request-body]]
 ==== {api-request-body-title}

docs/reference/ml/anomaly-detection/apis/get-job-stats.asciidoc

@@ -40,26 +40,15 @@ IMPORTANT: This API returns a maximum of 10,000 jobs.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Optional, string) An identifier for the {anomaly-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 {anomaly-jobs}.
+(Optional, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection-default]
 
 [[ml-get-job-stats-query-parms]]
 ==== {api-query-parms-title}
 
 `allow_no_jobs`::
-  (Optional, boolean) Specifies what to do when the request:
-+
---
-* Contains wildcard expressions and there are no jobs that match.
-* Contains the `_all` string or no identifiers and there are no matches.
-* Contains wildcard expressions and there are only partial matches.
-
-The default value is `true`, which returns an empty `jobs` array 
-when there are no matches and the subset of results when there are partial 
-matches. If this parameter is `false`, the request returns a `404` status code
-when there are no matches or only partial matches.
---
+(Optional, boolean)
+include::{docdir}/ml/ml-shared.asciidoc[tag=allow-no-jobs]
 
 [[ml-get-job-stats-results]]
 ==== {api-response-body-title}
@@ -68,7 +57,6 @@ The API returns the following information:
 
 `jobs`::
   (array) An array of {anomaly-job} statistics objects.
-  For more information, see <<ml-jobstats>>.
 
 [[ml-get-job-stats-response-codes]]
 ==== {api-response-codes-title}

docs/reference/ml/anomaly-detection/apis/get-job.asciidoc

@@ -40,35 +40,40 @@ IMPORTANT: This API returns a maximum of 10,000 jobs.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Optional, string) Identifier for the {anomaly-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 {anomaly-jobs}.
+(Optional, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection-default]
 
 [[ml-get-job-query-parms]]
 ==== {api-query-parms-title}
 
 `allow_no_jobs`::
-  (Optional, boolean) Specifies what to do when the request:
-+
---
-* Contains wildcard expressions and there are no jobs that match.
-* Contains the `_all` string or no identifiers and there are no matches.
-* Contains wildcard expressions and there are only partial matches.
-
-The default value is `true`, which returns an empty `jobs` array 
-when there are no matches and the subset of results when there are partial 
-matches. If this parameter is `false`, the request returns a `404` status code
-when there are no matches or only partial matches.
---
+(Optional, boolean)
+include::{docdir}/ml/ml-shared.asciidoc[tag=allow-no-jobs]
 
 [[ml-get-job-results]]
 ==== {api-response-body-title}
 
-The API returns the following information:
+The API returns an array of {anomaly-job} resources. For the full list of
+properties, see <<ml-put-job-request-body,create {anomaly-jobs} API>>.
 
-`jobs`::
-  (array) An array of {anomaly-job} resources.
-  For more information, see <<ml-job-resource>>.
+`create_time`::
+(string) The time the job was created. For example, `1491007356077`. This
+property is informational; you cannot change its value.
+  
+`finished_time`::
+(string) If the job closed or failed, this is the time the job finished.
+Otherwise, it is `null`. This property is informational; you cannot change its
+value.
+
+`job_type`::
+(string) Reserved for future use, currently set to `anomaly_detector`.
+
+`job_version`::
+(string) The version of {es} that existed on the node when the job was created.
+
+`model_snapshot_id`::
+(string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=model-snapshot-id]
 
 [[ml-get-job-response-codes]]
 ==== {api-response-codes-title}
@@ -80,53 +85,65 @@ The API returns the following information:
 [[ml-get-job-example]]
 ==== {api-examples-title}
 
-The following example gets configuration information for the `total-requests` job:
-
 [source,console]
 --------------------------------------------------
-GET _ml/anomaly_detectors/total-requests
+GET _ml/anomaly_detectors/high_sum_total_sales
 --------------------------------------------------
-// TEST[skip:setup:server_metrics_job]
+// TEST[skip:Kibana sample data]
 
 The API returns the following results:
 
-[source,console-result]
+[source,js]
 ----
 {
   "count": 1,
   "jobs": [
     {
-      "job_id": "total-requests",
-      "job_type": "anomaly_detector",
-      "job_version": "7.0.0-alpha1",
-      "description": "Total sum of requests",
-      "create_time": 1517011406091,
-      "analysis_config": {
-        "bucket_span": "10m",
-        "detectors": [
+      "job_id" : "high_sum_total_sales",
+      "job_type" : "anomaly_detector",
+      "job_version" : "7.5.0",
+      "groups" : [
+        "kibana_sample_data",
+        "kibana_sample_ecommerce"
+      ],
+      "description" : "Find customers spending an unusually high amount in an hour",
+      "create_time" : 1577221534700,
+      "analysis_config" : {
+        "bucket_span" : "1h",
+        "detectors" : [
           {
-            "detector_description": "Sum of total",
-            "function": "sum",
-            "field_name": "total",
-            "detector_index": 0
+            "detector_description" : "High total sales",
+            "function" : "high_sum",
+            "field_name" : "taxful_total_price",
+            "over_field_name" : "customer_full_name.keyword",
+            "detector_index" : 0
           }
         ],
-        "influencers": [ ]
+        "influencers" : [
+          "customer_full_name.keyword",
+          "category.keyword"
+        ]
+      },
+      "analysis_limits" : {
+        "model_memory_limit" : "10mb",
+        "categorization_examples_limit" : 4
+      },
+      "data_description" : {
+        "time_field" : "order_date",
+        "time_format" : "epoch_ms"
       },
-      "analysis_limits": {
-        "model_memory_limit": "1024mb",
-        "categorization_examples_limit": 4
+      "model_plot_config" : {
+        "enabled" : true
       },
-      "data_description": {
-        "time_field": "timestamp",
-        "time_format": "epoch_ms"
+      "model_snapshot_retention_days" : 1,
+      "custom_settings" : {
+        "created_by" : "ml-module-sample",
+        ...
       },
-      "model_snapshot_retention_days": 1,
-      "results_index_name": "shared",
-      "allow_lazy_open": false
+      "model_snapshot_id" : "1575402237",
+      "results_index_name" : "shared",
+      "allow_lazy_open" : false
     }
   ]
 }
 ----
-// TESTRESPONSE[s/"7.0.0-alpha1"/$body.$_path/]
-// TESTRESPONSE[s/1517011406091/$body.$_path/]

docs/reference/ml/anomaly-detection/apis/get-overall-buckets.asciidoc

@@ -55,16 +55,15 @@ a span equal to the jobs' largest bucket span.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the {anomaly-job}. It can be a job
-  identifier, a group name, a comma-separated list of jobs or groups, or a
-  wildcard expression.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection-wildcard-list]
 
 [[ml-get-overall-buckets-request-body]]
 ==== {api-request-body-title}
 
 `allow_no_jobs`::
-  (Optional, boolean) If `false` and the `job_id` does not match any
-  {anomaly-jobs}, an error occurs. The default value is `true`.
+(Optional, boolean)
+include::{docdir}/ml/ml-shared.asciidoc[tag=allow-no-jobs]
 
 `bucket_span`::
   (Optional, string) The span of the overall buckets. Must be greater or equal

docs/reference/ml/anomaly-detection/apis/get-record.asciidoc

@@ -26,7 +26,8 @@ privileges. See <<security-privileges>> and <<built-in-roles>>.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the {anomaly-job}.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 [[ml-get-record-request-body]]
 ==== {api-request-body-title}

docs/reference/ml/anomaly-detection/apis/get-snapshot.asciidoc

@@ -26,7 +26,8 @@ Retrieves information about model snapshots.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the {anomaly-job}.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 `<snapshot_id>`::
   (Optional, string) Identifier for the model snapshot. If you do not specify