mirror of
https://github.com/elastic/kibana.git
synced 2025-06-27 10:40:07 -04:00
Document update objects spaces API (#145109)
Resolves #133149 ## Summary Document update objects spaces API Co-authored-by: Jeramy Soucy <jeramy.soucy@elastic.co>
This commit is contained in:
Thom Heymann
GitHub
parent
42a7867454
commit
2e7b789a30
3 changed files with 229 additions and 0 deletions
|
|
@ -22,6 +22,10 @@ The following {kib} spaces APIs are available:
|
|||
|
||||
* <<spaces-api-disable-legacy-url-aliases, Disable legacy URL aliases API>> to disable legacy URL aliases if an error is encountered
|
||||
|
||||
* <<spaces-api-update-objects-spaces, Update saved objects spaces API>> to update one or more saved objects to add and/or remove them from specified spaces
|
||||
|
||||
* <<spaces-api-get-shareable-references, Get shareable references API>> to collect references and spaces context for saved objects
|
||||
|
||||
include::spaces-management/post.asciidoc[]
|
||||
include::spaces-management/put.asciidoc[]
|
||||
include::spaces-management/get.asciidoc[]
|
||||
|
|
@ -30,3 +34,5 @@ include::spaces-management/delete.asciidoc[]
|
|||
include::spaces-management/copy_saved_objects.asciidoc[]
|
||||
include::spaces-management/resolve_copy_saved_objects_conflicts.asciidoc[]
|
||||
include::spaces-management/disable_legacy_url_aliases.asciidoc[]
|
||||
include::spaces-management/update_objects_spaces.asciidoc[]
|
||||
include::spaces-management/get_shareable_references.asciidoc[]
|
||||
|
|
|
|||
81
docs/api/spaces-management/get_shareable_references.asciidoc
Normal file
81
docs/api/spaces-management/get_shareable_references.asciidoc
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
[role="xpack"]
|
||||
[[spaces-api-get-shareable-references]]
|
||||
=== Get shareable references API
|
||||
++++
|
||||
<titleabbrev>Get shareable references</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental[] Get shareable references.
|
||||
|
||||
Collects references and spaces context for saved objects.
|
||||
|
||||
[[spaces-api-get-shareable-references-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST <kibana host>:<port>/api/spaces/_get_shareable_references`
|
||||
|
||||
[[spaces-api-get-shareable-references-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
`objects`::
|
||||
(Required, object array) The saved objects to collect outbound references for.
|
||||
+
|
||||
.Properties of `objects`
|
||||
[%collapsible%open]
|
||||
=====
|
||||
`type`:::
|
||||
(Required, string) The saved object type.
|
||||
|
||||
`id`:::
|
||||
(Required, string) The saved object ID.
|
||||
=====
|
||||
|
||||
[role="child_attributes"]
|
||||
[[spaces-api-get-shareable-references-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
`objects`::
|
||||
(object array) The returned input object or one of its references, with additional context.
|
||||
+
|
||||
.Properties of `objects`
|
||||
[%collapsible%open]
|
||||
=====
|
||||
`type`:::
|
||||
(string) The saved object type.
|
||||
|
||||
`id`:::
|
||||
(string) The saved object ID.
|
||||
|
||||
`originId`:::
|
||||
(string) The origin ID of the referenced object (if it has one).
|
||||
|
||||
`inboundReferences`:::
|
||||
(object array) References to this object.
|
||||
+
|
||||
NOTE: This does not contain _all inbound references everywhere_, it only contains inbound references to this object within the scope of this operation.
|
||||
+
|
||||
.Properties of `inboundReferences`
|
||||
[%collapsible%open]
|
||||
======
|
||||
`type`::::
|
||||
(string) The type of the object that has the inbound reference.
|
||||
|
||||
`id`::::
|
||||
(string) The ID of the object that has the inbound reference.
|
||||
|
||||
`name`::::
|
||||
(string) The name of the inbound reference.
|
||||
======
|
||||
|
||||
`spaces`:::
|
||||
(string array) The space(s) that the referenced saved object exists in.
|
||||
|
||||
`spacesWithMatchingAliases`:::
|
||||
(string array) The space(s) that legacy URL aliases matching this type/id exist in. (if there are any)
|
||||
|
||||
`spacesWithMatchingOrigins`:::
|
||||
(string array) The space(s) that objects matching this origin exist in (including this one). (if there are any)
|
||||
|
||||
`isMissing`:::
|
||||
(boolean) Whether or not this object or reference is missing.
|
||||
=====
|
||||
142
docs/api/spaces-management/update_objects_spaces.asciidoc
Normal file
142
docs/api/spaces-management/update_objects_spaces.asciidoc
Normal file
|
|
@ -0,0 +1,142 @@
|
|||
[role="xpack"]
|
||||
[[spaces-api-update-objects-spaces]]
|
||||
=== Update saved objects spaces API
|
||||
++++
|
||||
<titleabbrev>Update saved objects spaces</titleabbrev>
|
||||
++++
|
||||
|
||||
experimental[] Update saved objects spaces.
|
||||
|
||||
Updates one or more saved objects to add and/or remove them from specified spaces.
|
||||
|
||||
[[spaces-api-update-objects-spaces-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST <kibana host>:<port>/api/spaces/_update_objects_spaces`
|
||||
|
||||
[[spaces-api-update-objects-spaces-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
`objects`::
|
||||
(Required, object array) The saved objects to update.
|
||||
+
|
||||
.Properties of `objects`
|
||||
[%collapsible%open]
|
||||
=====
|
||||
`type`:::
|
||||
(Required, string) The saved object type.
|
||||
|
||||
`id`:::
|
||||
(Required, string) The saved object ID.
|
||||
=====
|
||||
|
||||
`spacesToAdd`::
|
||||
(Required, string array) The IDs of the spaces the specified objects should be added to.
|
||||
|
||||
`spacesToRemove`::
|
||||
(Required, string array) The IDs of the spaces the specified objects should be removed from.
|
||||
|
||||
[role="child_attributes"]
|
||||
[[spaces-api-update-objects-spaces-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
`objects`::
|
||||
(object array) The saved objects that have been updated.
|
||||
+
|
||||
.Properties of `objects`
|
||||
[%collapsible%open]
|
||||
=====
|
||||
`type`:::
|
||||
(string) The saved object type.
|
||||
|
||||
`id`:::
|
||||
(string) The saved object ID.
|
||||
|
||||
`spaces`:::
|
||||
(string array) The space(s) that the referenced saved object exists in.
|
||||
|
||||
`errors`:::
|
||||
(string) Included if there was an error updating this object's spaces.
|
||||
=====
|
||||
|
||||
[[spaces-api-update-objects-spaces-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
[[spaces-api-update-objects-spaces-example-1]]
|
||||
===== Sharing saved objects
|
||||
|
||||
To share a saved object to a space programmatically follow these steps:
|
||||
|
||||
1. Collect reference graph and spaces context for each saved object that you want to share using <<spaces-api-get-shareable-references, Get shareable references API>>:
|
||||
+
|
||||
[source,sh]
|
||||
----
|
||||
$ curl -X POST /api/spaces/_get_shareable_references
|
||||
{
|
||||
"objects": [
|
||||
{
|
||||
"type": "index-pattern",
|
||||
"id": "90943e30-9a47-11e8-b64d-95841ca0b247"
|
||||
}
|
||||
]
|
||||
}
|
||||
----
|
||||
+
|
||||
The API returns the following:
|
||||
+
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"objects": [
|
||||
{
|
||||
"type": "index-pattern",
|
||||
"id": "90943e30-9a47-11e8-b64d-95841ca0b247",
|
||||
"spaces": ["default"],
|
||||
"inboundReferences": [],
|
||||
"spacesWithMatchingOrigins": ["default"]
|
||||
}
|
||||
]
|
||||
}
|
||||
----
|
||||
|
||||
2. Check each saved object for `spacesWithMatchingOrigins` conflicts.
|
||||
+
|
||||
Objects should not be shared to spaces with matching origins or you will create URL conflicts (causing the same URL to point to different saved objects).
|
||||
|
||||
3. Check each saved object for `spacesWithMatchingAliases` conflicts.
|
||||
+
|
||||
If these match the space(s) that these saved objects will be shared to you should disable legacy URL aliases for them using <<spaces-api-disable-legacy-url-aliases, Disable legacy URL aliases API>>.
|
||||
+
|
||||
When sharing to all spaces (`*`) all entries in `spacesWithMatchingAliases` should be checked.
|
||||
|
||||
4. Update spaces of each saved object and all its references:
|
||||
+
|
||||
[source,sh]
|
||||
----
|
||||
$ curl -X POST /api/spaces/_update_objects_spaces
|
||||
{
|
||||
"objects": [
|
||||
{
|
||||
"type": "index-pattern",
|
||||
"id": "90943e30-9a47-11e8-b64d-95841ca0b247"
|
||||
}
|
||||
],
|
||||
"spacesToAdd": ["test"],
|
||||
"spacesToRemove": []
|
||||
}
|
||||
----
|
||||
+
|
||||
The API returns the following:
|
||||
+
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"objects": [
|
||||
{
|
||||
"type": "index-pattern",
|
||||
"id": "90943e30-9a47-11e8-b64d-95841ca0b247",
|
||||
"spaces": ["default", "test"]
|
||||
}
|
||||
]
|
||||
}
|
||||
----
|
||||
Loading…
Add table
Add a link
Reference in a new issue