[DOCS] Add authorization info to create, get, and update DFA jobs APIs (#88098)

docs/build.gradle

@@ -1557,6 +1557,15 @@ setups['simple_kibana_continuous_pivot'] = setups['kibana_sample_data_ecommerce'
             }
           }
 '''
+setups['setup_houseprices'] = '''
+  - do:
+        indices.create:
+          index: houses_sold_last_10_yrs
+          body:
+            settings:
+              number_of_shards: 1
+              number_of_replicas: 1
+'''
 setups['setup_logdata'] = '''
   - do:
         indices.create:

docs/reference/ml/df-analytics/apis/get-dfanalytics.asciidoc

@@ -1,4 +1,3 @@
-[role="xpack"]
 [[get-dfanalytics]]
 = Get {dfanalytics-jobs} API
 [subs="attributes"]
@@ -56,6 +55,10 @@ You can get information for all {dfanalytics-jobs} by using _all, by specifying
 (Optional, Boolean)
 include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=allow-no-match-dfa-jobs]
 
+`exclude_generated`::
+(Optional, Boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=exclude-generated]
+
 `from`::
 (Optional, integer)
 include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=from]
@@ -64,10 +67,6 @@ include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=from]
 (Optional, integer)
 include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=size]
 
-`exclude_generated`::
-(Optional, Boolean)
-include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=exclude-generated]
-
 [role="child_attributes"]
 [[ml-get-dfanalytics-results]]
 == {api-response-body-title}
@@ -100,6 +99,39 @@ from the analysis.
 in the analysis.
 =====
 //End analyzed_fields
+//Begin authorization
+`authorization`:::
+(object)
+The security privileges that the job uses to run its queries. If
+{stack-security-features} were disabled at the time of the most recent update to
+the job, this property is omitted.
++
+.Properties of `authorization`
+[%collapsible%open]
+=====
+`api_key`:::
+(object) If an API key was used for the most recent update to the job, its name
+and identifier are listed in the response.
++
+.Properties of `api_key`
+[%collapsible%open]
+======
+`id`::::
+(string) The identifier for the API key.
+
+`name`::::
+(string) The name of the API key.
+======
+
+`roles`:::
+(array of strings) If a user ID was used for the most recent update to the job,
+its roles at the time of the update are listed in the response.
+
+`service_account`:::
+(string) If a service account was used for the most recent update to the job,
+the account name is listed in the response.
+=====
+//End authorization
 //Begin dest
 `dest`:::
 (string) The destination configuration of the analysis.
