From c7e8d72a485e2e1c5634d9b1ed1308654e8a4e7a Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Thu, 2 Jul 2020 13:14:34 -0400 Subject: [PATCH 01/13] Adding page for get snapshot API. --- .../apis/get-snapshot-api.asciidoc | 126 ++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc 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..2b11a12d489cb --- /dev/null +++ b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc @@ -0,0 +1,126 @@ +[[get-snapshot-api]] +==== Get snapshot API +++++ +Get snapshot +++++ + +Returns information about one or more snapshots from one or more registered repositories. + +//// +[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 a snapshot, including start and end time, version of {es} that created the snapshot, the list of included indices, the current state of the snapshot, and the list of failures that occurred during the snapshot. + +[[get-snapshot-api-path-params]] +==== {api-path-parms-title} + +``:: +(Required, string) +Comma-separated list of snapshot repository names used to limit the request. +Wildcard (`*`) expressions are supported. ++ +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 return. Also accepts wildcards (`*`). ++ +To get information about all snapshots in a registered repository, use a wildcard (`*`) or `_all`. ++ +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 snapshot 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 status information and the number of snapshotted shards. + +[[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: + +---- +{ + "snapshot": { + "snapshot": "snapshot_2", + "uuid": "vdRctLCxSketdKb54xw67g", + "version_id": , + "version": , + "indices": [], + "data_streams": [], + "include_global_state": false, + "metadata": { + "taken_by": "user123", + "taken_because": "backup before upgrading" + }, + "state": "SUCCESS", + "start_time": "2020-06-25T14:00:28.850Z", + "start_time_in_millis": 1593093628850, + "end_time": "2020-06-25T14:00:28.850Z", + "end_time_in_millis": 1593094752018, + "duration_in_millis": 0, + "failures": [], + "shards": { + "total": 0, + "failed": 0, + "successful": 0 + } + } +} +---- +// TESTRESPONSE[s/"uuid": "vdRctLCxSketdKb54xw67g"/"uuid": $body.snapshot.uuid/] +// TESTRESPONSE[s/"version_id": /"version_id": $body.snapshot.version_id/] +// TESTRESPONSE[s/"version": /"version": $body.snapshot.version/] +// TESTRESPONSE[s/"start_time": "2020-06-25T14:00:28.850Z"/"start_time": $body.snapshot.start_time/] +// TESTRESPONSE[s/"start_time_in_millis": 1593093628850/"start_time_in_millis": $body.snapshot.start_time_in_millis/] +// TESTRESPONSE[s/"end_time": "2020-06-25T14:00:28.850Z"/"end_time": $body.snapshot.end_time/] +// TESTRESPONSE[s/"end_time_in_millis": 1593094752018/"end_time_in_millis": $body.snapshot.end_time_in_millis/] +// TESTRESPONSE[s/"duration_in_millis": 0/"duration_in_millis": $body.snapshot.duration_in_millis/] From 816bc45edc64779670eb5581fe2d326b51fb9911 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Mon, 6 Jul 2020 15:27:34 -0400 Subject: [PATCH 02/13] Adding values for state and cleaning up some other formatting. --- .../apis/get-snapshot-api.asciidoc | 33 ++++++++++++++++--- .../apis/snapshot-restore-apis.asciidoc | 2 ++ .../snapshot-restore/take-snapshot.asciidoc | 14 +++----- 3 files changed, 34 insertions(+), 15 deletions(-) diff --git a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc index 2b11a12d489cb..7ddd6dbbaa160 100644 --- a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc +++ b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc @@ -1,5 +1,5 @@ [[get-snapshot-api]] -==== Get snapshot API +=== Get snapshot API ++++ Get snapshot ++++ @@ -37,7 +37,7 @@ GET /_snapshot/my_repository/my_snapshot [[get-snapshot-api-desc]] ==== {api-description-title} -Use the get snapshot API to return information about a snapshot, including start and end time, version of {es} that created the snapshot, the list of included indices, the current state of the snapshot, and the list of failures that occurred during the snapshot. +Use the get snapshot API to return information about one or more snapshots, including start and end time, version of {es} that created the snapshot, the list of included indices, the current state of the snapshot, and the list of failures that occurred during the snapshot. [[get-snapshot-api-path-params]] ==== {api-path-parms-title} @@ -54,7 +54,8 @@ cluster, omit this parameter or use `*` or `_all`. (Required, string) Comma-separated list of snapshot names to return. Also accepts wildcards (`*`). + -To get information about all snapshots in a registered repository, use a wildcard (`*`) or `_all`. +* 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, omit this parameter and use `_current`. + NOTE: Using `_all` in a request fails if any snapshots are unavailable. Set <> to `true` to return only available snapshots. @@ -65,7 +66,7 @@ NOTE: Using `_all` in a request fails if any snapshots are unavailable. Set <> +* <> * <> 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 495b107b60099..451e14546c0fe 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] ----------------------------------- From 39c279601abdcb0615f889960781f2110c9e3913 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Mon, 6 Jul 2020 17:46:23 -0400 Subject: [PATCH 03/13] Adding missing forward slash to GET request. --- docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc index 7ddd6dbbaa160..f39a1fa39f1d5 100644 --- a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc +++ b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc @@ -83,7 +83,7 @@ The following request returns information for `snapshot_2` in the `my_repository [source,console] ---- -GET _snapshot/my_repository/snapshot_2 +GET /_snapshot/my_repository/snapshot_2 ---- The API returns the following response: From 309e51a07b5b1229ccdc57ba72277e625447498c Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Mon, 6 Jul 2020 18:35:33 -0400 Subject: [PATCH 04/13] Updating values for start_time and end_time in TESTRESPONSE. --- .../reference/snapshot-restore/apis/get-snapshot-api.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc index f39a1fa39f1d5..1ba1d63effd2e 100644 --- a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc +++ b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc @@ -121,9 +121,9 @@ The API returns the following response: // TESTRESPONSE[s/"uuid": "vdRctLCxSketdKb54xw67g"/"uuid": $body.snapshot.uuid/] // TESTRESPONSE[s/"version_id": /"version_id": $body.snapshot.version_id/] // TESTRESPONSE[s/"version": /"version": $body.snapshot.version/] -// TESTRESPONSE[s/"start_time": "2020-06-25T14:00:28.850Z"/"start_time": $body.snapshot.start_time/] +// TESTRESPONSE[s/"start_time": "2020-07-06T21:55:18.129Z"/"start_time": $body.snapshot.start_time/] // TESTRESPONSE[s/"start_time_in_millis": 1593093628850/"start_time_in_millis": $body.snapshot.start_time_in_millis/] -// TESTRESPONSE[s/"end_time": "2020-06-25T14:00:28.850Z"/"end_time": $body.snapshot.end_time/] +// TESTRESPONSE[s/"end_time": "2020-07-06T21:55:18.129Z"/"end_time": $body.snapshot.end_time/] // TESTRESPONSE[s/"end_time_in_millis": 1593094752018/"end_time_in_millis": $body.snapshot.end_time_in_millis/] // TESTRESPONSE[s/"duration_in_millis": 0/"duration_in_millis": $body.snapshot.duration_in_millis/] From c1c80bd146a82b9099f8c16f38e978d5d76e85b1 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Tue, 7 Jul 2020 10:19:01 -0400 Subject: [PATCH 05/13] Swap "return" for "retrieve" Co-authored-by: James Rodewig --- docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc index 1ba1d63effd2e..e8605bfaab8bd 100644 --- a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc +++ b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc @@ -4,7 +4,7 @@ Get snapshot ++++ -Returns information about one or more snapshots from one or more registered repositories. +Retrieves information about one or more snapshots. //// [source,console] From fb1b3bee513ed00ea751151a69f0992dd21e2927 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Tue, 7 Jul 2020 10:19:39 -0400 Subject: [PATCH 06/13] Swap "return" for "retrieve" 2 Co-authored-by: James Rodewig --- docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc index e8605bfaab8bd..68542f781fee8 100644 --- a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc +++ b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc @@ -52,7 +52,7 @@ cluster, omit this parameter or use `*` or `_all`. ``:: (Required, string) -Comma-separated list of snapshot names to return. Also accepts wildcards (`*`). +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, omit this parameter and use `_current`. From 42cf77c86d95c1c0baf21255ec5c970e06c1a98d Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Tue, 7 Jul 2020 10:20:52 -0400 Subject: [PATCH 07/13] Change .snapshot to .response Co-authored-by: James Rodewig --- .../apis/get-snapshot-api.asciidoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc index 68542f781fee8..d01e4ba8ff927 100644 --- a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc +++ b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc @@ -118,14 +118,14 @@ The API returns the following response: } } ---- -// TESTRESPONSE[s/"uuid": "vdRctLCxSketdKb54xw67g"/"uuid": $body.snapshot.uuid/] -// TESTRESPONSE[s/"version_id": /"version_id": $body.snapshot.version_id/] -// TESTRESPONSE[s/"version": /"version": $body.snapshot.version/] -// TESTRESPONSE[s/"start_time": "2020-07-06T21:55:18.129Z"/"start_time": $body.snapshot.start_time/] -// TESTRESPONSE[s/"start_time_in_millis": 1593093628850/"start_time_in_millis": $body.snapshot.start_time_in_millis/] -// TESTRESPONSE[s/"end_time": "2020-07-06T21:55:18.129Z"/"end_time": $body.snapshot.end_time/] -// TESTRESPONSE[s/"end_time_in_millis": 1593094752018/"end_time_in_millis": $body.snapshot.end_time_in_millis/] -// TESTRESPONSE[s/"duration_in_millis": 0/"duration_in_millis": $body.snapshot.duration_in_millis/] +// TESTRESPONSE[s/"uuid": "vdRctLCxSketdKb54xw67g"/"uuid": $body.responses.0.snapshots.0.uuid/] +// TESTRESPONSE[s/"version_id": /"version_id": $body.responses.0.snapshots.0.version_id/] +// TESTRESPONSE[s/"version": /"version": $body.responses.0.snapshots.0.version/] +// TESTRESPONSE[s/"start_time": "2020-07-06T21:55:18.129Z"/"start_time": $body.responses.0.snapshots.0.start_time/] +// TESTRESPONSE[s/"start_time_in_millis": 1593093628850/"start_time_in_millis": $body.responses.0.snapshots.0.start_time_in_millis/] +// TESTRESPONSE[s/"end_time": "2020-07-06T21:55:18.129Z"/"end_time": $body.responses.0.snapshots.0.end_time/] +// TESTRESPONSE[s/"end_time_in_millis": 1593094752018/"end_time_in_millis": $body.responses.0.snapshots.0.end_time_in_millis/] +// TESTRESPONSE[s/"duration_in_millis": 0/"duration_in_millis": $body.responses.0.snapshots.0.duration_in_millis/] The snapshot `state` can be one of the following values: From e7ac1c0892bc0aaa8ce59504d65daa5e52e9d00b Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Tue, 7 Jul 2020 18:00:48 -0400 Subject: [PATCH 08/13] Adding response parameters and incorporating edits from review. --- .../apis/get-snapshot-api.asciidoc | 106 ++++++++++++++---- 1 file changed, 82 insertions(+), 24 deletions(-) diff --git a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc index d01e4ba8ff927..921bd0ad27dca 100644 --- a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc +++ b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc @@ -37,7 +37,13 @@ GET /_snapshot/my_repository/my_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, version of {es} that created the snapshot, the list of included indices, the current state of the snapshot, and the list of failures that occurred during the snapshot. +Use the get snapshot API to return information about one or more snapshots, including: + +* Value start and end time +* 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} @@ -55,9 +61,10 @@ cluster, omit this parameter or use `*` or `_all`. 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, omit this parameter and use `_current`. +* 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. +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]] @@ -76,6 +83,78 @@ 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`:: +Name of the snapshot. + +`uuid`:: +Universally unique identifier (UUID) of the snapshot. + +`version_id`:: +Build ID of the {es} version used to create the snapshot. + +`version`:: +{es} version used to create the snapshot. + +`indices`:: +Indices that are included in the snapshot. + +`start_time`:: +Date timestamp of when the snapshot creation process started. + +`start_time_in_millis`:: +The start time, in milliseconds, when the snapshot creation process started. + +`end_time`:: +Date timestamp of when the snapshot creation process ended. + +`end_time_in_millis`:: +The end time, in milliseconds, when the snapshot creation process ended. + +`duration_in_millis`:: +How long, in milliseconds, it took to create the snapshot. + +`failures`:: +Lists any failures that occurred when creating the snapshot. + +`shards`:: +Indicates the following shards information: +* Total shards included in the snapshot +* Failed shards that were not included in the snapshot +* Successful shards that were 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 `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 {es} and is incompatible with + the current version of the cluster. +==== +-- + [[get-snapshot-api-example]] ==== {api-examples-title} @@ -126,24 +205,3 @@ The API returns the following response: // TESTRESPONSE[s/"end_time": "2020-07-06T21:55:18.129Z"/"end_time": $body.responses.0.snapshots.0.end_time/] // TESTRESPONSE[s/"end_time_in_millis": 1593094752018/"end_time_in_millis": $body.responses.0.snapshots.0.end_time_in_millis/] // TESTRESPONSE[s/"duration_in_millis": 0/"duration_in_millis": $body.responses.0.snapshots.0.duration_in_millis/] - -The snapshot `state` can be one of the following values: - -[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 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 {es} and is incompatible with - the current version of the cluster. From aa8aa2f28b9c9ee7a59d19d7a141b2781554eac0 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Tue, 7 Jul 2020 18:01:50 -0400 Subject: [PATCH 09/13] Update response example to include repository info Co-authored-by: James Rodewig --- .../apis/get-snapshot-api.asciidoc | 51 ++++++++++--------- 1 file changed, 27 insertions(+), 24 deletions(-) diff --git a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc index 921bd0ad27dca..7b927d38951b6 100644 --- a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc +++ b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc @@ -170,31 +170,34 @@ The API returns the following response: [source,console-result] ---- { - "snapshot": { - "snapshot": "snapshot_2", - "uuid": "vdRctLCxSketdKb54xw67g", - "version_id": , - "version": , - "indices": [], - "data_streams": [], - "include_global_state": false, - "metadata": { - "taken_by": "user123", - "taken_because": "backup before upgrading" - }, - "state": "SUCCESS", - "start_time": "2020-06-25T14:00:28.850Z", - "start_time_in_millis": 1593093628850, - "end_time": "2020-06-25T14:00:28.850Z", - "end_time_in_millis": 1593094752018, - "duration_in_millis": 0, - "failures": [], - "shards": { - "total": 0, - "failed": 0, - "successful": 0 + "responses": [ + { + "repository": "my_repository", + "snapshots": [ + { + "snapshot": "snapshot_2", + "uuid": "vdRctLCxSketdKb54xw67g", + "version_id": , + "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.129Z", + "end_time_in_millis": 1593094752018, + "duration_in_millis": 0, + "failures": [], + "shards": { + "total": 0, + "failed": 0, + "successful": 0 + } + } + ] } - } + ] } ---- // TESTRESPONSE[s/"uuid": "vdRctLCxSketdKb54xw67g"/"uuid": $body.responses.0.snapshots.0.uuid/] From d2aaff6246945160da649a24504443532f210689 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 8 Jul 2020 08:49:33 -0400 Subject: [PATCH 10/13] Change dash to underscore Co-authored-by: James Rodewig --- docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc index 7b927d38951b6..94f39ab5c903d 100644 --- a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc +++ b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc @@ -83,7 +83,7 @@ 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"] +[role="child_attributes"] [[get-snapshot-api-response-body]] ==== {api-response-body-title} From 2880d1277d5d57e2b67605b1d2ce1d730aff08b6 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 8 Jul 2020 08:50:58 -0400 Subject: [PATCH 11/13] Add data type for snapshot in response Co-authored-by: James Rodewig --- docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc index 94f39ab5c903d..067690dd37d70 100644 --- a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc +++ b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc @@ -88,6 +88,7 @@ If `false`, omits additional information about the snapshot, such as version inf ==== {api-response-body-title} `snapshot`:: +(string) Name of the snapshot. `uuid`:: From ce7d5a120aac4730a8afa7c226464eb55fab74ad Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 8 Jul 2020 10:02:19 -0400 Subject: [PATCH 12/13] Incorporating review comments and adding missing response definitions. --- .../apis/get-snapshot-api.asciidoc | 55 ++++++++++++++----- 1 file changed, 42 insertions(+), 13 deletions(-) diff --git a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc index 067690dd37d70..54f2e616a2715 100644 --- a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc +++ b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc @@ -66,7 +66,7 @@ Comma-separated list of snapshot names to retrieve. Also accepts wildcards (`*`) NOTE: Using `_all` in a request fails if any snapshots are unavailable. Set <> to `true` to return only available snapshots. -[role="child-attributes"] +[role="child_attributes"] [[get-snapshot-api-request-body]] ==== {api-request-body-title} @@ -92,40 +92,73 @@ If `false`, omits additional information about the snapshot, such as version inf 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`:: -Indices that are included in the snapshot. +(array) +List of indices included in the snapshot. + +`data_streams`:: +(array) +List of <> 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`:: -The start time, in milliseconds, when the snapshot creation process started. +(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`:: -The end time, in milliseconds, when the snapshot creation process ended. +(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`:: -Indicates the following shards information: -* Total shards included in the snapshot -* Failed shards that were not included in the snapshot -* Successful shards that were included in the snapshot +(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`:: + @@ -147,12 +180,8 @@ The snapshot `state` can be one of the following values: `PARTIAL`:: 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 + The <> 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 {es} and is incompatible with - the current version of the cluster. ==== -- From e0471f41fc3da1f859dac9e77f7640741606665a Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 8 Jul 2020 10:54:21 -0400 Subject: [PATCH 13/13] Minor rewording in description. --- docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc index 54f2e616a2715..5ff01f6a201fe 100644 --- a/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc +++ b/docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc @@ -39,7 +39,7 @@ GET /_snapshot/my_repository/my_snapshot Use the get snapshot API to return information about one or more snapshots, including: -* Value start and end time +* Start and end time values * Version of {es} that created the snapshot * List of included indices * Current state of the snapshot