mirror of
https://github.com/elastic/kibana.git
synced 2025-04-25 10:23:14 -04:00
245 lines
8.8 KiB
Text
245 lines
8.8 KiB
Text
[[saved-objects-api-resolve-import-errors]]
|
|
=== Resolve import errors API
|
|
++++
|
|
<titleabbrev>Resolve import errors</titleabbrev>
|
|
++++
|
|
|
|
experimental[] Resolve errors from the <<saved-objects-api-import,Import objects API>>.
|
|
|
|
To resolve errors, you can:
|
|
|
|
* Retry certain saved objects
|
|
|
|
* Overwrite specific saved objects
|
|
|
|
* Change references to different saved objects
|
|
|
|
[NOTE]
|
|
====
|
|
For the most up-to-date API details, refer to the
|
|
{kib-repo}/tree/{branch}/packages/core/saved-objects/docs/openapi[open API specification].
|
|
====
|
|
|
|
[[saved-objects-api-resolve-import-errors-request]]
|
|
==== Request
|
|
|
|
`POST <kibana host>:<port>/api/saved_objects/_resolve_import_errors`
|
|
|
|
`POST <kibana host>:<port>/s/<space_id>/api/saved_objects/_resolve_import_errors`
|
|
|
|
[[saved-objects-api-resolve-import-errors-path-params]]
|
|
==== Path parameters
|
|
|
|
`space_id`::
|
|
(Optional, string) An identifier for the <<xpack-spaces,space>>. When `space_id` is unspecified in the URL, the default space is used.
|
|
|
|
[[saved-objects-api-resolve-import-errors-query-params]]
|
|
==== Query parameters
|
|
|
|
`createNewCopies`::
|
|
(Optional, boolean) Creates copies of the saved objects, regenerates each object ID, and resets the origin. When enabled during the
|
|
initial import, also enable when resolving import errors.
|
|
|
|
`compatibilityMode`::
|
|
(Optional, boolean) Applies various adjustments to the saved objects that are being imported to maintain compatibility between different {kib}
|
|
versions. When enabled during the initial import, also enable when resolving import errors.
|
|
+
|
|
NOTE: This option cannot be used with the `createNewCopies` option.
|
|
|
|
[[saved-objects-api-resolve-import-errors-request-body]]
|
|
==== Request body
|
|
|
|
The request body must include the multipart/form-data type.
|
|
|
|
`file`::
|
|
The same file given to the import API.
|
|
|
|
`retries`::
|
|
(Required, array) The retry operations, which can specify how to resolve different types of errors.
|
|
+
|
|
.Properties of `<retries>`
|
|
[%collapsible%open]
|
|
=====
|
|
`type`:::
|
|
(Required, string) The saved object type.
|
|
`id`:::
|
|
(Required, string) The saved object ID.
|
|
`overwrite`:::
|
|
(Optional, boolean) When set to `true`, the source object overwrites the conflicting destination object. When set to `false`, does
|
|
nothing.
|
|
`destinationId`:::
|
|
(Optional, string) Specifies the destination ID that the imported object should have, if different from the current ID.
|
|
`replaceReferences`:::
|
|
(Optional, array) A list of `type`, `from`, and `to` used to change the object references.
|
|
`ignoreMissingReferences`:::
|
|
(Optional, boolean) When set to `true`, ignores missing reference errors. When set to `false`, does nothing.
|
|
=====
|
|
|
|
[[saved-objects-api-resolve-import-errors-response-body]]
|
|
==== Response body
|
|
|
|
`success`::
|
|
(boolean) Indicates a successful import. When set to `false`, some objects may not have been created. For additional information, refer to
|
|
the `errors` and `successResults` properties.
|
|
|
|
`successCount`::
|
|
(number) Indicates the number of successfully resolved records.
|
|
|
|
`errors`::
|
|
(Optional, array) Specifies the objects that failed to resolve.
|
|
+
|
|
NOTE: One object can result in multiple errors, which requires separate steps to resolve. For instance, a `missing_references` error and a
|
|
`conflict` error.
|
|
|
|
`successResults`::
|
|
(Optional, array) Indicates the objects that are successfully imported, with any metadata if applicable.
|
|
+
|
|
NOTE: Objects are only created when all resolvable errors are addressed, including conflict and missing references. To resolve errors, refer
|
|
to the <<saved-objects-api-resolve-import-errors-example, examples>>.
|
|
|
|
[[saved-objects-api-resolve-import-errors-codes]]
|
|
==== Response code
|
|
|
|
`200`::
|
|
Indicates a successful call.
|
|
|
|
[[saved-objects-api-resolve-import-errors-example]]
|
|
==== Examples
|
|
|
|
[[saved-objects-api-resolve-import-errors-example-1]]
|
|
===== Resolve conflict errors
|
|
|
|
This example builds upon the <<saved-objects-api-import-example-3,Import objects API example with conflict errors>>.
|
|
|
|
Resolve conflict errors for a {data-source}, visualization, and *Canvas* workpad by overwriting the existing saved objects:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
$ curl -X POST api/saved_objects/_resolve_import_errors -H "kbn-xsrf: true" --form file=@file.ndjson --form retries='[{"type":"index-pattern","id":"my-pattern","overwrite":true},{"type":"visualization","id":"my-vis","overwrite":true,"destinationId":"another-vis"},{"type":"canvas","id":"my-canvas","overwrite":true,"destinationId":"yet-another-canvas"},{"type":"dashboard","id":"my-dashboard"}]'
|
|
--------------------------------------------------
|
|
// KIBANA
|
|
|
|
The `file.ndjson` file contains the following:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
{"type":"index-pattern","id":"my-pattern","attributes":{"title":"my-pattern-*"}}
|
|
{"type":"visualization","id":"my-vis","attributes":{"title":"Look at my visualization"}}
|
|
{"type":"canvas-workpad","id":"my-canvas","attributes":{"name":"Look at my canvas"}}
|
|
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}}
|
|
--------------------------------------------------
|
|
|
|
The API returns the following:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
{
|
|
"success": true,
|
|
"successCount": 4,
|
|
"successResults": [
|
|
{
|
|
"id": "my-pattern",
|
|
"type": "index-pattern",
|
|
"meta": {
|
|
"icon": "indexPatternApp",
|
|
"title": "my-pattern-*"
|
|
}
|
|
},
|
|
{
|
|
"id": "my-vis",
|
|
"type": "visualization",
|
|
"destinationId": "another-vis",
|
|
"meta": {
|
|
"icon": "visualizeApp",
|
|
"title": "Look at my visualization"
|
|
}
|
|
},
|
|
{
|
|
"id": "my-canvas",
|
|
"type": "canvas-workpad",
|
|
"destinationId": "yet-another-canvas",
|
|
"meta": {
|
|
"icon": "canvasApp",
|
|
"title": "Look at my canvas"
|
|
}
|
|
},
|
|
{
|
|
"id": "my-dashboard",
|
|
"type": "dashboard",
|
|
"meta": {
|
|
"icon": "dashboardApp",
|
|
"title": "Look at my dashboard"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
|
|
The result indicates a successful import, and all four objects were created.
|
|
|
|
TIP: If a prior import attempt resulted in resolvable errors, you must include a retry for each object you want to import, including any
|
|
that were returned in the `successResults` array. In this example, we retried importing the dashboard accordingly.
|
|
|
|
[[saved-objects-api-resolve-import-errors-example-2]]
|
|
===== Resolve missing reference errors
|
|
|
|
This example builds upon the <<saved-objects-api-import-example-4,Import objects API example with missing reference errors>>.
|
|
|
|
Resolve a missing reference error for a visualization by replacing the {data-source} with another, and resolve a missing reference error for
|
|
a search by ignoring it:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
$ curl -X POST api/saved_objects/_resolve_import_errors -H "kbn-xsrf: true" --form file=@file.ndjson --form retries='[{"type":"visualization","id":"my-vis","replaceReferences":[{"type":"index-pattern","from":"my-pattern-*","to":"existing-pattern"}]},{"type":"search","id":"my-search","ignoreMissingReferences":true},{"type":"dashboard","id":"my-dashboard"}]'
|
|
--------------------------------------------------
|
|
// KIBANA
|
|
|
|
The `file.ndjson` file contains the following:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
{"type":"visualization","id":"my-vis","attributes":{"title":"Look at my visualization"},"references":[{"name":"ref_0","type":"index-pattern","id":"my-pattern-*"}]}
|
|
{"type":"search","id":"my-search","attributes":{"title":"Look at my search"},"references":[{"name":"ref_0","type":"index-pattern","id":"another-pattern-*"}]}
|
|
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"},"references":[{"name":"ref_0","type":"visualization","id":"my-vis"}]}
|
|
--------------------------------------------------
|
|
|
|
The API returns the following:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
{
|
|
"success": true,
|
|
"successCount": 3,
|
|
"successResults": [
|
|
{
|
|
"id": "my-vis",
|
|
"type": "visualization",
|
|
"meta": {
|
|
"icon": "visualizeApp",
|
|
"title": "Look at my visualization"
|
|
}
|
|
},
|
|
{
|
|
"id": "my-search",
|
|
"type": "search",
|
|
"meta": {
|
|
"icon": "searchApp",
|
|
"title": "Look at my search"
|
|
}
|
|
},
|
|
{
|
|
"id": "my-dashboard",
|
|
"type": "dashboard",
|
|
"meta": {
|
|
"icon": "dashboardApp",
|
|
"title": "Look at my dashboard"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
|
|
The result indicates a successful import, and all three objects were created.
|
|
|
|
TIP: If a prior import attempt resulted in resolvable errors, you must include a retry for each object you want to import, including any
|
|
that were returned in the `successResults` array. In this example, we retried importing the dashboard accordingly.
|