› › ›

获取快照 API

获取快照 API编辑

检索有关一个或多个快照的信息。

response = client.snapshot.get(
  repository: 'my_repository',
  snapshot: 'my_snapshot'
)
puts response

GET /_snapshot/my_repository/my_snapshot

请求编辑

GET /_snapshot/<repository>/<snapshot>

先决条件编辑

如果启用了 Elasticsearch 安全功能，您必须具有 monitor_snapshot、create_snapshot 或 manage 集群权限才能使用此 API。

路径参数编辑

<repository>

(必需，字符串) 用于限制请求的快照存储库名称的逗号分隔列表。支持通配符 (*) 表达式，包括将通配符与以 - 开头的排除模式组合。

要获取有关集群中注册的所有快照存储库的信息，请省略此参数或使用 * 或 _all。

<snapshot>

(必需，字符串) 要检索的快照名称的逗号分隔列表。支持通配符 (*) 表达式，包括将通配符与以 - 开头的排除模式组合。

要获取有关注册存储库中的所有快照的信息，请使用通配符 (*) 或 _all。
要获取有关当前正在运行的任何快照的信息，请使用 _current。

如果任何快照不可用，则在请求中使用 _all 会失败。将 ignore_unavailable 设置为 true 以仅返回可用的快照。

查询参数编辑

master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时时间到期之前主节点不可用，则请求失败并返回错误。默认为 30s。也可以设置为 -1 表示请求永远不会超时。

ignore_unavailable

(可选，布尔值) 如果为 false，则请求会针对任何不可用的快照返回错误。默认为 false。

如果为 true，则请求会忽略不可用的快照，例如损坏的快照或暂时无法返回的快照。

verbose

(可选，布尔值) 如果为 true，则返回有关每个快照的附加信息，例如用于创建快照的 Elasticsearch 版本、快照的开始和结束时间以及快照的分片数量。默认为 true。如果为 false，则省略附加信息。

index_names

(可选，布尔值) 如果为 true，则在响应中返回每个快照中包含的索引名称列表。默认为 true。

index_details

(可选，布尔值) 如果为 true，则返回有关快照中每个索引的附加信息，包括索引中的分片数量、索引的总大小（以字节为单位）以及索引中每个分片的最大段数。默认为 false，这意味着此信息将被省略。

include_repository

(可选，布尔值) 如果为 true，则在响应中返回每个快照的存储库名称。默认为 true。

sort

(可选，字符串) 允许设置结果的排序顺序。默认为 start_time，即按快照开始时间戳排序。

有效 sort 值

start_time: 按快照开始时间戳排序快照，并按快照名称打破平局。
duration: 按快照持续时间排序快照，并按快照名称打破平局。
name: 按快照名称排序快照。
repository: 按快照存储库名称排序快照，并按快照名称打破平局。
index_count: 按快照包含的索引数量排序快照，并按快照名称打破平局。
shard_count: 按快照包含的分片数量排序快照，并按快照名称打破平局。
failed_shard_count: 按快照未能快照的分片数量排序快照，并按快照名称打破平局。

size

(可选，整数) 要返回的最大快照数量。默认为 0，这意味着返回所有与请求匹配的快照，没有限制。

order

(可选，字符串) 排序顺序。有效值为 asc（升序）和 desc（降序）。默认为 asc，表示升序。

from_sort_value

(可选，字符串) 要开始检索的当前排序列的值。可以是字符串快照或存储库名称（按快照或存储库名称排序）、毫秒时间值或数字（按索引或分片数量排序）。

after

(可选，字符串) 从响应主体中的 next 字段返回的偏移量标识符开始分页。使用此参数与使用 from_sort_value 参数互斥。

offset

(可选，整数) 基于与该请求匹配的快照，从该数字偏移量开始分页。使用此参数的非零值与使用 after 参数互斥。默认为 0。

slm_policy_filter

(可选，字符串) 按快照所属的逗号分隔的 SLM 策略名称列表筛选快照。还接受通配符 (\*) 以及通配符与以 - 开头的排除模式的组合。例如，模式 *,-policy-a-\* 将返回所有快照，除了由名称以 policy-a- 开头的 SLM 策略创建的快照。请注意，通配符模式 * 匹配由 SLM 策略创建的所有快照，但不匹配未由 SLM 策略创建的快照。要包含未由 SLM 策略创建的快照，可以使用特殊模式 _none，它将匹配所有没有 SLM 策略的快照。

