[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.
This commit is contained in:
Adam Locke
GitHub
parent
bb1c53a0f5
commit
96a06685cf
|
|
@ -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/]
|
||||
|
|
@ -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[]
|
||||
|
|
@ -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[]
|
||||
|
|
|
|||
|
|
@ -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]
|
||||
-----------------------------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue