diff --git a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc new file mode 100644 index 0000000000000..97f714b5ae32d --- /dev/null +++ b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc @@ -0,0 +1,229 @@ +[[get-snapshot-api]] +=== Get snapshot API +++++ +Get snapshot +++++ + +Retrieves information about one or more snapshots. + +//// +[source,console] +---- +PUT /_snapshot/my_repository +{ + "type": "fs", + "settings": { + "location": "my_backup_location" + } +} + +PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true + +PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=true +---- +// TESTSETUP +//// + +[source,console] +---- +GET /_snapshot/my_repository/my_snapshot +---- + +[[get-snapshot-api-request]] +==== {api-request-title} + +`GET /_snapshot//` + +[[get-snapshot-api-desc]] +==== {api-description-title} + +Use the get snapshot API to return information about one or more snapshots, including: + +* Start and end time values +* Version of {es} that created the snapshot +* List of included indices +* Current state of the snapshot +* List of failures that occurred during the snapshot + +[[get-snapshot-api-path-params]] +==== {api-path-parms-title} + +``:: +(Required, string) +Snapshot repository name used to limit the request. ++ +To get information about all snapshot repositories registered in the +cluster, omit this parameter or use `*` or `_all`. + +``:: +(Required, string) +Comma-separated list of snapshot names to retrieve. Also accepts wildcards (`*`). ++ +* To get information about all snapshots in a registered repository, use a wildcard (`*`) or `_all`. +* To get information about any snapshots that are currently running, use `_current`. ++ +NOTE: Using `_all` in a request fails if any snapshots are unavailable. +Set <> to `true` to return only available snapshots. + +[role="child_attributes"] +[[get-snapshot-api-request-body]] +==== {api-request-body-title} + +[[get-snapshot-api-ignore-unavailable]] +`ignore_unavailable`:: +(Optional, boolean) +If `false`, the request returns an error for any snapshots that are unavailable. Defaults to `false`. ++ +If `true`, the request ignores snapshots that are unavailable, such as those that are corrupted or temporarily cannot be returned. + +`verbose`:: +(Optional, boolean) +If `true`, returns all available information about a snapshot. Defaults to `true`. ++ +If `false`, omits additional information about the snapshot, such as version information, start and end times, and the number of snapshotted shards. + +[role="child_attributes"] +[[get-snapshot-api-response-body]] +==== {api-response-body-title} + +`snapshot`:: +(string) +Name of the snapshot. + +`uuid`:: +(string) +Universally unique identifier (UUID) of the snapshot. + +`version_id`:: +(int) +Build ID of the {es} version used to create the snapshot. + +`version`:: +(float) +{es} version used to create the snapshot. + +`indices`:: +(array) +List of indices included in the snapshot. + +`include_global_state`:: +(boolean) +Indicates whether the current cluster state is included in the snapshot. + +`start_time`:: +(string) +Date timestamp of when the snapshot creation process started. + +`start_time_in_millis`:: +(long) +The time, in milliseconds, when the snapshot creation process started. + +`end_time`:: +(string) +Date timestamp of when the snapshot creation process ended. + +`end_time_in_millis`:: +(long) +The time, in milliseconds, when the snapshot creation process ended. + +`duration_in_millis`:: +(long) +How long, in milliseconds, it took to create the snapshot. + +[[get-snapshot-api-response-failures]] +`failures`:: +(array) +Lists any failures that occurred when creating the snapshot. + +`shards`:: +(object) +Contains a count of shards in the snapshot. ++ +.Properties of `shards` +[%collapsible%open] +==== +`total`:: +(integer) +Total number of shards included in the snapshot. + +`successful`:: +(integer) +Number of shards that were successfully included in the snapshot. + +`failed`:: +(integer) +Number of shards that failed to be included in the snapshot. +==== + +`state`:: ++ +-- +(string) +The snapshot `state` can be one of the following values: + +.Values for `state` +[%collapsible%open] +==== +`IN_PROGRESS`:: + The snapshot is currently running. + +`SUCCESS`:: + The snapshot finished and all shards were stored successfully. + +`FAILED`:: + The snapshot finished with an error and failed to store any data. + +`PARTIAL`:: + The global cluster state was stored, but data of at least one shard was not stored successfully. + The <> section of the response contains more detailed information about shards + that were not processed correctly. +==== +-- + +[[get-snapshot-api-example]] +==== {api-examples-title} + +The following request returns information for `snapshot_2` in the `my_repository` repository. + +[source,console] +---- +GET /_snapshot/my_repository/snapshot_2 +---- + +The API returns the following response: + +[source,console-result] +---- +{ + "snapshots": [ + { + "snapshot": "snapshot_2", + "uuid": "vdRctLCxSketdKb54xw67g", + "version_id": , + "version": , + "indices": [], + "include_global_state": true, + "state": "SUCCESS", + "start_time": "2020-07-06T21:55:18.129Z", + "start_time_in_millis": 1593093628850, + "end_time": "2020-07-06T21:55:18.876Z", + "end_time_in_millis": 1593094752018, + "duration_in_millis": 0, + "failures": [], + "shards": { + "total": 0, + "failed": 0, + "successful": 0 + } + } + ] +} +---- +// TESTRESPONSE[s/"uuid": "vdRctLCxSketdKb54xw67g"/"uuid": $body.snapshots.0.uuid/] +// TESTRESPONSE[s/"version_id": /"version_id": $body.snapshots.0.version_id/] +// TESTRESPONSE[s/"version": /"version": $body.snapshots.0.version/] +// TESTRESPONSE[s/"start_time": "2020-07-06T21:55:18.129Z"/"start_time": $body.snapshots.0.start_time/] +// TESTRESPONSE[s/"start_time_in_millis": 1593093628850/"start_time_in_millis": $body.snapshots.0.start_time_in_millis/] +// TESTRESPONSE[s/"end_time": "2020-07-06T21:55:18.876Z"/"end_time": $body.snapshots.0.end_time/] +// TESTRESPONSE[s/"end_time_in_millis": 1593094752018/"end_time_in_millis": $body.snapshots.0.end_time_in_millis/] +// TESTRESPONSE[s/"duration_in_millis": 0/"duration_in_millis": $body.snapshots.0.duration_in_millis/] diff --git a/docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc b/docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc index 6310cb3917797..f30f04d754310 100644 --- a/docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc +++ b/docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc @@ -25,6 +25,7 @@ content may not be included yet. [[snapshot-management-apis]] === Snapshot management APIs * <> +* <> * <> include::put-repo-api.asciidoc[] @@ -33,4 +34,5 @@ include::get-repo-api.asciidoc[] include::delete-repo-api.asciidoc[] include::clean-up-repo-api.asciidoc[] include::create-snapshot-api.asciidoc[] +include::get-snapshot-api.asciidoc[] include::delete-snapshot-api.asciidoc[] diff --git a/docs/reference/snapshot-restore/take-snapshot.asciidoc b/docs/reference/snapshot-restore/take-snapshot.asciidoc index dda5ab9d5811f..481fcb9ead0c2 100644 --- a/docs/reference/snapshot-restore/take-snapshot.asciidoc +++ b/docs/reference/snapshot-restore/take-snapshot.asciidoc @@ -112,30 +112,24 @@ snapshot and the list of failures that occurred during the snapshot. The snapsho [horizontal] `IN_PROGRESS`:: - The snapshot is currently running. `SUCCESS`:: - The snapshot finished and all shards were stored successfully. `FAILED`:: - The snapshot finished with an error and failed to store any data. `PARTIAL`:: - - The global cluster state was stored, but data of at least one shard wasn't stored successfully. - The `failure` section in this case should contain more detailed information about shards + The global cluster state was stored, but data of at least one shard was not stored successfully. + The `failures` section of the response contains more detailed information about shards that were not processed correctly. `INCOMPATIBLE`:: - - The snapshot was created with an old version of Elasticsearch and therefore is incompatible with + The snapshot was created with an old version of {es} and is incompatible with the current version of the cluster. - -Similar as for repositories, information about multiple snapshots can be queried in one go, supporting wildcards as well: +Similar as for repositories, information about multiple snapshots can be queried in a single request, supporting wildcards as well: [source,console] -----------------------------------