参数 after 和 next 字段允许在快照之间进行迭代，并提供有关快照并发创建或删除的一些一致性保证。保证在迭代开始时存在的任何快照，如果未并发删除，将在迭代期间看到。并发创建的快照可能在迭代期间看到。

参数 size、order、after、from_sort_value、offset、slm_policy_filter 和 sort 在使用 verbose=false 时不受支持，并且使用 verbose=false 的请求的排序顺序是未定义的。

响应主体编辑

snapshot

(字符串) 快照的名称。

uuid

(字符串) 快照的通用唯一标识符 (UUID)。

version_id

(整数) 用于创建快照的 Elasticsearch 版本的构建 ID。

version

(浮点数) 用于创建快照的 Elasticsearch 版本。

indices

(数组) 快照中包含的索引列表。

index_details

(对象) 快照中每个索引的详细信息，按索引名称键控。仅在设置了 ?index_details 查询参数时才存在，并且仅包含在 Elasticsearch 的足够新版本中完全快照的索引的详细信息。

index_details 的属性

shard_count: (整数) 此索引中的分片数量。
size: (字符串) 此索引中所有分片的总大小。仅在设置了 ?human 查询参数时才存在。
size_in_bytes: (长整数) 此索引中所有分片的总大小（以字节为单位）。
max_segments_per_shard: (整数) 此索引快照中每个分片的最大段数。

data_streams

(字符串数组) 快照中包含的数据流列表。

include_global_state

(布尔值) 指示当前集群状态是否包含在快照中。

feature_states

(对象数组) 快照中的功能状态。仅当快照包含一个或多个功能状态时才存在。

features_states 对象的属性

feature_name: (字符串) 功能的名称，如获取功能 API 返回的名称。
indices: (字符串数组) 功能状态中的索引。

start_time

(字符串) 快照创建过程开始时的日期时间戳。

start_time_in_millis

(长整数) 快照创建过程开始时的毫秒数。

end_time

(字符串) 快照创建过程结束时的日期时间戳。

end_time_in_millis

(长整数) 快照创建过程结束时的毫秒数。

duration_in_millis

(长整数) 创建快照所需的时间（以毫秒为单位）。

failures

(数组) 列出创建快照时发生的任何错误。

shards

(对象) 包含快照中分片的数量。

shards 的属性

total: (整数) 快照中包含的分片总数。
successful: (整数) 成功包含在快照中的分片数量。
failed: (整数) 无法包含在快照中的分片数量。

state

(字符串) 快照 state 可以是以下值之一

state 的值

IN_PROGRESS: 快照当前正在运行。
SUCCESS: 快照已完成，所有分片都已成功存储。
FAILED: 快照已完成，但出现错误，无法存储任何数据。
PARTIAL: 全局集群状态已存储，但至少一个分片的數據未成功存储。响应的 failures 部分包含有关未正确处理的分片的更多详细信息。

next

(字符串) 如果请求包含大小限制，并且可能存在更多结果，则会在响应中添加一个 next 字段，可将其用作 after 查询参数以获取更多结果。

total

(整数) 忽略大小限制或 after 查询参数时，与请求匹配的快照总数。

remaining

(整数) 由于大小限制而未返回的剩余快照数量，可以通过使用 next 字段值的其他请求来获取这些快照。

示例编辑

以下请求返回 my_repository 存储库中 snapshot_2 的信息。

response = client.snapshot.get(
  repository: 'my_repository',
  snapshot: 'snapshot_2'
)
puts response

GET /_snapshot/my_repository/snapshot_2

API 返回以下响应

{
  "snapshots": [
    {
      "snapshot": "snapshot_2",
      "uuid": "vdRctLCxSketdKb54xw67g",
      "repository": "my_repository",
      "version_id": <version_id>,
      "version": <version>,
      "indices": [],
      "data_streams": [],
      "feature_states": [],
      "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
      }
    }
  ],
  "total": 1,
  "remaining": 0
}

以下请求返回 my_repository 存储库中所有以 snapshot 为前缀的快照的信息，将响应大小限制为 2，并按快照名称排序。

response = client.snapshot.get(
  repository: 'my_repository',
  snapshot: 'snapshot*',
  size: 2,
  sort: 'name'
)
puts response

