From aca1575830e5a064d278a115aff6aa3cd79eb009 Mon Sep 17 00:00:00 2001 From: Court Ewing Date: Fri, 7 Sep 2018 15:25:42 -0400 Subject: [PATCH 1/2] docs: dashboard import/export API --- docs/api.asciidoc | 2 + docs/api/dashboard-import.asciidoc | 17 ++++ docs/api/dashboard-import/export.asciidoc | 38 +++++++++ docs/api/dashboard-import/import.asciidoc | 95 +++++++++++++++++++++++ 4 files changed, 152 insertions(+) create mode 100644 docs/api/dashboard-import.asciidoc create mode 100644 docs/api/dashboard-import/export.asciidoc create mode 100644 docs/api/dashboard-import/import.asciidoc diff --git a/docs/api.asciidoc b/docs/api.asciidoc index 8376c81ff18127..afe7722a0cec5c 100644 --- a/docs/api.asciidoc +++ b/docs/api.asciidoc @@ -29,12 +29,14 @@ entirely. * <> * <> +* <> * <> * <> -- include::api/role-management.asciidoc[] include::api/saved-objects.asciidoc[] +include::api/dashboard-import.asciidoc[] include::api/logstash-configuration-management.asciidoc[] include::api/url-shortening.asciidoc[] diff --git a/docs/api/dashboard-import.asciidoc b/docs/api/dashboard-import.asciidoc new file mode 100644 index 00000000000000..43ed037daf13b2 --- /dev/null +++ b/docs/api/dashboard-import.asciidoc @@ -0,0 +1,17 @@ +[[dashboard-import-api]] +== Dashboard Import API + +The dashboard import/export APIs allow people to import dashboards along with +all of their corresponding saved objects such as visualizations, saved +searches, and index patterns. + +Traditionally, developers would perform this level of integration by writing +documents directly to the `.kibana` index. *Do not do this!* Writing directly +to the `.kibana` index is not safe and it _will_ result in corrupted data that +permanently breaks Kibana in a future version. + +* <> +* <> + +include::dashboard-import/import.asciidoc[] +include::dashboard-import/export.asciidoc[] diff --git a/docs/api/dashboard-import/export.asciidoc b/docs/api/dashboard-import/export.asciidoc new file mode 100644 index 00000000000000..ddafeb35f7cc0c --- /dev/null +++ b/docs/api/dashboard-import/export.asciidoc @@ -0,0 +1,38 @@ +[[dashboard-import-api-export]] +=== Export Dashboard + +experimental[This functionality is *experimental* and may be changed or removed completely in a future release.] + +The dashboard export API allows people to export dashboards along with all of +their corresponding saved objects such as visualizations, saved searches, and +index patterns. + +==== Request + +`GET /api/kibana/dashboards/export` + +==== Query Parameters + +`dashboard` (optional):: + (array|string) The id(s) of the dashboard(s) to export + +==== Response body + +The response body will have a top level `objects` property that contains an +array of saved objects. The order of these objects is not guaranteed. You +should use this exact response body as the request body for the corresponding +<>. + +==== Examples + +The following example exports all saved objects associated with and including +the dashboard with id `942dcef0-b2cd-11e8-ad8e-85441f0c2e5c`. + +[source,js] +-------------------------------------------------- +GET api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c +-------------------------------------------------- +// KIBANA + +A successful call returns a response code of `200` along with the exported +objects as the response body. diff --git a/docs/api/dashboard-import/import.asciidoc b/docs/api/dashboard-import/import.asciidoc new file mode 100644 index 00000000000000..91c59bcddff227 --- /dev/null +++ b/docs/api/dashboard-import/import.asciidoc @@ -0,0 +1,95 @@ +[[dashboard-import-api-import]] +=== Import Dashboard + +experimental[This functionality is *experimental* and may be changed or removed completely in a future release.] + +The dashboard import API allows people to import dashboards along with all of +their corresponding saved objects such as visualizations, saved searches, and +index patterns. + +==== Request + +`POST /api/kibana/dashboards/import` + +==== Query Parameters + +`force` (optional):: + (boolean) Overwrite any existing objects on id conflict +`exclude` (optional):: + (array) Saved object types that should not be imported + +==== Request Body + +The request body is JSON, but you should not manually construct a payload to +this endpoint. Instead, use the complete response body from the +<> as the request body to +this import API. + +==== Response body + +The response body will have a top level `objects` property that contains an +array of the saved objects that were created. The order of these objects is not +guaranteed. + +==== Examples + +The following example imports saved objects associated with and including the +dashboard with id `942dcef0-b2cd-11e8-ad8e-85441f0c2e5c`. + +[source,js] +-------------------------------------------------- +POST api/kibana/dashboards/import?exclude=index-pattern +{ + "objects": [ + { + "id": "80b956f0-b2cd-11e8-ad8e-85441f0c2e5c", + "type": "visualization", + "updated_at": "2018-09-07T18:40:33.247Z", + "version": 1, + "attributes": { + "title": "Count Example", + "visState": "{\"title\":\"Count Example\",\"type\":\"metric\",\"params\":{\"addTooltip\":true,\"addLegend\":false,\"type\":\"metric\",\"metric\":{\"percentageMode\":false,\"useRanges\":false,\"colorSchema\":\"Green to Red\",\"metricColorMode\":\"None\",\"colorsRange\":[{\"from\":0,\"to\":10000}],\"labels\":{\"show\":true},\"invertColors\":false,\"style\":{\"bgFill\":\"#000\",\"bgColor\":false,\"labelColor\":false,\"subText\":\"\",\"fontSize\":60}}},\"aggs\":[{\"id\":\"1\",\"enabled\":true,\"type\":\"count\",\"schema\":\"metric\",\"params\":{}}]}", + "uiStateJSON": "{}", + "description": "", + "version": 1, + "kibanaSavedObjectMeta": { + "searchSourceJSON": "{\"index\":\"90943e30-9a47-11e8-b64d-95841ca0b247\",\"query\":{\"query\":\"\",\"language\":\"lucene\"},\"filter\":[]}" + } + } + }, + { + "id": "90943e30-9a47-11e8-b64d-95841ca0b247", + "type": "index-pattern", + "updated_at": "2018-09-07T18:39:47.683Z", + "version": 1, + "attributes": { + "title": "kibana_sample_data_logs", + "timeFieldName": "timestamp", + "fields": "", + "fieldFormatMap": "{\"hour_of_day\":{}}" + } + }, + { + "id": "942dcef0-b2cd-11e8-ad8e-85441f0c2e5c", + "type": "dashboard", + "updated_at": "2018-09-07T18:41:05.887Z", + "version": 1, + "attributes": { + "title": "Example Dashboard", + "hits": 0, + "description": "", + "panelsJSON": "[{\"gridData\":{\"w\":24,\"h\":15,\"x\":0,\"y\":0,\"i\":\"1\"},\"version\":\"7.0.0-alpha1\",\"panelIndex\":\"1\",\"type\":\"visualization\",\"id\":\"80b956f0-b2cd-11e8-ad8e-85441f0c2e5c\",\"embeddableConfig\":{}}]", + "optionsJSON": "{\"darkTheme\":false,\"useMargins\":true,\"hidePanelTitles\":false}", + "version": 1, + "timeRestore": false, + "kibanaSavedObjectMeta": { + "searchSourceJSON": "{\"query\":{\"query\":\"\",\"language\":\"lucene\"},\"filter\":[]}" + } + } + } + ] +} +-------------------------------------------------- +// KIBANA + +A successful call returns a response code of `200`. From 9292fbc3a79db05fe4cb1207a1d6f1424dd43a6d Mon Sep 17 00:00:00 2001 From: Court Ewing Date: Fri, 7 Sep 2018 15:49:46 -0400 Subject: [PATCH 2/2] docs: clarify response handling of errors in import api --- docs/api/dashboard-import/import.asciidoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/api/dashboard-import/import.asciidoc b/docs/api/dashboard-import/import.asciidoc index 91c59bcddff227..e95d15f1b20d0a 100644 --- a/docs/api/dashboard-import/import.asciidoc +++ b/docs/api/dashboard-import/import.asciidoc @@ -28,8 +28,7 @@ this import API. ==== Response body The response body will have a top level `objects` property that contains an -array of the saved objects that were created. The order of these objects is not -guaranteed. +array of the saved objects that were created. ==== Examples @@ -92,4 +91,6 @@ POST api/kibana/dashboards/import?exclude=index-pattern -------------------------------------------------- // KIBANA -A successful call returns a response code of `200`. +A response code of `200` will be returned even if there are errors importing +individual saved objects. In that case, error information will be returned in +the response body on an object-by-object basis.