@@ -187,26 +219,40 @@ The API returns the following results:
 [source,console-result]
 ----
 {
-  "count": 1,
-  "data_frame_analytics": [
+  "count" : 1,
+  "data_frame_analytics" : [
     {
-      "id": "loganalytics",
-      "source": {
-        "index": "logdata",
-        "query": {
-          "match_all": {}
+      "id" : "loganalytics",
+      "create_time" : 1656364565517,
+      "version" : "8.4.0",
+      "authorization" : {
+        "roles" : [
+          "superuser"
+        ]
+      },
+      "description" : "Outlier detection on log data",
+      "source" : {
+        "index" : [
+          "logdata"
+        ],
+        "query" : {
+          "match_all" : { }
         }
       },
-      "dest": {
-        "index": "logdata_out",
-        "results_field": "ml"
+      "dest" : {
+        "index" : "logdata_out",
+        "results_field" : "ml"
       },
-      "analysis": {
-        "outlier_detection": {}
+      "analysis" : {
+        "outlier_detection" : {
+          "compute_feature_influence" : true,
+          "outlier_fraction" : 0.05,
+          "standardization_enabled" : true
+        }
       },
-      "model_memory_limit": "1gb",
-      "create_time": 1562265491319,
-      "version": "8.0.0"
+      "model_memory_limit" : "1gb",
+      "allow_lazy_start" : false,
+      "max_num_threads" : 1
     }
   ]
 }

docs/reference/ml/df-analytics/apis/put-dfanalytics.asciidoc

@@ -664,34 +664,43 @@ The API returns the following result:
 [source,console-result]
 ----
 {
-  "id": "loganalytics",
-  "description": "Outlier detection on log data",
-  "source": {
-    "index": [ "logdata" ],
-    "query": {
-      "match_all": {}
+  "id" : "loganalytics",
+  "create_time" : 1656364565517,
+  "version" : "8.4.0",
+  "authorization" : {
+    "roles" : [
+      "superuser"
+    ]
+  },
+  "description" : "Outlier detection on log data",
+  "source" : {
+    "index" : [
+      "logdata"
+    ],
+    "query" : {
+      "match_all" : { }
     }
   },
-  "dest": {
-    "index": "logdata_out",
-    "results_field": "ml"
+  "dest" : {
+    "index" : "logdata_out",
+    "results_field" : "ml"
   },
-  "analysis": {
-    "outlier_detection": {
-      "compute_feature_influence": true,
-      "outlier_fraction": 0.05,
-      "standardization_enabled": true
+  "analysis" : {
+    "outlier_detection" : {
+      "compute_feature_influence" : true,
+      "outlier_fraction" : 0.05,
+      "standardization_enabled" : true
     }
   },
-  "model_memory_limit": "1gb",
-  "create_time": 1562265491319,
-  "version": "8.0.0",
-  "allow_lazy_start": false,
-  "max_num_threads": 1
+  "model_memory_limit" : "1gb",
+  "allow_lazy_start" : false,
+  "max_num_threads" : 1
 }
+
 ----
-// TESTRESPONSE[s/1562265491319/$body.$_path/]
-// TESTRESPONSE[s/"version": "8.0.0"/"version": $body.version/]
+// TESTRESPONSE[s/1656364565517/$body.$_path/]
+// TESTRESPONSE[s/"version": "8.4.0"/"version": $body.version/]
+// TESTRESPONSE[s/"authorization" : \{[^}]*\},//]
 
 
 [[ml-put-dfanalytics-example-r]]
@@ -718,7 +727,7 @@ PUT _ml/data_frame/analytics/house_price_regression_analysis
     }
 }
 --------------------------------------------------
-// TEST[skip:TBD]
+// TEST[setup:setup_houseprices]
 
 
 The API returns the following result:
@@ -727,6 +736,13 @@ The API returns the following result:
 ----
 {
   "id" : "house_price_regression_analysis",
+  "create_time" : 1656364845151,
+  "version" : "8.4.0",
+  "authorization" : {
+    "roles" : [
+      "superuser"
+    ]
+  },
   "source" : {
     "index" : [
       "houses_sold_last_10_yrs"
@@ -742,17 +758,23 @@ The API returns the following result:
   "analysis" : {
     "regression" : {
       "dependent_variable" : "price",
-      "training_percent" : 100
+      "prediction_field_name" : "price_prediction",
+      "training_percent" : 100.0,
+      "randomize_seed" : -3578554885299300212,
+      "loss_function" : "mse",
+      "early_stopping_enabled" : true
     }
   },
   "model_memory_limit" : "1gb",
-  "create_time" : 1567168659127,
-  "version" : "8.0.0",
-  "allow_lazy_start" : false
+  "allow_lazy_start" : false,
+  "max_num_threads" : 1
 }
+
 ----
-// TESTRESPONSE[s/1567168659127/$body.$_path/]
-// TESTRESPONSE[s/"version": "8.0.0"/"version": $body.version/]
+// TESTRESPONSE[s/1656364845151/$body.$_path/]
+// TESTRESPONSE[s/"version": "8.4.0"/"version": $body.version/]
+// TESTRESPONSE[s/"authorization" : \{[^}]*\},//]
+// TESTRESPONSE[s/-3578554885299300212/$body.$_path/]
 
 
 The following example creates a job and specifies a training percent:

docs/reference/ml/df-analytics/apis/update-dfanalytics.asciidoc

@@ -86,9 +86,49 @@ The following example shows how to update the model memory limit for the existin
 
 [source,console]
 --------------------------------------------------
-POST _ml/data_frame/analytics/model-flight-delays/_update
+POST _ml/data_frame/analytics/loganalytics/_update
 {
   "model_memory_limit": "200mb"
 }
 --------------------------------------------------
 // TEST[skip:setup kibana sample data]
+
+When the job is updated, the response contains its configuration with
+the updated values. For example:
+
+[source,console-result]
+----
+{
+  "id" : "loganalytics",
+  "create_time" : 1656364565517,
+  "version" : "8.4.0",
+  "authorization" : {
+    "roles" : [
+      "superuser"
+    ]
+  },
+  "description" : "Outlier detection on log data",
+  "source" : {
+    "index" : [
+      "logdata"
+    ],
+    "query" : {
+      "match_all" : { }
+    }
+  },
+  "dest" : {
+    "index" : "logdata_out",
+    "results_field" : "ml"
+  },
+  "analysis" : {
+    "outlier_detection" : {
+      "compute_feature_influence" : true,
+      "outlier_fraction" : 0.05,
+      "standardization_enabled" : true
+    }
+  },
+  "model_memory_limit" : "200mb",
+  "allow_lazy_start" : false,
+  "max_num_threads" : 1
+}
+----