GET /_snapshot/my_repository/snapshot*?size=2&sort=name

API 返回以下响应

{
  "snapshots": [
    {
      "snapshot": "snapshot_1",
      "uuid": "dKb54xw67gvdRctLCxSket",
      "repository": "my_repository",
      "version_id": <version_id>,
      "version": <version>,
      "indices": [],
      "data_streams": [],
      "feature_states": [],
      "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
      }
    },
    {
      "snapshot": "snapshot_2",
      "uuid": "vdRctLCxSketdKb54xw67g",
      "repository": "my_repository",
      "version_id": <version_id>,
      "version": <version>,
      "indices": [],
      "data_streams": [],
      "feature_states": [],
      "include_global_state": true,
      "state": "SUCCESS",
      "start_time": "2020-07-06T21:55:18.130Z",
      "start_time_in_millis": 1593093628851,
      "end_time": "2020-07-06T21:55:18.130Z",
      "end_time_in_millis": 1593094752019,
      "duration_in_millis": 1,
      "failures": [],
      "shards": {
        "total": 0,
        "failed": 0,
        "successful": 0
      }
    }
  ],
  "next": "c25hcHNob3RfMixteV9yZXBvc2l0b3J5LHNuYXBzaG90XzI=",
  "total": 3,
  "remaining": 1
}

然后可以使用先前响应中的 next 值作为 after 参数，对剩余快照发出后续请求。

response = client.snapshot.get(
  repository: 'my_repository',
  snapshot: 'snapshot*',
  size: 2,
  sort: 'name',
  after: 'c25hcHNob3RfMixteV9yZXBvc2l0b3J5LHNuYXBzaG90XzI='
)
puts response

GET /_snapshot/my_repository/snapshot*?size=2&sort=name&after=c25hcHNob3RfMixteV9yZXBvc2l0b3J5LHNuYXBzaG90XzI=

API 返回以下响应

{
  "snapshots": [
    {
      "snapshot": "snapshot_3",
      "uuid": "dRctdKb54xw67gvLCxSket",
      "repository": "my_repository",
      "version_id": <version_id>,
      "version": <version>,
      "indices": [],
      "data_streams": [],
      "feature_states": [],
      "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
      }
    }
  ],
  "total": 3,
  "remaining": 0
}

或者，可以通过使用 2 的偏移值来跳过已看到的两个快照，从而获得相同的结果。

response = client.snapshot.get(
  repository: 'my_repository',
  snapshot: 'snapshot*',
  size: 2,
  sort: 'name',
  offset: 2
)
puts response

GET /_snapshot/my_repository/snapshot*?size=2&sort=name&offset=2

API 返回以下响应

{
  "snapshots": [
    {
      "snapshot": "snapshot_3",
      "uuid": "dRctdKb54xw67gvLCxSket",
      "repository": "my_repository",
      "version_id": <version_id>,
      "version": <version>,
      "indices": [],
      "data_streams": [],
      "feature_states": [],
      "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
      }
    }
  ],
  "total": 3,
  "remaining": 0
}

以下请求返回 my_repository 存储库中所有以 snapshot 为前缀的快照的信息，但名为 snapshot_3 的快照除外。

response = client.snapshot.get(
  repository: 'my_repository',
  snapshot: 'snapshot*,-snapshot_3',
  sort: 'name'
)
puts response

GET /_snapshot/my_repository/snapshot*,-snapshot_3?sort=name

API 返回以下响应

{
  "snapshots": [
    {
      "snapshot": "snapshot_1",
      "uuid": "dKb54xw67gvdRctLCxSket",
      "repository": "my_repository",
      "version_id": <version_id>,
      "version": <version>,
      "indices": [],
      "data_streams": [],
      "feature_states": [],
      "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
      }
    },
    {
      "snapshot": "snapshot_2",
      "uuid": "vdRctLCxSketdKb54xw67g",
      "repository": "my_repository",
      "version_id": <version_id>,
      "version": <version>,
      "indices": [],
      "data_streams": [],
      "feature_states": [],
      "include_global_state": true,
      "state": "SUCCESS",
      "start_time": "2020-07-06T21:55:18.130Z",
      "start_time_in_millis": 1593093628851,
      "end_time": "2020-07-06T21:55:18.130Z",
      "end_time_in_millis": 1593094752019,
      "duration_in_millis": 1,
      "failures": [],
      "shards": {
        "total": 0,
        "failed": 0,
        "successful": 0
      }
    }
  ],
  "total": 2,
  "remaining": 0
}

