[DOCS] Replace ML API page with automated output (#136583)

elastic · Jul 22, 2022 · 7c8dff7 · 7c8dff7
1 parent 34af4dc
commit 7c8dff7
Show file tree

Hide file tree

Showing 5 changed files with 338 additions and 90 deletions.
diff --git a/docs/api/machine-learning/ml_apis_v2_defs.asciidoc b/docs/api/machine-learning/ml_apis_v2_defs.asciidoc
@@ -0,0 +1,240 @@
+[[Machine_learning_APIs-definitions]]
+== Definitions
+
+* <<MLSyncResponse>>
+* <<MLSyncResponse-Datafeeds>>
+* <<MLSyncResponse-Jobs>>
+* <<MLSyncResponse-Models>>
+* <<MLSyncResponse-SavedObjectsCreated>>
+* <<MLSyncResponse-SavedObjectsDeleted>>
+
+[[MLSyncResponse]]
+=== `MLSyncResponse`
+
+The sync machine learning saved objects API returns this list of machine learning saved objects that required synchronization.
+
+
+==== Properties
+
+`datafeedsAdded` (++map[string,++<<MLSyncResponse-Datafeeds,`MLSyncResponse-Datafeeds`>>++]++)::
+If a saved object for an anomaly detection job is missing a datafeed identifier, it is added when you run the sync machine learning saved objects API.
+
+
+`datafeedsRemoved` (++map[string,++<<MLSyncResponse-Datafeeds,`MLSyncResponse-Datafeeds`>>++]++)::
+If a saved object for an anomaly detection job references a datafeed that no longer exists, it is deleted when you run the sync machine learning saved objects API.
+
+
+`savedObjectsCreated` (<<MLSyncResponse-SavedObjectsCreated,`MLSyncResponse-SavedObjectsCreated`>>)::
+If saved objects are missing for machine learning jobs or trained models, they are created when you run the sync machine learning saved objects API.
+
+
+`savedObjectsDeleted` (<<MLSyncResponse-SavedObjectsDeleted,`MLSyncResponse-SavedObjectsDeleted`>>)::
+If saved objects exist for machine learning jobs or trained models that no longer exist, they are deleted when you run the sync machine learning saved objects API.
+
+
+==== Example
+
+[source,json]
+--------
+{
+   "datafeedsAdded" : {
+      "some_property" : {
+         "success" : true
+      }
+   },
+   "datafeedsRemoved" : {
+      "some_property" : {
+         "success" : true
+      }
+   },
+   "savedObjectsCreated" : {
+      "anomaly-detector" : {
+         "some_property" : {
+            "success" : true
+         }
+      },
+      "data-frame-analytics" : {
+         "some_property" : {
+            "success" : true
+         }
+      },
+      "trained-model" : {
+         "some_property" : {
+            "success" : true
+         }
+      }
+   },
+   "savedObjectsDeleted" : {
+      "anomaly-detector" : {
+         "some_property" : {
+            "success" : true
+         }
+      },
+      "data-frame-analytics" : {
+         "some_property" : {
+            "success" : true
+         }
+      },
+      "trained-model" : {
+         "some_property" : {
+            "success" : true
+         }
+      }
+   }
+}
+
+--------
+
+[[MLSyncResponse-Datafeeds]]
+=== `MLSyncResponse-Datafeeds`
+
+The sync machine learning saved objects API response contains this object when there are datafeeds affected by the synchronization. There is an object for each relevant datafeed, which contains the synchronization status.
+
+
+==== Properties
+
+`success` (+boolean+)::
+The success or failure of the synchronization.
+
+
+==== Example
+
+[source,json]
+--------
+{
+   "success" : true
+}
+
+--------
+
+[[MLSyncResponse-Jobs]]
+=== `MLSyncResponse-Jobs`
+
+The sync machine learning saved objects API response contains this object when there are machine learning jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.
+
+
+==== Properties
+
+`success` (+boolean+)::
+The success or failure of the synchronization.
+
+
+==== Example
+
+[source,json]
+--------
+{
+   "success" : true
+}
+
+--------
+
+[[MLSyncResponse-Models]]
+=== `MLSyncResponse-Models`
+
+The sync machine learning saved objects API response contains this object when there are trained models affected by the synchronization. There is an object for each relevant trained model, which contains the synchronization status.
+
+
+==== Properties
+
+`success` (+boolean+)::
+The success or failure of the synchronization.
+
+
+==== Example
+
+[source,json]
+--------
+{
+   "success" : true
+}
+
+--------
+
+[[MLSyncResponse-SavedObjectsCreated]]
+=== `MLSyncResponse-SavedObjectsCreated`
+
+If saved objects are missing for machine learning jobs or trained models, they are created when you run the sync machine learning saved objects API.
+
+
+==== Properties
+
+`anomaly-detector` (++map[string,++<<MLSyncResponse-Jobs,`MLSyncResponse-Jobs`>>++]++)::
+This object is present if there are anomaly detection jobs affected by the synchronization.
+
+
+`data-frame-analytics` (++map[string,++<<MLSyncResponse-Jobs,`MLSyncResponse-Jobs`>>++]++)::
+This object is present if there are data frame analytics jobs affected by the synchronization.
+
+
+`trained-model` (++map[string,++<<MLSyncResponse-Models,`MLSyncResponse-Models`>>++]++)::
+This object is present if there are trained models affected by the synchronization.
+
+
+==== Example
+
+[source,json]
+--------
+{
+   "anomaly-detector" : {
+      "some_property" : {
+         "success" : true
+      }
+   },
+   "data-frame-analytics" : {
+      "some_property" : {
+         "success" : true
+      }
+   },
+   "trained-model" : {
+      "some_property" : {
+         "success" : true
+      }
+   }
+}
+
+--------
+
+[[MLSyncResponse-SavedObjectsDeleted]]
+=== `MLSyncResponse-SavedObjectsDeleted`
+
+If saved objects exist for machine learning jobs or trained models that no longer exist, they are deleted when you run the sync machine learning saved objects API.
+
+
+==== Properties
+
+`anomaly-detector` (++map[string,++<<MLSyncResponse-Jobs,`MLSyncResponse-Jobs`>>++]++)::
+This object is present if there are anomaly detection jobs affected by the synchronization.
+
+
+`data-frame-analytics` (++map[string,++<<MLSyncResponse-Jobs,`MLSyncResponse-Jobs`>>++]++)::
+This object is present if there are data frame analytics jobs affected by the synchronization.
+
+
+`trained-model` (++map[string,++<<MLSyncResponse-Models,`MLSyncResponse-Models`>>++]++)::
+This object is present if there are trained models affected by the synchronization.
+
+
+==== Example
+
+[source,json]
+--------
+{
+   "anomaly-detector" : {
+      "some_property" : {
+         "success" : true
+      }
+   },
+   "data-frame-analytics" : {
+      "some_property" : {
+         "success" : true
+      }
+   },
+   "trained-model" : {
+      "some_property" : {
+         "success" : true
+      }
+   }
+}
+
+--------
diff --git a/docs/api/machine-learning/ml_apis_v2_docs.asciidoc b/docs/api/machine-learning/ml_apis_v2_docs.asciidoc
@@ -0,0 +1,86 @@
+[[Machine_learning_APIs]]
+== Machine learning APIs
+
+* <<ml-sync-default>>
+* <<ml-sync>>
+
+[[ml-sync-default]]
+=== Sync machine learning saved objects in the default space
+
+Synchronizes Kibana saved objects for machine learning jobs and trained models in the default space. You must have `all` privileges for the *Machine Learning* feature in the *Analytics* section of the Kibana feature privileges. This API runs automatically when you start Kibana and periodically thereafter.
+
+
+==== Request
+
+`GET /api/ml/saved_objects/sync`
+
+==== Query parameters
+
+[options="header"]
+|==========
+|Name |Type |Required |Description
+|`simulate` |+boolean+; default: ++false++ |N |When true, simulates the synchronization by returning only the list actions that would be performed.
+
+|==========
+==== Responses
+
+`200`::
++
+--
+(<<MLSyncResponse,`MLSyncResponse`>>)
+
+Indicates a successful call.
+
+--
+
+==== Request example
+
+[source,json]
+--------
+curl -XGET https://localhost:5601/api/ml/saved_objects/sync \
+-u USER:PASSWORD
+--------
+[[ml-sync]]
+=== Sync machine learning saved objects
+
+Synchronizes Kibana saved objects for machine learning jobs and trained models. You must have `all` privileges for the *Machine Learning* feature in the *Analytics* section of the Kibana feature privileges. This API runs automatically when you start Kibana and periodically thereafter.
+
+
+==== Request
+
+`GET /s/{spaceId}/api/ml/saved_objects/sync`
+
+==== Path parameters
+
+[options="header"]
+|==========
+|Name |Type |Required |Description
+|`spaceId` |+string+ |Y |An identifier for the space.
+
+|==========
+==== Query parameters
+
+[options="header"]
+|==========
+|Name |Type |Required |Description
+|`simulate` |+boolean+; default: ++false++ |N |When true, simulates the synchronization by returning only the list actions that would be performed.
+
+|==========
+==== Responses
+
+`200`::
++
+--
+(<<MLSyncResponse,`MLSyncResponse`>>)
+
+Indicates a successful call.
+
+--
+
+==== Request example
+
+[source,json]
+--------
+curl -XGET https://localhost:5601/s/{spaceId}/api/ml/saved_objects/sync \
+-u USER:PASSWORD
+--------