« Security APIs Snapshot lifecycle management APIs »
Elastic Docs ›Elasticsearch Guide ›REST APIs

快照与恢复API

edit

快照和恢复API

edit

您可以使用以下API来设置快照仓库、管理快照备份，并将快照恢复到正在运行的集群中。

更多信息，请参阅快照和恢复。

快照仓库管理API

edit

快照管理API

edit

创建或更新快照仓库 API

edit

注册或更新一个快照仓库。

PUT /_snapshot/my_repository
{
  "type": "fs",
  "settings": {
    "location": "my_backup_location"
  }
}

如果您正在迁移可搜索快照，源集群和目标集群中的存储库名称必须相同。

请求

edit

PUT /_snapshot/

POST /_snapshot/

先决条件

edit
  • 如果启用了Elasticsearch安全功能，您必须拥有manage 集群权限才能使用此API。
  • 要注册快照仓库，集群的全局元数据必须是可写的。确保没有阻止写访问的集群块。

路径参数

edit
<repository>
(必需，字符串) 要注册或更新的快照仓库的名称。

查询参数

edit

此API的几个选项可以通过查询参数或请求体参数来指定。如果同时指定了这两个参数，则仅使用查询参数。

master_timeout
(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。 也可以设置为-1，表示请求不应超时。
timeout
(可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。 如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。 默认为 30s。 也可以设置为 -1 以指示请求不应超时。
verify

(可选，布尔值) 如果true，请求会验证仓库在集群中的所有主节点和数据节点上是否功能正常。如果false，则跳过此验证。默认为true。

您可以手动使用 验证快照仓库 API执行此验证。

请求体

edit
type

(必需, 字符串) 仓库类型。

有效值为 type
azure
Azure 仓库
gcs
Google Cloud Storage 仓库
s3
S3 仓库
fs
共享文件系统仓库
source
仅源仓库
url
只读 URL 仓库

其他仓库类型可通过官方插件获得：

hdfs
Hadoop 分布式文件系统 (HDFS) 仓库
settings

（必需，对象） 存储库的设置。支持的设置因存储库类型而异：

其他仓库类型可通过官方插件获得：

verify

(可选，布尔值) 如果为true，请求将验证仓库在集群中的所有主节点和数据节点上是否功能正常。如果为false，则跳过此验证。默认为true。

您可以手动执行此验证，使用验证快照仓库 API。

验证快照仓库 API

edit

检查快照仓库中的常见错误配置。请参阅 验证仓库。

POST /_snapshot/my_repository/_verify

请求

edit

POST /_snapshot//_verify

先决条件

edit
  • 如果启用了Elasticsearch安全功能，您必须拥有manage 集群权限才能使用此API。

路径参数

edit
<repository>
(必需，字符串) 要验证的快照仓库的名称。

查询参数

edit
master_timeout
(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。 也可以设置为-1，表示请求不应超时。
timeout
(可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。 如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。 默认为 30s。 也可以设置为 -1 以指示请求不应超时。

响应体

edit
nodes

(对象)

Properties of nodes objects

(对象) 包含有关连接到快照存储库的节点的信息。

关键字是节点的ID。

Properties of
name

(字符串) 节点的人类可读名称。

您可以使用 node.name 属性在 elasticsearch.yml 中设置此名称。默认为机器的主机名。

仓库分析 API

edit

分析一个仓库，报告其性能特征和发现的任何不正确行为。

POST /_snapshot/my_repository/_analyze?blob_count=10&max_blob_size=1mb&timeout=120s

请求

edit

POST /_snapshot//_analyze

先决条件

edit
  • 如果启用了Elasticsearch安全功能，您必须拥有manage 集群权限才能使用此API。更多信息，请参阅安全权限。

描述

edit

有许多第三方存储系统可供选择，但并非所有都适合用作Elasticsearch的快照存储库。某些存储系统在行为上存在问题，或者性能较差，尤其是在Elasticsearch集群的节点同时访问时。

Repository analysis API 对您的仓库执行一系列读写操作，旨在检测不正确的行为并测量存储系统的性能特征。

此API的参数默认值故意设置得较低，以减少无意中运行分析的影响，并为您的调查提供一个合理的起点。首先使用默认参数值运行您的第一次分析，以检查简单问题。如果成功，则运行一系列逐渐增大的分析，直到遇到失败或达到至少2000的blob_count，至少2gb的max_blob_size，至少1tb的max_total_data_size，以及至少100的register_operation_count。始终指定一个慷慨的超时时间，可能为1h或更长，以允许每次分析运行完成。使用与生产集群大小相似的多节点集群执行分析，以便它可以检测到仅在仓库被多个节点同时访问时才会出现的问题。

如果分析失败，则 Elasticsearch 检测到您的存储库行为异常。这通常意味着您正在使用第三方存储系统，该系统对其声称的 API 支持的实现不正确或不兼容。如果是这样，该存储系统不适合用作快照存储库。您需要与您的存储系统供应商合作，解决 Elasticsearch 检测到的不兼容问题。有关更多信息，请参阅 自管理存储库类型。

如果分析成功，此API将返回测试过程的详细信息，可选地包括每个操作花费的时间。您可以使用此信息来确定存储系统的性能。如果任何操作失败或返回错误结果，此API将返回一个错误。如果API返回错误，则可能未删除其写入存储库的所有数据。错误将指示任何剩余数据的位置，并且此路径也会记录在Elasticsearch日志中。您应自行验证此位置是否已正确清理。如果指定位置仍有剩余数据，则应手动删除它。

如果从您的客户端到 Elasticsearch 的连接在客户端等待分析结果时关闭，则测试将被取消。某些客户端配置为在未在特定超时内收到响应时关闭其连接。分析需要很长时间才能完成，因此您可能需要放宽此类客户端侧的超时设置。在取消时，分析尝试清理它正在写入的数据，但它可能无法全部删除。残留数据的路径记录在 Elasticsearch 日志中。您应自行验证此位置是否已正确清理。如果指定位置仍有残留数据，则应手动删除它。

如果分析成功，则表明未检测到不正确的行为，但这并不意味着正确的行为得到了保证。分析尝试检测常见错误，但它当然不能提供100%的覆盖率。此外，它不测试以下内容：

  • 您的存储库必须执行持久写入。一旦一个blob被写入，它必须保持在原位，直到被删除，即使在断电或类似灾难之后。
  • 您的存储库不得遭受静默数据损坏。一旦一个blob被写入，其内容必须保持不变，直到被故意修改或删除。
  • 即使集群的连接性中断，您的存储库也必须正确运行。在这种情况下，读取和写入可能会失败，但它们不得返回错误的结果。

分析会将大量数据写入您的存储库，然后再次读取这些数据。这会消耗集群与存储库之间网络的带宽，以及存储库本身的存储空间和IO带宽。您必须确保这种负载不会影响这些系统的其他用户。分析会尊重存储库设置max_snapshot_bytes_per_sec和max_restore_bytes_per_sec（如果可用），以及集群设置indices.recovery.max_bytes_per_sec，您可以使用这些设置来限制它们消耗的带宽。

此API旨在供人类进行探索性使用。您应预期请求参数和响应格式在未来的版本中会有所变化。

不同版本的 Elasticsearch 可能会对存储库兼容性执行不同的检查，通常新版本比旧版本更为严格。一个在某个版本的 Elasticsearch 下通过存储库分析的存储系统，在不同版本下可能会失败。这表明它在某些方面表现不正确，而前一个版本未能检测到这些问题。您必须与存储系统的供应商合作，解决在任何版本的 Elasticsearch 中由存储库分析 API 检测到的兼容性问题。

此 API 在混合版本集群中可能无法正常工作。

实现细节

edit

本节文档描述了在此版本的Elasticsearch中，Repository分析API的工作原理，但您应该预期其实现在不同版本之间会有所不同。请求参数和响应格式取决于实现的细节，因此在较新的版本中也可能有所不同。

分析包括由blob_count参数设置的多个blob级别任务，以及由register_operation_count参数设置的线性化寄存器上的多个比较和交换操作。这些任务分布在集群中的数据节点和符合主节点资格的节点上执行。

对于大多数 blob 级任务，执行节点首先将一个 blob 写入存储库，然后指示集群中的其他一些节点尝试读取它刚刚写入的数据。blob 的大小是根据 max_blob_size 和 max_total_data_size 参数随机选择的。如果这些读取中的任何一个失败，则存储库没有实现 Elasticsearch 所需的必要的读后写语义。

对于某些块级任务，执行节点将指示其部分对等节点在写入过程完成之前尝试读取数据。这些读取操作允许失败，但不得返回部分数据。如果任何读取操作返回部分数据，则该存储库未实现Elasticsearch所需的必要原子性语义。

对于某些blob级别的任务，执行节点在其他节点读取该blob时会覆盖它。在这种情况下，读取的数据可能来自原始blob或覆盖后的blob，但读取操作不能返回部分数据或两者的混合数据。如果任何这些读取操作返回了部分数据或两者的混合数据，则该存储库未实现Elasticsearch所需的覆盖操作所需的必要原子性语义。

执行节点将使用多种不同的方法来写入blob。例如，在适用的情况下，它将使用单部分和多部分上传。同样，读取节点将使用多种不同的方法来读取数据。例如，它们可能会从头到尾读取整个blob，或者可能只读取数据的一个子集。

对于某些块级任务，执行节点将在写入完成之前中止写入。在这种情况下，它仍然指示集群中的其他一些节点尝试读取该块，但所有这些读取都必须失败，无法找到该块。

线性可序列化寄存器是Elasticsearch使用原子比较和交换操作操作的特殊blob。此操作确保即使在多个节点同时访问blob时也能正确且强一致的行为。线性可序列化寄存器上的比较和交换操作的详细实现因存储库类型而异。存储库分析验证了在无争用情况下对线性可序列化寄存器blob的比较和交换操作总是成功。存储库分析还验证了争用操作要么成功，要么报告争用情况，但不会返回错误的结果。如果由于争用导致操作失败，Elasticsearch会重试操作直到成功。存储库分析执行的大多数比较和交换操作都会原子性地增加一个计数器，该计数器表示为一个8字节的blob。一些操作还会验证在其他非8字节大小的较小blob上的行为。

路径参数

edit
<repository>
(必需，字符串) 要测试的快照仓库的名称。

查询参数

edit
blob_count
(可选，整数) 在测试期间写入仓库的 blob 总数。默认为 100。为了进行真实的实验，您应将其设置为至少 2000。
max_blob_size
(可选, 大小单位) 测试期间要写入的 blob 的最大大小。默认为 10mb。对于真实的实验，您应将其设置为至少 2gb。
max_total_data_size
(可选, 大小单位) 测试期间写入的所有blob的总大小的上限。默认为1gb。对于现实实验，您应将其设置为至少1tb。
register_operation_count
(可选，整数) 总共要执行的最少线性化寄存器操作次数。默认为 10。为了进行实际的实验，您应将其设置为至少 100。
timeout
(可选，时间单位) 指定等待测试完成的时间段。如果在超时到期之前未收到响应，则测试将被取消并返回错误。默认为 30s。

高级查询参数

edit

以下参数允许对分析进行额外控制，但您通常不需要调整它们。

concurrency
(可选，整数) 并发执行的写操作数量。 默认为 10。
read_node_count
(可选，整数) 在写入每个 blob 后执行读操作的节点数量。默认为 10。
early_read_node_count
(可选，整数) 在写入每个 blob 时，执行早期读取操作的节点数量。默认为 2。早期读取操作很少执行。
rare_action_probability
(可选，双精度) 每个 blob 执行罕见操作（早期读取、覆盖或中止写入）的概率。默认为 0.02。
seed
(可选，整数) 用于生成测试期间执行的操作列表的伪随机数生成器的种子。要在多次实验中重复相同的操作集，请在每次实验中使用相同的种子。请注意，操作是并发执行的，因此在每次运行中可能不会以相同的顺序发生。
detailed
(可选，布尔值) 是否返回详细结果，包括分析过程中每个操作的计时信息。默认为 false，表示仅返回分析的摘要。
rarely_abort_writes
(可选，布尔值) 是否很少中止一些写请求。默认为 true。

响应体

edit

响应暴露了分析的实现细节，这些细节可能会随着版本的变化而变化。因此，响应体格式不被认为是稳定的，在较新的版本中可能会有所不同。

coordinating_node

(对象) 标识协调分析并执行最终清理的节点。

Properties of coordinating_node
id
(字符串) 协调节点的ID。
name
(字符串) 协调节点的名称
repository
(字符串) 被分析的仓库的名称。
blob_count
(整数) 测试期间写入仓库的blob数量，等于 ?blob_count 请求参数。
concurrency
(整数) 测试期间同时执行的写操作数量，等于 ?concurrency 请求参数。
read_node_count
(整数) 在写入每个blob后执行读操作的节点数量限制，等于?read_node_count请求参数。
early_read_node_count
(整数) 在写入每个blob后，执行早期读操作的节点数量限制，等于?early_read_node_count请求参数。
max_blob_size
(字符串) 测试期间写入的blob大小的限制，等于 ?max_blob_size 参数。
max_blob_size_bytes
(长整型) 在测试期间写入的blob的大小限制，以字节为单位，等于 ?max_blob_size 参数。
max_total_data_size
(字符串) 测试期间写入的所有blob的总大小限制，等于 ?max_total_data_size 参数。
max_total_data_size_bytes
(长整型) 在测试期间写入的所有blob的总大小限制，以字节为单位， 等于?max_total_data_size参数。
seed
(长整型) 用于生成测试期间使用的操作的伪随机数生成器的种子。如果设置了，等于?seed请求参数。
rare_action_probability
(双精度) 测试期间执行罕见操作的概率。等于 ?rare_action_probability 请求参数。
blob_path
(字符串) 在测试期间，所有blob写入的仓库中的路径。
issues_detected
(列表) 检测到的正确性问题列表，如果API成功，则此列表为空。包含此项是为了强调，成功的响应并不保证未来的行为正确。
summary

(对象) 总结测试结果的统计数据集合。

Properties of summary
write

(对象) 一个汇总了测试中写操作结果的统计数据集合。

Properties of write
count
(整数) 测试中执行的写操作次数。
total_size
(字符串) 测试中所有写入的blob的总大小。
total_size_bytes
(长整型) 测试中所有写入的blob的总大小，以字节为单位。
total_throttled
(字符串) 由于max_snapshot_bytes_per_sec限制而等待的总时间。
total_throttled_nanos
(长整型) 由于max_snapshot_bytes_per_sec限制而等待的总时间，以纳秒为单位。
total_elapsed
(字符串) 测试中写入blob所花费的总时间。
total_elapsed_nanos
(长整型) 测试中写入blob所花费的总时间，以纳秒为单位。
read

(对象) 一组统计数据，总结了测试中读操作的结果。

Properties of read
count
(整数) 测试中执行的读操作次数。
total_size
(字符串) 测试中所有读取的blob或部分blob的总大小。
total_size_bytes
(长整型) 测试中所有读取的blob或部分blob的总大小，以字节为单位。
total_wait
(字符串) 等待每个读请求的第一个字节接收所花费的总时间。
total_wait_nanos
(长整型) 等待每个读请求的第一个字节接收所花费的总时间，以纳秒为单位。
max_wait
(字符串) 等待任何读请求的第一个字节接收所花费的最大时间。
max_wait_nanos
(长整型) 等待任何读请求的第一个字节接收所花费的最大时间，以纳秒为单位。
total_throttled
(字符串) 由于max_restore_bytes_per_sec或indices.recovery.max_bytes_per_sec限制而等待的总时间。
total_throttled_nanos
(长整型) 由于max_restore_bytes_per_sec或indices.recovery.max_bytes_per_sec限制而等待的总时间，以纳秒为单位。
total_elapsed
(字符串) 测试中读取blob所花费的总时间。
total_elapsed_nanos
(长整型) 测试中读取blob所花费的总时间，以纳秒为单位。
details

(数组) 测试期间执行的每个读取和写入操作的描述。仅当?detailed请求参数设置为true时，才会返回此内容。

Properties of items within details
blob

(对象) 对写入和读取的blob的描述。

Properties of blob
name
(字符串) blob的名称。
size
(字符串) blob的大小。
size_bytes
(长整型) blob的大小，以字节为单位。
read_start
(长整型) 读操作开始的位置，以字节为单位。
read_end
(长整型) 读操作完成的位置，以字节为单位。
read_early
(布尔值) 是否在写操作完成之前开始任何读操作。
overwritten
(布尔值) 在读操作进行期间，blob是否被覆盖。
writer_node

(对象) 标识写入此blob并协调读操作的节点。

Properties of writer_node
id
(字符串) 写入节点的ID。
name
(字符串) 写入节点的名称
write_elapsed
(字符串) 写入此blob所花费的经过时间。
write_elapsed_nanos
(长整型) 写入此blob所花费的经过时间，以纳秒为单位。
overwrite_elapsed
(字符串) 覆盖此blob所花费的经过时间。如果blob未被覆盖，则省略。
overwrite_elapsed_nanos
(长整型) 覆盖此blob所花费的经过时间，以纳秒为单位。如果blob未被覆盖，则省略。
write_throttled
(字符串) 在写入此blob时，等待max_snapshot_bytes_per_sec（或 indices.recovery.max_bytes_per_sec，如果 托管服务的恢复设置 已设置）节流所花费的时间。
write_throttled_nanos
(长整型) 在写入此blob时，等待max_snapshot_bytes_per_sec（或 indices.recovery.max_bytes_per_sec，如果 托管服务的恢复设置 已设置）节流所花费的时间，以纳秒为单位。
reads

(数组) 对此blob执行的每个读取操作的描述。

Properties of items within reads
node

(对象) 标识执行读操作的节点。

Properties of node
id
(字符串) 读取节点的ID。
name
(字符串) 读取节点的名称
before_write_complete
(布尔值) 读操作是否可能在写操作完成之前开始。如果为false，则省略。
found
(布尔值) 此读操作是否找到了blob。如果读操作在写操作完成之前开始，或者写操作在完成之前中止，则可能为false。
first_byte_time
(字符串) 等待读操作的第一个字节接收所花费的时间。如果未找到blob，则省略。
first_byte_time_nanos
(长整型) 等待读操作的第一个字节接收所花费的时间，以纳秒为单位。如果未找到blob，则省略。
elapsed
(字符串) 读取此blob所花费的时间。如果未找到blob，则省略。
elapsed_nanos
(长整型) 读取此blob所花费的时间，以纳秒为单位。如果未找到blob，则省略。
throttled
(字符串) 在读取此blob期间，由于max_restore_bytes_per_sec或 indices.recovery.max_bytes_per_sec节流所花费的等待时间。如果未找到blob，则省略。
throttled_nanos
(长整型) 在读取此blob期间，由于max_restore_bytes_per_sec或 indices.recovery.max_bytes_per_sec节流所花费的等待时间，以纳秒为单位。如果未找到blob，则省略。
listing_elapsed
(字符串) 检索容器中所有blob列表所花费的时间。
listing_elapsed_nanos
(长整型) 获取容器中所有blob列表所花费的时间，以纳秒为单位。
delete_elapsed
(字符串) 删除容器中所有blob所需的时间。
delete_elapsed_nanos
(长整型) 删除容器中所有blob所花费的时间，以纳秒为单位。

验证仓库完整性 API

edit

验证快照存储库内容的完整性。

POST /_snapshot/my_repository/_verify_integrity

请求

edit

POST /_snapshot//_verify_integrity

先决条件

edit
  • 如果启用了Elasticsearch安全功能，您必须拥有manage 集群权限才能使用此API。更多信息，请参阅安全权限。

描述

edit

此API允许您对存储库的内容进行全面检查，查找其数据或元数据中的任何异常，这些异常可能会阻止您从存储库中恢复快照，或者可能导致未来的快照创建或删除操作失败。

如果您怀疑某个快照仓库的内容的完整性，请立即停止对该仓库的所有写入操作，将其read_only选项设置为true，并使用此API验证其完整性。在此之前：

  • 可能无法从该存储库中恢复某些快照。
  • 可搜索的快照在搜索时可能会报告错误，或者可能存在未分配的分片。
  • 将快照存储到此存储库可能会失败，或者可能会成功创建一个无法恢复的快照。
  • 从此存储库中删除快照可能会失败，或者可能会成功删除，但底层数据仍保留在磁盘上。
  • 在存储库处于无效状态时继续写入可能会对其内容造成额外损坏。

如果 验证仓库完整性 API 发现仓库内容存在任何完整性问题，Elasticsearch 将无法修复损坏。 恢复仓库内容至完全工作状态的唯一方法是，从损坏发生前创建的 仓库备份 中恢复其内容。您还必须识别导致损坏的原因，并采取措施防止其再次发生。

如果你无法恢复仓库备份， 注册一个新的仓库并将其用于所有未来的快照操作。在某些情况下，可能可以通过 恢复尽可能多的快照并 对恢复的数据进行新的快照，或者使用 Reindex API 从任何从损坏的仓库挂载的 可搜索的快照中复制数据，来恢复部分损坏仓库的内容。

在运行验证仓库完整性 API 时，避免所有对仓库进行写操作的操作。如果在完整性验证运行期间，某些操作改变了仓库内容，Elasticsearch 可能会错误地报告检测到某些内容异常，这是由于并发写入导致的。它也可能错误地未能报告某些异常，这些异常是由于并发写入阻止了其检测。

此API旨在供人类进行探索性使用。您应预期请求参数和响应格式在未来的版本中会有所变化。

此 API 在混合版本集群中可能无法正常工作。

路径参数

edit
<repository>
(必需，字符串) 要验证其完整性的快照仓库的名称。

查询参数

edit

此API的参数默认值旨在限制完整性验证对集群中其他活动的影响。例如，默认情况下，它最多只会使用一半的snapshot_meta线程来验证每个快照的完整性，从而允许其他快照操作使用该线程池的另一半。

如果您修改这些参数以加快验证过程，可能会破坏集群中其他与快照相关的操作。对于大型存储库，建议设置一个单独的单节点 Elasticsearch 集群，专门用于运行完整性验证 API。

snapshot_verification_concurrency
(可选，整数) 指定同时验证的快照数量。 默认为 0，表示一次最多使用 snapshot_meta 线程池的一半。
index_verification_concurrency
(可选，整数) 指定同时验证的索引数量。 默认为 0，表示使用整个 snapshot_meta 线程池。
meta_thread_pool_concurrency
(可选，整数) 指定要并发执行的最大快照元数据操作数。默认为 0，表示一次最多使用 snapshot_meta 线程池的一半。
index_snapshot_verification_concurrency
(可选，整数) 指定每个索引验证中并发验证的最大索引快照数量。默认为 1。
max_failed_shard_snapshots
(可选，整数) 限制在完整性验证期间跟踪的分片快照失败的数量，以避免过度使用资源。如果你的仓库中包含超过此数量的分片快照失败，则验证将失败。默认为 10000。
verify_blob_contents
(可选，布尔值) 指定是否验证仓库中每个数据块的校验和。默认为 false。如果启用此功能，Elasticsearch 将读取整个仓库内容，这可能会非常慢且耗费资源。
blob_thread_pool_concurrency
(可选, 整数) 如果 ?verify_blob_contents 是 true, 这个参数 指定一次验证多少个blob。默认为 1。
max_bytes_per_sec
(可选, 大小单位) 如果 ?verify_blob_contents 为 true，此参数指定 Elasticsearch 每秒从存储库读取的最大数据量。默认为 10mb。

响应体

edit

响应暴露了分析的实现细节，这些细节可能会随着版本的变化而变化。因此，响应体格式不被认为是稳定的，在较新的版本中可能会有所不同。

log

(数组) 报告分析进度的对象序列。

Properties of log
timestamp_in_millis
(整数) 此日志条目的时间戳，表示为自Unix纪元以来的毫秒数。
timestamp
(字符串) 此日志条目的时间戳，表示为根据ISO 8601格式化的字符串。仅当设置了?human标志时才包含。
snapshot
(对象) 如果日志条目与特定快照相关，则此对象中将描述该快照。
index
(对象) 如果日志条目与特定索引相关，则此对象中将描述该索引。
snapshot_restorability
(对象) 如果日志条目与索引的可恢复性相关，则此对象中将描述详细信息。
anomaly
(字符串) 如果日志条目与存储库内容中的异常相关，则此字符串将描述该异常。
exception
(对象) 如果日志条目与Elasticsearch在验证过程中遇到的异常相关，则此对象中将包含详细信息。
results

(对象) 描述分析最终结果的对象。

Properties of results
status
(对象) 分析任务的最终状态。
final_repository_generation
(整数) 分析结束时的仓库生成。如果在分析过程中对仓库进行了任何写操作，则此值将与任务状态中报告的generation不同，并且分析可能由于并发写操作而检测到虚假异常，或者可能未能检测到仓库内容中的一些异常。
total_anomalies
(整数) 分析过程中检测到的异常总数。
result
(字符串) 分析的最终结果。如果仓库内容看起来是完整的，则这将是字符串pass。如果此字段缺失，或者包含其他值，则仓库内容未完全验证。
exception
(对象) 如果分析过程中遇到异常，导致无法成功完成，则此异常将在此处报告。

获取快照仓库 API

edit

获取有关一个或多个已注册的 快照仓库的信息。

GET /_snapshot/my_repository

请求

edit

GET /_snapshot/

GET /_snapshot

先决条件

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

路径参数

edit
<repository>

(可选，字符串) 用于限制请求的快照仓库名称的逗号分隔列表。 支持通配符 (*) 表达式，包括结合以 - 开头的排除模式的通配符。

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

查询参数

edit
local
(可选，布尔值) 如果 true，请求仅从本地节点获取信息。如果 false，请求从主节点获取信息。默认为 false。
master_timeout
(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。 也可以设置为-1，表示请求不应超时。

响应体

edit
<repository>

(对象) 包含有关快照仓库的信息。键是快照仓库的名称。

Properties of
type

(字符串) 仓库类型。

Values for type
fs
共享文件系统仓库。参见 共享文件系统仓库。
source
仅源仓库。参见 仅源仓库。
url
URL 仓库。参见 只读 URL 仓库。

更多仓库类型可通过以下官方插件获得：

settings

(对象) 包含存储库的设置。settings 对象的有效属性取决于使用 type 参数设置的存储库类型。

有关属性，请参阅创建或更新快照仓库 API的settings参数。

示例

edit
GET /_snapshot/my_repository

API返回以下响应：

{
  "my_repository" : {
    "type" : "fs",
    "uuid" : "0JLknrXbSUiVPuLakHjBrQ",
    "settings" : {
      "location" : "my_backup_location"
    }
  }
}

删除快照仓库 API

edit

注销一个或多个快照仓库。

当一个仓库被注销时，Elasticsearch仅移除对该仓库存储快照位置的引用。快照本身不会被触动，仍然保留在原位。

DELETE /_snapshot/my_repository

请求

edit

DELETE /_snapshot/

先决条件

edit
  • 如果启用了Elasticsearch安全功能，您必须拥有manage 集群权限才能使用此API。

路径参数

edit
<repository>
(必需，字符串) 要注销的快照仓库的名称。支持通配符 (*) 模式。

查询参数

edit
master_timeout
(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。 也可以设置为-1，表示请求不应超时。
timeout
(可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。 如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。 默认为 30s。 也可以设置为 -1 以指示请求不应超时。

清理快照仓库 API

edit

触发快照仓库内容的审查，并删除任何未被现有快照引用的陈旧数据。请参阅 清理仓库。

POST /_snapshot/my_repository/_cleanup

请求

edit

POST /_snapshot//_cleanup

前提条件

edit
  • 如果启用了Elasticsearch安全功能，您必须拥有manage 集群权限才能使用此API。

路径参数

edit
<repository>
(必需，字符串) 要查看和清理的快照仓库的名称。

查询参数

edit
master_timeout
(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。 也可以设置为-1，表示请求不应超时。
timeout
(可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。 如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。 默认为 30s。 也可以设置为 -1 以指示请求不应超时。

响应体

edit
results

(对象) 包含清理操作的统计信息。

Properties of results
deleted_bytes
(整数) 清理操作释放的字节数。
deleted_blobs
(整数) 在清理操作期间从快照仓库中删除的二进制大对象（blobs）的数量。 任何非零值都意味着发现了未引用的 blobs 并随后进行了清理。

示例

edit
POST /_snapshot/my_repository/_cleanup

API返回以下响应：

{
  "results": {
    "deleted_bytes": 20,
    "deleted_blobs": 5
  }
}

克隆快照 API

edit

克隆部分或全部快照到一个新的快照中。

PUT /_snapshot/my_repository/source_snapshot/_clone/target_snapshot
{
  "indices": "index_a,index_b"
}

请求

edit

PUT /_snapshot///_clone/

先决条件

edit
  • 如果启用了Elasticsearch安全功能，您必须拥有manage 集群权限才能使用此API。

描述

edit

克隆快照API允许在同一仓库中创建现有快照的全部或部分副本。

路径参数

edit
<repository>
(必需，字符串) 源快照和目标快照所属的快照仓库的名称。

查询参数

edit
master_timeout
(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。 也可以设置为-1，表示请求不应超时。
timeout
(可选，时间单位) 指定等待响应的时间段。如果在超时到期之前未收到响应，请求将失败并返回错误。默认为 30s。
indices
(必需，字符串) 一个以逗号分隔的索引列表，用于包含在快照中。 多目标语法 是被支持的。

创建快照 API

edit

创建快照 一个集群或指定的数据流和索引。

PUT /_snapshot/my_repository/my_snapshot

请求

edit

PUT /_snapshot//

POST /_snapshot//

先决条件

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

路径参数

edit
<repository>
(必需，字符串) 快照仓库的名称。
<snapshot>
(必需, 字符串) 快照的名称。支持 日期数学。必须在快照仓库中唯一。

查询参数

edit
master_timeout
(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。 也可以设置为-1，表示请求不应超时。
wait_for_completion
(可选，布尔值) 如果 true，请求在快照完成时返回响应。如果 false，请求在快照初始化时返回响应。默认为 false。

请求体

edit
expand_wildcards

(可选，字符串) 确定通配符模式在 indices 参数中如何匹配数据流和索引。支持逗号分隔的值，例如 open,hidden。默认为 all。有效值包括：

all
匹配任何数据流或索引，包括关闭的和隐藏的。
open
匹配开放的索引和数据流。
closed
匹配关闭的索引和数据流。
hidden
匹配隐藏的数据流和索引。必须与 open、closed 或两者结合使用。
none
不扩展通配符模式。
ignore_unavailable
(可选，布尔值) 如果为false，当indices中的任何数据流或索引缺失时，快照将失败。如果为true，快照将忽略缺失的数据流和索引。默认为false。
include_global_state

(可选，布尔值) 如果为true，则在快照中包含集群状态。默认为true。 集群状态包括：

indices

(可选，字符串或字符串数组) 逗号分隔的数据流和索引列表，包含在快照中。 支持多目标语法。默认为空数组 ([])，包含所有常规数据流和常规索引。要排除 所有数据流和索引，请使用-*。

您不能使用此参数来包含或排除系统索引或系统数据流从快照中。请改用feature_states。

feature_states

(可选，字符串数组) 要包含在快照中的功能状态。要获取可能的值及其描述的列表，请使用获取功能API。

如果 include_global_state 为 true，快照默认包含所有特征状态。如果 include_global_state 为 false，快照默认不包含任何特征状态。

请注意，指定一个空数组将导致默认行为。要排除所有特征状态，无论include_global_state的值如何，请指定一个仅包含值none的数组（["none"]）。

metadata
(可选, 对象) 附加任意元数据到快照，例如记录谁拍摄了快照、拍摄的原因或任何其他有用的数据。元数据必须小于1024字节。
partial

(可选，布尔值) 如果为false，则如果快照中包含的一个或多个索引没有所有主分片可用，整个快照将失败。默认为false。

如果为true，允许对包含不可用分片的索引进行部分快照。

示例

edit

以下请求对index_1和index_2进行快照。

PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=true
{
  "indices": "index_1,index_2",
  "ignore_unavailable": true,
  "include_global_state": false,
  "metadata": {
    "taken_by": "user123",
    "taken_because": "backup before upgrading"
  }
}

API返回以下响应：

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

获取快照 API

edit

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

GET /_snapshot/my_repository/my_snapshot

请求

edit

GET /_snapshot//

先决条件

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

路径参数

edit
<repository>

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

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

<snapshot>

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

  • 要获取有关注册仓库中所有快照的信息，请使用通配符 (*) 或 _all。

  • 要获取有关当前正在运行的任何快照的信息，请使用 _current。

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

查询参数

edit
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 的请求，排序顺序是未定义的。

响应体

edit
snapshot
(字符串) 快照的名称。
uuid
(字符串) 快照的通用唯一标识符 (UUID)。
version_id
(整数) 用于创建快照的Elasticsearch版本的构建ID。
version
(浮点数) 用于创建快照的Elasticsearch版本。
indices
(数组) 快照中包含的索引列表。
index_details

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

Properties of index_details
shard_count
(整数) 该索引中的分片数量。
size
(字符串) 该索引中所有分片的总大小。仅当设置了?human查询参数时才存在。
size_in_bytes
(长整型) 该索引中所有分片的总大小，以字节为单位。
max_segments_per_shard
(整数) 该索引快照中每个分片的最大段数。
data_streams
(字符串数组) 快照中包含的数据流列表。
include_global_state
(布尔值) 指示当前集群状态是否包含在快照中。
feature_states

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

Properties of features_states objects
feature_name
(字符串) 功能的名称，由获取功能API返回。
indices
(字符串数组) 功能状态中的索引。
start_time
(字符串) 快照创建过程开始的时间戳。
start_time_in_millis
(长整型) 快照创建过程开始的时间，以毫秒为单位。
end_time
(字符串) 快照创建过程结束时的日期时间戳。
end_time_in_millis
(长整型) 快照创建过程结束时的时间，以毫秒为单位。
duration_in_millis
(长整型) 创建快照所花费的时间，以毫秒为单位。
failures
(数组) 列出创建快照时发生的任何失败。
shards

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

Properties of shards
total
(整数) 快照中包含的分片总数。
successful
(整数) 成功包含在快照中的分片数量。
failed
(整数) 未能包含在快照中的分片数量。
state

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

Values for state
IN_PROGRESS
快照正在运行中。
SUCCESS
快照已完成，所有分片都已成功存储。
FAILED
快照因错误而完成，未能存储任何数据。
PARTIAL
全局集群状态已存储，但至少有一个分片的数据未能成功存储。 响应的 failures 部分包含有关未正确处理的分片的更多详细信息。
next
(字符串) 如果请求中包含大小限制并且可能还有更多结果，将在响应中添加一个next字段，并可以用作after查询参数来获取更多结果。
total
(整数) 在忽略大小限制或after查询参数时，与请求匹配的快照总数。
remaining
(整数) 由于大小限制而未返回的剩余快照数量，可以通过使用next字段值的额外请求来获取。

示例

edit

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

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，并按快照名称排序。

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参数来请求剩余的快照。

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来跳过已经看到的两个快照，从而获得相同的结果。

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 的快照

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之后的所有快照信息。

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日）或之后开始的快照信息，按快照开始时间以默认的升序排序。

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

edit

检索参与快照的每个分片的当前状态的详细描述。请注意，此API仅应用于获取正在进行中的快照的分片级详细信息。如果不需要此详细信息，或者您想获取一个或多个现有快照的信息，请使用获取快照API。

GET _snapshot/_status

请求

edit

GET _snapshot/_status

GET _snapshot//_status

GET _snapshot///_status

先决条件

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

描述

edit

使用获取快照状态 API 来获取参与快照的分片的详细信息。

如果你省略了请求路径参数，请求只会检索当前正在运行的快照的信息。这种用法是首选的。

如果需要，您可以指定 和 来检索特定快照的信息，即使它们当前未在运行。

使用API返回除当前正在运行的快照之外的任何快照的状态可能会很昂贵。API需要从存储库中读取每个快照中的每个分片。例如，如果您有100个快照，每个快照有1,000个分片，则包含所有快照的API请求将需要100,000次读取（100个快照 * 1,000个分片）。

根据您的存储延迟，此类请求可能需要极长的时间才能返回结果。这些请求还可能消耗机器资源，并且在使用云存储时，会产生高昂的处理成本。

路径参数

edit
<repository>
(可选，字符串) 用于限制请求的快照仓库名称。如果未指定，则支持通配符 (*)。
<snapshot>
(可选，字符串) 逗号分隔的快照列表，用于检索状态。默认为当前正在运行的快照。不支持通配符 (*)。

查询参数

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

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

如果true，请求将忽略不可用的快照，例如那些已损坏或暂时无法返回的快照。

响应体

edit
repository
(字符串) 包含快照的仓库名称。
snapshot
(字符串) 快照的名称。
uuid
(字符串) 快照的通用唯一标识符 (UUID)。
state

(字符串) 指示当前快照状态。

Values for state
FAILED
快照在错误中结束，未能存储任何数据。
STARTED
快照正在运行中。
SUCCESS
快照已完成。
include_global_state
(布尔值) 指示当前集群状态是否包含在快照中。
shards_stats

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

Properties of shards_stats
initializing
(整数) 仍在初始化的分片数量。
started
(整数) 已启动但未完成的分片数量。
finalizing
(整数) 正在完成但未完成的分片数量。
done
(整数) 已成功初始化、启动和完成的分片数量。
failed
(整数) 未能包含在快照中的分片数量。
total
(整数) 快照中包含的分片总数。
stats

(对象) 提供快照中包含的文件数量（file_count）和大小（size_in_bytes）的详细信息。

Properties of stats
incremental

(对象) 仍需作为增量快照一部分复制的文件数量和大小。

对于已完成的快照，此属性表示未在仓库中且作为增量快照一部分复制的文件数量和大小。

processed
(对象) 已上传到快照的文件数量和大小。文件上传后，已处理的 file_count 和 size_in_bytes 会在 stats 中递增。
total
(对象) 快照引用的文件总数和大小。
start_time_in_millis
(长整型) 快照创建过程开始的时间，以毫秒为单位。
time_in_millis
(长整型) 快照过程完成所花费的总时间，以毫秒为单位。
<index>

(对象列表) 包含有关快照中包含的索引信息的对象列表。

Properties of
shards_stats
(对象) 参见 shards_stats。
stats
(对象) 参见 stats。
shards

(对象列表) 包含有关包含快照的分片的对象列表信息。

Properties of shards
stage

(字符串) 指示包含快照的分片的当前状态。

Properties of stage
DONE
快照中成功存储在仓库中的分片数量。
FAILURE
快照中未成功存储在仓库中的分片数量。
FINALIZE
快照中处于存储在仓库的最终化阶段的分片数量。
INIT
快照中处于存储在仓库的初始化阶段的分片数量。
STARTED
快照中处于存储在仓库的开始阶段的分片数量。
stats
(对象) 参见 stats。
total
(对象) 快照引用的文件总数和大小。
start_time_in_millis
(长整型) 参见 start_time_in_millis。
time_in_millis
(长整型) 参见 time_in_millis。

示例

edit

以下请求返回my_repository仓库中snapshot_2的详细状态信息。此响应包括超出Get snapshot API的额外信息，例如分片状态和文件统计信息。

GET _snapshot/my_repository/snapshot_2/_status
{
  "snapshots" : [
    {
      "snapshot" : "snapshot_2",
      "repository" : "my_repository",
      "uuid" : "lNeQD1SvTQCqqJUMQSwmGg",
      "state" : "SUCCESS",
      "include_global_state" : false,
      "shards_stats" : {
        "initializing" : 0,
        "started" : 0,
        "finalizing" : 0,
        "done" : 1,
        "failed" : 0,
        "total" : 1
      },
      "stats" : {
        "incremental" : {
          "file_count" : 3,
          "size_in_bytes" : 5969
        },
        "total" : {
          "file_count" : 4,
          "size_in_bytes" : 6024
        },
        "start_time_in_millis" : 1594829326691,
        "time_in_millis" : 205
      },
      "indices" : {
        "index_1" : {
          "shards_stats" : {
            "initializing" : 0,
            "started" : 0,
            "finalizing" : 0,
            "done" : 1,
            "failed" : 0,
            "total" : 1
          },
          "stats" : {
            "incremental" : {
              "file_count" : 3,
              "size_in_bytes" : 5969
            },
            "total" : {
              "file_count" : 4,
              "size_in_bytes" : 6024
            },
            "start_time_in_millis" : 1594829326896,
            "time_in_millis" : 0
          },
          "shards" : {
            "0" : {
              "stage" : "DONE",
              "stats" : {
                "incremental" : {
                  "file_count" : 3,
                  "size_in_bytes" : 5969
                },
                "total" : {
                  "file_count" : 4,
                  "size_in_bytes" : 6024
                },
                "start_time_in_millis" : 1594829326896,
                "time_in_millis" : 0
              }
            }
          }
        }
      }
    }
  ]
}

恢复快照 API

edit

恢复一个快照，该快照包含集群或指定数据流和索引的内容。

POST /_snapshot/my_repository/my_snapshot/_restore

请求

edit

POST /_snapshot///_restore

先决条件

edit
  • 如果您使用Elasticsearch安全功能，您必须拥有manage或 cluster:admin/snapshot/*集群权限才能使用此API。
  • 您只能将快照恢复到一个具有已选举的 主节点的运行集群。快照的存储库必须 已注册并可用于集群。
  • 快照和集群版本必须兼容。请参阅 快照兼容性。
  • 要恢复快照，集群的全局元数据必须是可写的。确保 没有任何阻止写入的集群块。 恢复操作会忽略索引块。

  • 在恢复数据流之前，请确保集群包含一个启用了数据流的匹配索引模板。要检查，可以使用Kibana的索引管理功能或获取索引模板API：

    GET _index_template/*?filter_path=index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream

    如果没有这样的模板，您可以创建一个或 恢复包含一个的集群状态。没有匹配的索引模板，数据流无法滚动 或创建支持索引。

  • 如果您的快照包含来自App Search或Workplace Search的数据，请确保 在恢复快照之前已恢复企业搜索加密密钥。

路径参数

edit
<repository>
(必需，字符串) 要从其恢复快照的仓库名称。
<snapshot>
(必需，字符串) 要恢复的快照名称。

查询参数

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

(可选，布尔值) 如果为 true，请求将在恢复操作完成时返回响应。当恢复操作完成所有尝试 恢复主分片 时，操作即视为完成。 即使一个或多个恢复尝试失败，此规则也适用。

如果为false，请求在恢复操作初始化时返回响应。默认为false。

请求体

edit
ignore_unavailable
(可选，布尔值) 如果为true，请求将忽略快照中缺少的任何索引或数据流。如果为false，请求将为任何缺少的索引或数据流返回错误。默认为false。
ignore_index_settings

(可选，字符串或字符串数组) 不从快照恢复的索引设置。您不能使用此选项来忽略 index.number_of_shards。

对于数据流，此选项仅适用于已恢复的备份索引。新的备份索引是使用数据流的匹配索引模板进行配置的。

include_aliases
(可选，布尔值) 如果true，请求将恢复任何已恢复的数据流和索引的别名。如果false，请求不会恢复别名。默认为true。
include_global_state

(可选, 布尔值) 如果为true，恢复集群状态。默认为false。

集群状态包括：

如果 include_global_state 为 true，则恢复操作会将集群中的旧版索引模板与快照中包含的模板合并，替换名称与快照中匹配的任何现有模板。它将完全删除集群中所有持久设置、非旧版索引模板、摄取管道和 ILM 生命周期策略，并用快照中的相应项目替换它们。

使用 feature_states 参数来配置如何恢复特征状态。

如果 include_global_state 为 true 并且快照是在没有全局状态的情况下创建的，那么恢复请求将会失败。

feature_states

(可选，字符串数组) 要恢复的功能状态。

如果 include_global_state 为 true，请求默认恢复快照中的所有特征状态。如果 include_global_state 为 false，请求默认不恢复任何特征状态。请注意，指定一个空数组将导致默认行为。要恢复无特征状态，无论 include_global_state 的值如何，请指定一个仅包含值 none 的数组（["none"]）。

index_settings

（可选，对象）要在恢复的索引中添加或更改的索引设置，包括后备索引。您不能使用此选项来更改 index.number_of_shards。

对于数据流，此选项仅适用于已恢复的备份索引。新的备份索引是使用数据流的匹配索引模板进行配置的。

indices

(可选，字符串或字符串数组) 要恢复的索引和数据流的逗号分隔列表。支持多目标语法。默认恢复快照中的所有常规索引和常规数据流。

您不能使用此参数来恢复系统索引或系统数据流。请改用feature_states。

partial

(可选，布尔值) 如果为false，则在快照中包含的一个或多个索引没有所有主分片可用时，整个恢复操作将失败。默认为false。

如果 true，允许恢复包含不可用分片的索引的部分快照。只有成功包含在快照中的分片才会被恢复。所有缺失的分片将被重新创建为空。

rename_pattern

(可选，字符串) 定义一个重命名模式，应用于恢复的数据流和索引。匹配重命名模式的数据流和索引将根据 rename_replacement 进行重命名。

重命名模式根据正则表达式定义应用，该正则表达式支持引用原始文本，依据appendReplacement逻辑。

rename_replacement
(可选，字符串) 定义重命名的替换字符串。更多信息请参见rename_pattern。

示例

edit

恢复重命名

edit

以下请求从snapshot_2恢复index_1和index_2。rename_pattern和rename_replacement参数表示任何匹配正则表达式index_(.+)的索引在恢复时将使用模式restored_index_$1进行重命名。

例如，index_1 将被重命名为 restored_index_1。index_2 将被重命名为 restored_index_2。

POST /_snapshot/my_repository/snapshot_2/_restore?wait_for_completion=true
{
  "indices": "index_1,index_2",
  "ignore_unavailable": true,
  "include_global_state": false,
  "rename_pattern": "index_(.+)",
  "rename_replacement": "restored_index_$1",
  "include_aliases": false
}

如果请求成功，API将返回确认信息。如果请求遇到错误，响应将指出发现的任何问题，例如阻止还原操作完成的开放索引。

就地恢复

edit

您可能希望就地恢复索引，例如当集群分配解释API报告no_valid_shard_copy后没有其他替代选项时。

以下请求关闭index_1，然后从my_repository仓库中的snapshot_2快照中就地恢复它。

POST index_1/_close

POST /_snapshot/my_repository/snapshot_2/_restore?wait_for_completion=true
{
  "indices": "index_1"
}

删除快照 API

edit

删除一个快照。

DELETE /_snapshot/my_repository/my_snapshot

请求

edit

DELETE /_snapshot//

先决条件

edit
  • 如果启用了Elasticsearch安全功能，您必须拥有manage 集群权限才能使用此API。

路径参数

edit
<repository>
(必需，字符串) 要从中删除快照的仓库名称。
<snapshot>
(必需，字符串) 要删除的快照名称的逗号分隔列表。也接受通配符 (*)。

查询参数

edit
master_timeout
(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。 也可以设置为-1，表示请求不应超时。
wait_for_completion
(可选，布尔值) 如果为true，请求将在所有匹配的快照都被删除后返回响应。如果为false，请求将在删除操作被安排后立即返回响应。默认为true。

示例

edit

以下请求从名为 my_repository 的仓库中删除 snapshot_2 和 snapshot_3。

DELETE /_snapshot/my_repository/snapshot_2,snapshot_3

API返回以下响应：

{
  "acknowledged" : true
}
« Security APIs Snapshot lifecycle management APIs »