Skip to content

Commit 96a0668

Browse files
author
Adam Locke
authored
[7.x] [DOCS] Adding get snapshot api docs (#59238)
* [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.
1 parent bb1c53a commit 96a0668

File tree

3 files changed

+240
-10
lines changed

3 files changed

+240
-10
lines changed

‎docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
[[get-snapshot-api]]
2+
=== Get snapshot API
3+
++++
4+
<titleabbrev>Get snapshot</titleabbrev>
5+
++++
6+
7+
Retrieves information about one or more snapshots.
8+
9+
////
10+
[source,console]
11+
----
12+
PUT /_snapshot/my_repository
13+
{
14+
"type": "fs",
15+
"settings": {
16+
"location": "my_backup_location"
17+
}
18+
}
19+
20+
PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true
21+
22+
PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=true
23+
----
24+
// TESTSETUP
25+
////
26+
27+
[source,console]
28+
----
29+
GET /_snapshot/my_repository/my_snapshot
30+
----
31+
32+
[[get-snapshot-api-request]]
33+
==== {api-request-title}
34+
35+
`GET /_snapshot/<repository>/<snapshot>`
36+
37+
[[get-snapshot-api-desc]]
38+
==== {api-description-title}
39+
40+
Use the get snapshot API to return information about one or more snapshots, including:
41+
42+
* Start and end time values
43+
* Version of {es} that created the snapshot
44+
* List of included indices
45+
* Current state of the snapshot
46+
* List of failures that occurred during the snapshot
47+
48+
[[get-snapshot-api-path-params]]
49+
==== {api-path-parms-title}
50+
51+
`<repository>`::
52+
(Required, string)
53+
Snapshot repository name used to limit the request.
54+
+
55+
To get information about all snapshot repositories registered in the
56+
cluster, omit this parameter or use `*` or `_all`.
57+
58+
`<snapshot>`::
59+
(Required, string)
60+
Comma-separated list of snapshot names to retrieve. Also accepts wildcards (`*`).
61+
+
62+
* To get information about all snapshots in a registered repository, use a wildcard (`*`) or `_all`.
63+
* To get information about any snapshots that are currently running, use `_current`.
64+
+
65+
NOTE: Using `_all` in a request fails if any snapshots are unavailable.
66+
Set <<get-snapshot-api-ignore-unavailable,`ignore_unavailable`>> to `true` to return only available snapshots.
67+
68+
[role="child_attributes"]
69+
[[get-snapshot-api-request-body]]
70+
==== {api-request-body-title}
71+
72+
[[get-snapshot-api-ignore-unavailable]]
73+
`ignore_unavailable`::
74+
(Optional, boolean)
75+
If `false`, the request returns an error for any snapshots that are unavailable. Defaults to `false`.
76+
+
77+
If `true`, the request ignores snapshots that are unavailable, such as those that are corrupted or temporarily cannot be returned.
78+
79+
`verbose`::
80+
(Optional, boolean)
81+
If `true`, returns all available information about a snapshot. Defaults to `true`.
82+
+
83+
If `false`, omits additional information about the snapshot, such as version information, start and end times, and the number of snapshotted shards.
84+
85+
[role="child_attributes"]
86+
[[get-snapshot-api-response-body]]
87+
==== {api-response-body-title}
88+
89+
`snapshot`::
90+
(string)
91+
Name of the snapshot.
92+
93+
`uuid`::
94+
(string)
95+
Universally unique identifier (UUID) of the snapshot.
96+
97+
`version_id`::
98+
(int)
99+
Build ID of the {es} version used to create the snapshot.
100+
101+
`version`::
102+
(float)
103+
{es} version used to create the snapshot.
104+
105+
`indices`::
106+
(array)
107+
List of indices included in the snapshot.
108+
109+
`data_streams`::
110+
(array)
111+
List of <<data-streams,data streams>> included in the snapshot.
112+
113+
`include_global_state`::
114+
(boolean)
115+
Indicates whether the current cluster state is included in the snapshot.
116+
117+
`start_time`::
118+
(string)
119+
Date timestamp of when the snapshot creation process started.
120+
121+
`start_time_in_millis`::
122+
(long)
123+
The time, in milliseconds, when the snapshot creation process started.
124+
125+
`end_time`::
126+
(string)
127+
Date timestamp of when the snapshot creation process ended.
128+
129+
`end_time_in_millis`::
130+
(long)
131+
The time, in milliseconds, when the snapshot creation process ended.
132+
133+
`duration_in_millis`::
134+
(long)
135+
How long, in milliseconds, it took to create the snapshot.
136+
137+
[[get-snapshot-api-response-failures]]
138+
`failures`::
139+
(array)
140+
Lists any failures that occurred when creating the snapshot.
141+
142+
`shards`::
143+
(object)
144+
Contains a count of shards in the snapshot.
145+
+
146+
.Properties of `shards`
147+
[%collapsible%open]
148+
====
149+
`total`::
150+
(integer)
151+
Total number of shards included in the snapshot.
152+
153+
`successful`::
154+
(integer)
155+
Number of shards that were successfully included in the snapshot.
156+
157+
`failed`::
158+
(integer)
159+
Number of shards that failed to be included in the snapshot.
160+
====
161+
162+
`state`::
163+
+
164+
--
165+
(string)
166+
The snapshot `state` can be one of the following values:
167+
168+
.Values for `state`
169+
[%collapsible%open]
170+
====
171+
`IN_PROGRESS`::
172+
The snapshot is currently running.
173+
174+
`SUCCESS`::
175+
The snapshot finished and all shards were stored successfully.
176+
177+
`FAILED`::
178+
The snapshot finished with an error and failed to store any data.
179+
180+
`PARTIAL`::
181+
The global cluster state was stored, but data of at least one shard was not stored successfully.
182+
The <<get-snapshot-api-response-failures,`failures`>> section of the response contains more detailed information about shards
183+
that were not processed correctly.
184+
====
185+
--
186+
187+
[[get-snapshot-api-example]]
188+
==== {api-examples-title}
189+
190+
The following request returns information for `snapshot_2` in the `my_repository` repository.
191+
192+
[source,console]
193+
----
194+
GET /_snapshot/my_repository/snapshot_2
195+
----
196+
197+
The API returns the following response:
198+
199+
[source,console-result]
200+
----
201+
{
202+
"snapshots": [
203+
{
204+
"snapshot": "snapshot_2",
205+
"uuid": "vdRctLCxSketdKb54xw67g",
206+
"version_id": <version_id>,
207+
"version": <version>,
208+
"indices": [],
209+
"data_streams": [],
210+
"include_global_state": true,
211+
"state": "SUCCESS",
212+
"start_time": "2020-07-06T21:55:18.129Z",
213+
"start_time_in_millis": 1593093628850,
214+
"end_time": "2020-07-06T21:55:18.876Z",
215+
"end_time_in_millis": 1593094752018,
216+
"duration_in_millis": 0,
217+
"failures": [],
218+
"shards": {
219+
"total": 0,
220+
"failed": 0,
221+
"successful": 0
222+
}
223+
}
224+
]
225+
}
226+
----
227+
// TESTRESPONSE[s/"uuid": "vdRctLCxSketdKb54xw67g"/"uuid": $body.snapshots.0.uuid/]
228+
// TESTRESPONSE[s/"version_id": <version_id>/"version_id": $body.snapshots.0.version_id/]
229+
// TESTRESPONSE[s/"version": <version>/"version": $body.snapshots.0.version/]
230+
// TESTRESPONSE[s/"start_time": "2020-07-06T21:55:18.129Z"/"start_time": $body.snapshots.0.start_time/]
231+
// TESTRESPONSE[s/"start_time_in_millis": 1593093628850/"start_time_in_millis": $body.snapshots.0.start_time_in_millis/]
232+
// TESTRESPONSE[s/"end_time": "2020-07-06T21:55:18.876Z"/"end_time": $body.snapshots.0.end_time/]
233+
// TESTRESPONSE[s/"end_time_in_millis": 1593094752018/"end_time_in_millis": $body.snapshots.0.end_time_in_millis/]
234+
// TESTRESPONSE[s/"duration_in_millis": 0/"duration_in_millis": $body.snapshots.0.duration_in_millis/]

‎docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ content may not be included yet.
2525
[[snapshot-management-apis]]
2626
=== Snapshot management APIs
2727
* <<create-snapshot-api,Create snapshot>>
28+
* <<get-snapshot-api,Get snapshot>>
2829
* <<delete-snapshot-api,Delete snapshot>>
2930

3031
include::put-repo-api.asciidoc[]
@@ -33,4 +34,5 @@ include::get-repo-api.asciidoc[]
3334
include::delete-repo-api.asciidoc[]
3435
include::clean-up-repo-api.asciidoc[]
3536
include::create-snapshot-api.asciidoc[]
37+
include::get-snapshot-api.asciidoc[]
3638
include::delete-snapshot-api.asciidoc[]

‎docs/reference/snapshot-restore/take-snapshot.asciidoc

Lines changed: 4 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -112,30 +112,24 @@ snapshot and the list of failures that occurred during the snapshot. The snapsho
112112

113113
[horizontal]
114114
`IN_PROGRESS`::
115-
116115
The snapshot is currently running.
117116

118117
`SUCCESS`::
119-
120118
The snapshot finished and all shards were stored successfully.
121119

122120
`FAILED`::
123-
124121
The snapshot finished with an error and failed to store any data.
125122

126123
`PARTIAL`::
127-
128-
The global cluster state was stored, but data of at least one shard wasn't stored successfully.
129-
The `failure` section in this case should contain more detailed information about shards
124+
The global cluster state was stored, but data of at least one shard was not stored successfully.
125+
The `failures` section of the response contains more detailed information about shards
130126
that were not processed correctly.
131127

132128
`INCOMPATIBLE`::
133-
134-
The snapshot was created with an old version of Elasticsearch and therefore is incompatible with
129+
The snapshot was created with an old version of {es} and is incompatible with
135130
the current version of the cluster.
136131

137-
138-
Similar as for repositories, information about multiple snapshots can be queried in one go, supporting wildcards as well:
132+
Similar as for repositories, information about multiple snapshots can be queried in a single request, supporting wildcards as well:
139133

140134
[source,console]
141135
-----------------------------------

0 commit comments

Comments
 (0)