以下请求返回按快照名称以默认升序排序时，在 snapshot_2 之后的所有快照的信息。

response = client.snapshot.get(
  repository: 'my_repository',
  snapshot: '*',
  sort: 'name',
  from_sort_value: 'snapshot_2'
)
puts response

GET /_snapshot/my_repository/*?sort=name&from_sort_value=snapshot_2

API 返回以下响应

{
  "snapshots": [
    {
      "snapshot": "snapshot_2",
      "uuid": "vdRctLCxSketdKb54xw67g",
      "repository": "my_repository",
      "version_id": <version_id>,
      "version": <version>,
      "indices": [],
      "data_streams": [],
      "feature_states": [],
      "include_global_state": true,
      "state": "SUCCESS",
      "start_time": "2020-07-06T21:55:18.130Z",
      "start_time_in_millis": 1593093628851,
      "end_time": "2020-07-06T21:55:18.130Z",
      "end_time_in_millis": 1593094752019,
      "duration_in_millis": 1,
      "failures": [],
      "shards": {
        "total": 0,
        "failed": 0,
        "successful": 0
      }
    },
    {
      "snapshot": "snapshot_3",
      "uuid": "dRctdKb54xw67gvLCxSket",
      "repository": "my_repository",
      "version_id": <version_id>,
      "version": <version>,
      "indices": [],
      "data_streams": [],
      "feature_states": [],
      "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
      }
    }
  ],
  "total": 2,
  "remaining": 0
}

以下请求返回所有名称以 snapshot_ 开头且在时间戳 1577833200000（2020 年 1 月 1 日）或之后开始的快照的信息，这些快照按快照开始时间以默认升序排序。

response = client.snapshot.get(
  repository: 'my_repository',
  snapshot: 'snapshot_*',
  sort: 'start_time',
  from_sort_value: 1_577_833_200_000
)
puts response

GET /_snapshot/my_repository/snapshot_*?sort=start_time&from_sort_value=1577833200000

API 返回以下响应

{
  "snapshots": [
    {
      "snapshot": "snapshot_1",
      "uuid": "dKb54xw67gvdRctLCxSket",
      "repository": "my_repository",
      "version_id": <version_id>,
      "version": <version>,
      "indices": [],
      "data_streams": [],
      "feature_states": [],
      "include_global_state": true,
      "state": "SUCCESS",
      "start_time": "2020-07-06T21:55:18.128Z",
      "start_time_in_millis": 1593093628849,
      "end_time": "2020-07-06T21:55:18.129Z",
      "end_time_in_millis": 1593093628850,
      "duration_in_millis": 1,
      "failures": [],
      "shards": {
        "total": 0,
        "failed": 0,
        "successful": 0
      }
    },
    {
      "snapshot": "snapshot_2",
      "uuid": "vdRctLCxSketdKb54xw67g",
      "repository": "my_repository",
      "version_id": <version_id>,
      "version": <version>,
      "indices": [],
      "data_streams": [],
      "feature_states": [],
      "include_global_state": true,
      "state": "SUCCESS",
      "start_time": "2020-07-06T21:55:18.130Z",
      "start_time_in_millis": 1593093628851,
      "end_time": "2020-07-06T21:55:18.130Z",
      "end_time_in_millis": 1593093628851,
      "duration_in_millis": 0,
      "failures": [],
      "shards": {
        "total": 0,
        "failed": 0,
        "successful": 0
      }
    },
    {
      "snapshot": "snapshot_3",
      "uuid": "dRctdKb54xw67gvLCxSket",
      "repository": "my_repository",
      "version_id": <version_id>,
      "version": <version>,
      "indices": [],
      "data_streams": [],
      "feature_states": [],
      "include_global_state": true,
      "state": "SUCCESS",
      "start_time": "2020-07-06T21:55:18.131Z",
      "start_time_in_millis": 1593093628852,
      "end_time": "2020-07-06T21:55:18.135Z",
      "end_time_in_millis": 1593093628856,
      "duration_in_millis": 4,
      "failures": [],
      "shards": {
        "total": 0,
        "failed": 0,
        "successful": 0
      }
    }
  ],
  "total": 3,
  "remaining": 0
}

« 创建快照 API 获取快照状态 API »