mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 17:28:26 -04:00
[DOCS] Link to open API specification from ML sync API (#142136)
This commit is contained in:
Lisa Cawley
GitHub
parent
27916d316a
commit
1be987e66a
6 changed files with 100 additions and 295 deletions
|
|
@ -1,4 +1,4 @@
|
|||
[[machine-learning-api]]
|
||||
[[machine-learning-apis]]
|
||||
== Machine learning APIs
|
||||
|
||||
preview::[]
|
||||
|
|
|
|||
|
|
@ -1,240 +0,0 @@
|
|||
[[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
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
--------
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
[[Machine_learning_APIs]]
|
||||
== Machine learning APIs
|
||||
|
||||
* <<ml-sync>>
|
||||
|
||||
[[ml-sync]]
|
||||
=== Sync machine learning 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. If you omit `/s/` and this identifier from the path, the default space is used.
|
||||
|
||||
|==========
|
||||
==== 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
|
||||
--------
|
||||
95
docs/api/machine-learning/sync.asciidoc
Normal file
95
docs/api/machine-learning/sync.asciidoc
Normal file
|
|
@ -0,0 +1,95 @@
|
|||
[[machine-learning-api-sync]]
|
||||
=== Sync {ml} saved objects API
|
||||
++++
|
||||
<titleabbrev>Sync {ml} saved objects</titleabbrev>
|
||||
++++
|
||||
|
||||
Synchronizes {kib} saved objects for {ml} jobs and trained models.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
For the most up-to-date API details, refer to the
|
||||
{kib-repo}/tree/{branch}/x-pack/plugins/ml/common/openapi[open API specification]. For a preview, check out <<machine-learning-apis>>.
|
||||
====
|
||||
|
||||
[[machine-learning-api-sync-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET <kibana host>:<port>/api/ml/saved_objects/sync`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/ml/saved_objects/sync`
|
||||
|
||||
[[machine-learning-api-sync-prereq]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
You must have `all` privileges for the *Machine Learning* feature in the *Analytics* section of the
|
||||
<<kibana-feature-privileges,{kib} feature privileges>>.
|
||||
|
||||
[[machine-learning-api-sync-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
This API runs automatically when you start {kib} and periodically thereafter.
|
||||
|
||||
[[machine-learning-api-sync-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in
|
||||
the URL the default space is used.
|
||||
|
||||
[[machine-learning-api-sync-query-params]]
|
||||
==== {api-query-parms-title}
|
||||
|
||||
`simulate`::
|
||||
(Optional, boolean) When `true`, simulates the synchronization by only returning
|
||||
the list actions that _would_ be performed.
|
||||
|
||||
[[machine-learning-api-sync-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
`datafeedsAdded`::
|
||||
(array) If a saved object for an {anomaly-job} is missing a {dfeed} identifier,
|
||||
it is added. This list contains the {dfeed} identifiers and indicates whether
|
||||
the synchronization was successful.
|
||||
|
||||
`datafeedsRemoved`::
|
||||
(array) If a saved object for an anomaly detection job references a datafeed
|
||||
that no longer exists, it is deleted. This list contains the {dfeed} identifiers
|
||||
and indicates whether the synchronization was successful.
|
||||
|
||||
`savedObjectsCreated`::
|
||||
(array) If saved objects are missing for {ml} jobs or trained models, they are
|
||||
created. This list contains the job and model identifiers and indicates whether
|
||||
the synchronization was successful.
|
||||
|
||||
`savedObjectsDeleted`::
|
||||
(array) If saved objects exist for {ml} jobs or trained models that no longer
|
||||
exist, they are deleted. This list contains the job and model identifiers and
|
||||
indicates whether the synchronization was successful.
|
||||
|
||||
[[machine-learning-api-sync-codes]]
|
||||
==== {api-response-codes-title}
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[[machine-learning-api-sync-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
Retrieve the list of {ml} saved objects that require synchronization:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
GET api/ml/saved_objects/sync?simulate=true
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
If there are two jobs that need to be synchronized, for example, the API returns
|
||||
the following response:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{"savedObjectsCreated":{"anomaly_detector":{"myjob1":{"success":true},"myjob2":{"success":true}}},"savedObjectsDeleted":{},"datafeedsAdded":{},"datafeedsRemoved":{}}
|
||||
--------------------------------------------------
|
||||
|
||||
To perform the synchronization, re-run the API and omit the `simulate` parameter.
|
||||
|
|
@ -416,7 +416,7 @@ This page has been deleted. Refer to <<document-explorer>>.
|
|||
|
||||
This page has been deleted. Refer to <<osquery>>.
|
||||
|
||||
[role="exclude",id="machine-learning-api-sync"]
|
||||
== Sync machine learning saved objects API
|
||||
[role="exclude",id="ml-sync"]
|
||||
== Sync machine learning objects API
|
||||
|
||||
This page has been deleted. Refer to <<ml-sync>>.
|
||||
This page has been deleted. Refer to <<machine-learning-api-sync>>.
|
||||
|
|
@ -100,8 +100,7 @@ include::{kib-repo-dir}/api/actions-and-connectors.asciidoc[]
|
|||
include::{kib-repo-dir}/api/cases.asciidoc[]
|
||||
include::{kib-repo-dir}/api/dashboard-api.asciidoc[]
|
||||
include::{kib-repo-dir}/api/logstash-configuration-management.asciidoc[]
|
||||
include::{kib-repo-dir}/api/machine-learning/ml_apis_v2_docs.asciidoc[]
|
||||
include::{kib-repo-dir}/api/machine-learning/ml_apis_v2_defs.asciidoc[leveloffset=+1]
|
||||
include::{kib-repo-dir}/api/machine-learning.asciidoc[]
|
||||
include::{kib-repo-dir}/api/osquery-manager.asciidoc[]
|
||||
include::{kib-repo-dir}/api/short-urls.asciidoc[]
|
||||
include::{kib-repo-dir}/api/task-manager/health.asciidoc[]
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue