› › ›

获取快照 API

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

resp = client.snapshot.get(
    repository="my_repository",
    snapshot="my_snapshot",
)
print(resp)

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

const response = await client.snapshot.get({
  repository: "my_repository",
  snapshot: "my_snapshot",
});
console.log(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 字段允许遍历快照，并对快照的并发创建或删除提供一些一致性保证。保证在迭代开始时存在且未并发删除的任何快照都将在迭代期间被看到。在迭代期间可能会看到并发创建的快照。

当使用 verbose=false 时，不支持参数 size、order、after、from_sort_value、offset、slm_policy_filter 和 sort，并且 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 的信息。

resp = client.snapshot.get(
    repository="my_repository",
    snapshot="snapshot_2",
)
print(resp)

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

const response = await client.snapshot.get({
  repository: "my_repository",
  snapshot: "snapshot_2",
});
console.log(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 并按快照名称排序。

resp = client.snapshot.get(
    repository="my_repository",
    snapshot="snapshot*",
    size="2",
    sort="name",
)
print(resp)

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

const response = await client.snapshot.get({
  repository: "my_repository",
  snapshot: "snapshot*",
  size: 2,
  sort: "name",
});
console.log(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 参数，来请求剩余的快照。

resp = client.snapshot.get(
    repository="my_repository",
    snapshot="snapshot*",
    size="2",
    sort="name",
    after="c25hcHNob3RfMixteV9yZXBvc2l0b3J5LHNuYXBzaG90XzI=",
)
print(resp)

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

const response = await client.snapshot.get({
  repository: "my_repository",
  snapshot: "snapshot*",
  size: 2,
  sort: "name",
  after: "c25hcHNob3RfMixteV9yZXBvc2l0b3J5LHNuYXBzaG90XzI=",
});
console.log(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 来跳过已经看到的两个快照，从而获得相同的结果。

resp = client.snapshot.get(
    repository="my_repository",
    snapshot="snapshot*",
    size="2",
    sort="name",
    offset="2",
)
print(resp)

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

const response = await client.snapshot.get({
  repository: "my_repository",
  snapshot: "snapshot*",
  size: 2,
  sort: "name",
  offset: 2,
});
console.log(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 的快照。

resp = client.snapshot.get(
    repository="my_repository",
    snapshot="snapshot*,-snapshot_3",
    sort="name",
)
print(resp)

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

const response = await client.snapshot.get({
  repository: "my_repository",
  snapshot: "snapshot*,-snapshot_3",
  sort: "name",
});
console.log(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 之后的所有快照的信息。

resp = client.snapshot.get(
    repository="my_repository",
    snapshot="*",
    sort="name",
    from_sort_value="snapshot_2",
)
print(resp)

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

const response = await client.snapshot.get({
  repository: "my_repository",
  snapshot: "*",
  sort: "name",
  from_sort_value: "snapshot_2",
});
console.log(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 日) 或之后开始的所有快照的信息，这些快照按快照开始时间的默认升序排序。

resp = client.snapshot.get(
    repository="my_repository",
    snapshot="snapshot_*",
    sort="start_time",
    from_sort_value="1577833200000",
)
print(resp)

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

const response = await client.snapshot.get({
  repository: "my_repository",
  snapshot: "snapshot_*",
  sort: "start_time",
  from_sort_value: 1577833200000,
});
console.log(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 »