Skip to content

Commit

Permalink
[7.x] [DOCS] Adding get snapshot api docs (#59238)
Browse files Browse the repository at this point in the history
* [DOCS] Adding get snapshot API docs (#59098)

* Adding page for get snapshot API.

* Adding values for state and cleaning up some other formatting.

* Adding missing forward slash to GET request.

* Updating values for start_time and end_time in TESTRESPONSE.

* Swap "return" for "retrieve"

* Swap "return" for "retrieve" 2

* Change .snapshot to .response

* Adding response parameters and incorporating edits from review.

* Update response example to include repository info

* Change dash to underscore

* Add data type for snapshot in response

* Incorporating review comments and adding missing response definitions.

* Minor rewording in description.

* Removing multi-snapshot support for 7.x.

* Changing end_time value from build error.

* Removing .response from snippet testing.
  • Loading branch information
Adam Locke authored Jul 8, 2020
1 parent bb1c53a commit 96a0668
Show file tree
Hide file tree
Showing 3 changed files with 240 additions and 10 deletions.
234 changes: 234 additions & 0 deletions docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,234 @@
[[get-snapshot-api]]
=== Get snapshot API
++++
<titleabbrev>Get snapshot</titleabbrev>
++++

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/<repository>/<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}

`<repository>`::
(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`.

`<snapshot>`::
(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 <<get-snapshot-api-ignore-unavailable,`ignore_unavailable`>> 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.

`data_streams`::
(array)
List of <<data-streams,data streams>> 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 <<get-snapshot-api-response-failures,`failures`>> 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_id>,
"version": <version>,
"indices": [],
"data_streams": [],
"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>/"version_id": $body.snapshots.0.version_id/]
// TESTRESPONSE[s/"version": <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/]
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ content may not be included yet.
[[snapshot-management-apis]]
=== Snapshot management APIs
* <<create-snapshot-api,Create snapshot>>
* <<get-snapshot-api,Get snapshot>>
* <<delete-snapshot-api,Delete snapshot>>

include::put-repo-api.asciidoc[]
Expand All @@ -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[]
14 changes: 4 additions & 10 deletions docs/reference/snapshot-restore/take-snapshot.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
-----------------------------------
Expand Down

0 comments on commit 96a0668

Please sign in to comment.