快照（Snapshots）

class elasticsearch.client.SnapshotClient

To use this client, access client.snapshot from an Elasticsearch client. For example:

from elasticsearch import Elasticsearch

# Create the client instance
client = Elasticsearch(...)
# Use the snapshot client
client.snapshot.<method>(...)

cleanup_repository(*, name, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, timeout=None)

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

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-cleanup-repository

Parameters:

• name (str) – 要清理的快照仓库名称。

• master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待连接主节点的时间段。 如果在超时到期前主节点不可用，请求 将失败并返回错误。若要表示请求永不超时， 请设置为 -1

• timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 更新集群元数据后等待集群中所有相关节点 响应的时间段。如果在超时到期前未收到响应， 集群元数据更新仍会应用但 响应将指示未完全确认。若要表示 请求永不超时，请设置为 -1。

• error_trace (bool | None)

• filter_path (str | Sequence[str] | None)

• human (bool | None)

• pretty (bool | None)

Return type:

ObjectApiResponse[Any]

clone(*, repository, snapshot, target_snapshot, indices=None, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, body=None)

克隆快照。 将快照的部分或全部内容克隆到同一仓库中的另一个快照。

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-clone

Parameters:

• repository (str) – 源快照和目标快照所属的快照仓库名称。

• snapshot (str) – 源快照名称。

• target_snapshot (str) – 目标快照名称。

• indices (str | None) – 要包含在快照中的逗号分隔的索引列表。 支持多目标语法。

• master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待主节点的时间段。如果主 节点在超时到期前不可用，请求将失败并返回 错误。若要表示请求永不超时，请设置为 -1。

• error_trace (bool | None)

• filter_path (str | Sequence[str] | None)

• human (bool | None)

• pretty (bool | None)

• body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

create(*, repository, snapshot, error_trace=None, expand_wildcards=None, feature_states=None, filter_path=None, human=None, ignore_unavailable=None, include_global_state=None, indices=None, master_timeout=None, metadata=None, partial=None, pretty=None, wait_for_completion=None, body=None)

创建快照。 对集群或数据流和索引进行快照。

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-create

Parameters:

• repository (str) – 快照所属的仓库名称。

• snapshot (str) – 快照名称。支持日期数学表达式。在仓库中 必须唯一。

• expand_wildcards (Sequence[str | Literal['all', 'closed', 'hidden', 'none', 'open']] | str | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | None) – 确定 indices 参数中的通配符模式如何 匹配数据流和索引。支持逗号分隔的值，如 open,hidden。

• feature_states (Sequence[str] | None) – 要包含在快照中的功能状态。每个功能 状态包含一个或多个相关数据的系统索引。 可以使用获取功能 API 查看符合条件的功能列表。 如果 include_global_state 为 true，默认包含 所有当前功能状态。如果 include_global_state 为 false，默认不包含任何功能状态。注意指定 空数组将导致默认行为。要排除所有功能 状态，无论 include_global_state 值如何，请指定 仅包含值 none 的数组（[“none”]）。

• ignore_unavailable (bool | None) – 如果为 true，请求将忽略 indices 中 缺失或关闭的数据流和索引。如果为 false， 请求将对任何缺失或关闭的数据流或索引返回 错误。

• include_global_state (bool | None) – 如果为 true，当前集群状态将包含 在快照中。集群状态包括持久化集群设置、 可组合索引模板、传统索引模板、摄取管道和 ILM 策略。还包括存储在系统索引中的数据， 如 Watches 和任务记录（可通过 feature_states 配置）。

• indices (str | Sequence[str] | None) – 要包含在快照中的逗号分隔的数据流和索引列表。 支持多目标语法。默认为空数组（[]）， 包含所有常规数据流和常规索引。 要排除所有数据流和索引，请使用 -*。不能使用此参数 在快照中包含或排除系统索引或系统数据流。 请改用 feature_states。

• master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待连接主节点的时间段。 如果在超时到期前未收到响应，请求将失败 并返回错误。

• metadata (Mapping[str, Any] | None) – 快照的任意元数据，如记录谁 创建了快照、创建原因或其他有用数据。 可以是任何内容但必须小于 1024 字节。此信息 不是由 Elasticsearch 自动生成的。

• partial (bool | None) – 如果为 true，允许恢复具有不可用分片的 部分索引快照。只有成功包含在快照中的 分片会被恢复。所有缺失分片将作为空分片重建。 如果为 false，如果快照中包含的一个或多个索引 没有所有主分片可用，整个恢复操作将失败。

• wait_for_completion (bool | None) – 如果为 true，请求在 快照完成时返回响应。如果为 false，请求在 快照初始化时返回响应。

• error_trace (bool | None)

• filter_path (str | Sequence[str] | None)

• human (bool | None)

• pretty (bool | None)

• body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

create_repository(*, name, repository=None, body=None, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, timeout=None, verify=None)

创建或更新快照仓库。 重要提示：如果要迁移可搜索快照，源集群和目标集群中的仓库名称必须相同。 要注册快照仓库，集群的全局元数据必须可写。 确保没有集群块（例如 cluster.blocks.read_only 和 clsuter.blocks.read_only_allow_delete 设置）阻止写入访问。

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

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-create-repository

Parameters:

• name (str) – 要注册或更新的快照仓库名称。

• repository (Mapping[str, Any] | None)

• master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待主节点的时间段。如果主 节点在超时到期前不可用，请求将失败并返回 错误。若要表示请求永不超时，请设置为 -1。

• timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 更新集群元数据后等待集群中所有相关节点 响应的时间段。如果在超时到期前未收到响应， 集群元数据更新仍会应用但 响应将指示未完全确认。若要表示 请求永不超时，请设置为 -1。

• verify (bool | None) – 如果为 true，请求将验证仓库在 集群中所有主节点和数据节点上是否功能正常。 如果为 false，则跳过此验证。也可以使用 验证快照仓库 API 执行此验证。

• body (Mapping[str, Any] | None)

• error_trace (bool | None)

• filter_path (str | Sequence[str] | None)

• human (bool | None)

• pretty (bool | None)

Return type:

ObjectApiResponse[Any]

delete(*, repository, snapshot, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, wait_for_completion=None)

删除快照。

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-delete

Parameters:

• repository (str) – 要从中删除快照的仓库名称。

• snapshot (str) – 要删除的快照名称的逗号分隔列表。 也接受通配符（*）。

• master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待主节点的时间段。如果主 节点在超时到期前不可用，请求将失败并返回 错误。若要表示请求永不超时，请设置为 -1。

• wait_for_completion (bool | None) – 如果为 true，请求在所有匹配的 快照被删除后返回响应。如果为 false， 请求在删除操作被调度后立即返回响应。

• error_trace (bool | None)

• filter_path (str | Sequence[str] | None)

• human (bool | None)

• pretty (bool | None)

Return type:

ObjectApiResponse[Any]

delete_repository(*, name, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, timeout=None)

删除快照仓库。 当取消注册一个仓库时，Elasticsearch 仅移除对该仓库存储快照位置的引用。 快照本身保持不变且保留在原处。

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-delete-repository

Parameters:

• name (str | Sequence[str]) – 要取消注册的快照仓库名称。支持通配符(*)模式。

• master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待主节点的超时时间。如果在超时前主节点不可用， 请求将失败并返回错误。设置为`-1`表示永不超时。

• timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 更新集群元数据后等待集群中所有相关节点响应的超时时间。 如果在超时前未收到响应，集群元数据更新仍会应用但响应将表明未完全确认。 设置为`-1`表示永不超时。

• error_trace (bool | None)

• filter_path (str | Sequence[str] | None)

• human (bool | None)

• pretty (bool | None)

Return type:

ObjectApiResponse[Any]

get(*, repository, snapshot, after=None, error_trace=None, filter_path=None, from_sort_value=None, human=None, ignore_unavailable=None, include_repository=None, index_details=None, index_names=None, master_timeout=None, offset=None, order=None, pretty=None, size=None, slm_policy_filter=None, sort=None, state=None, verbose=None)

获取快照信息。

注意：after参数和next字段使您能够在迭代快照时保持一定的一致性保证，即使快照被并发创建或删除。 可以保证在迭代开始时存在且未被并发删除的任何快照都将在迭代过程中被看到。 并发创建的快照可能在迭代过程中被看到。

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-get

Parameters:

• repository (str) – 用于限制请求的快照仓库名称的逗号分隔列表。支持通配符(*)表达式。

• snapshot (str | Sequence[str]) – 要检索的快照名称的逗号分隔列表。支持通配符(*)。* 要获取注册仓库中所有快照的信息，请使用通配符(*)或`_all`。* 要获取当前正在运行的任何快照的信息，请使用`_current`。

• after (str | None) – 从响应体中next字段返回的偏移标识符开始分页。

• from_sort_value (str | None) – 当前排序列的值，从该值开始检索。当按快照或仓库名称排序时，可以是字符串`snapshot-`或仓库名称。当按`index-`或分片计数排序时，可以是毫秒时间值或数字。

• ignore_unavailable (bool | None) – 如果为`false`，请求会对任何不可用的快照返回错误。

• include_repository (bool | None) – 如果为`true`，响应中会包含每个快照的仓库名称。

• index_details (bool | None) – 如果为`true`，响应中会包含快照中每个索引的附加信息，包括索引的分片数量、索引的总大小（字节）以及索引中每个分片的最大段数。默认为`false`，表示省略此信息。

• index_names (bool | None) – 如果为`true`，响应中会包含每个快照中每个索引的名称。

• master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待连接到主节点的时间段。如果在超时到期前未收到响应，请求将失败并返回错误。

• offset (int | None) – 基于匹配此请求的快照开始分页的数字偏移量。为此参数使用非零值与使用after参数是互斥的。默认为0。

• order (str | Literal['asc', 'desc'] | None) – 排序顺序。有效值为`asc`表示升序，`desc`表示降序。默认行为是升序。

• size (int | None) – 要返回的快照的最大数量。默认为0，表示返回所有匹配请求的快照，没有限制。

• slm_policy_filter (str | None) – 按快照所属的快照生命周期管理(SLM)策略名称的逗号分隔列表过滤快照。您可以使用通配符(*)和通配符后跟以`-开头的排除模式的组合。例如，模式`*,-policy-a-*`将返回除由名称以`policy-a-`开头的SLM策略创建的快照之外的所有快照。请注意，通配符模式`*`匹配由SLM策略创建的所有快照，但不匹配那些不是由SLM策略创建的快照。要包含不是由SLM策略创建的快照，您可以使用特殊模式`_none，它将匹配所有没有SLM策略的快照。

• sort (str | Literal['duration', 'failed_shard_count', 'index_count', 'name', 'repository', 'shard_count', 'start_time'] | None) – 结果的排序顺序。默认行为是按快照开始时间戳排序。

• state (Sequence[str | Literal['FAILED', 'INCOMPATIBLE', 'IN_PROGRESS', 'PARTIAL', 'SUCCESS']] | str | ~typing.Literal['FAILED', 'INCOMPATIBLE', 'IN_PROGRESS', 'PARTIAL', 'SUCCESS'] | None) – 仅返回状态在给定的逗号分隔的快照状态列表中的快照。默认为所有快照状态。

• verbose (bool | None) – 如果为`true`，返回关于每个快照的附加信息，例如拍摄快照的Elasticsearch版本、快照的开始和结束时间以及快照的分片数量。注意：当您设置`verbose=false`时，不支持参数`size`、order、after、from_sort_value、offset、slm_policy_filter`和`sort，并且对于`verbose=false`的请求，排序顺序是未定义的。

• error_trace (bool | None)

• filter_path (str | Sequence[str] | None)

• human (bool | None)

• pretty (bool | None)

Return type:

ObjectApiResponse[Any]

get_repository(*, name=None, error_trace=None, filter_path=None, human=None, local=None, master_timeout=None, pretty=None)

获取快照仓库信息。

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-get-repository

Parameters:

• name (str | Sequence[str] | None) – 用于限制请求的快照仓库名称的逗号分隔列表。支持通配符(*)表达式， 包括将通配符与以`-开头的排除模式结合使用。要获取集群中注册的所有快照仓库信息， 请省略此参数或使用`*`或`_all。

• local (bool | None) – 如果为`true`，请求仅从本地节点获取信息。 如果为`false`，请求将从主节点获取信息。

• master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待主节点的超时时间。如果在超时到期前主节点不可用， 请求将失败并返回错误。若要表示请求永不超时，请将其设置为`-1`。

• error_trace (bool | None)

• filter_path (str | Sequence[str] | None)

• human (bool | None)

• pretty (bool | None)

Return type:

ObjectApiResponse[Any]

repository_analyze(*, name, blob_count=None, concurrency=None, detailed=None, early_read_node_count=None, error_trace=None, filter_path=None, human=None, max_blob_size=None, max_total_data_size=None, pretty=None, rare_action_probability=None, rarely_abort_writes=None, read_node_count=None, register_operation_count=None, seed=None, timeout=None)

分析快照存储库。

对快照存储库执行操作以检查是否存在异常行为。

市面上有大量第三方存储系统，但并非所有都适合作为Elasticsearch的快照存储库使用。 某些存储系统存在行为异常或性能低下的问题，特别是在被Elasticsearch集群节点作为多客户端并发访问时。 该API通过执行一系列读写操作来检测异常行为并测量存储系统的性能特征。

参数默认值特意设置较低，以减少无意运行分析的影响，并为调查提供合理起点。 首次分析应使用默认参数值检查基本问题。 某些存储库可能在轻负载时表现正常，但在生产级负载下出现异常。 若首次分析成功，可逐步增加分析规模直至遇到失败，或达到blob_count至少2000、max_blob_size至少2gb、max_total_data_size至少1tb、register_operation_count至少100。 始终设置充足超时（如1h或更长）确保分析完整运行。 某些存储库在被少量节点访问时正常，但在生产规模集群并发访问时异常。 建议使用与生产集群规模相近的多节点集群进行分析，以检测多节点并发访问时才出现的问题。

若分析失败，说明Elasticsearch检测到存储库行为异常。 通常意味着您使用的第三方存储系统对其声称支持的API存在错误或不兼容实现。 此类存储系统不适合作为快照存储库。 存储库分析会触发生产系统中罕见的快照条件。 即使分析失败，向不兼容存储写入快照可能多数情况下看似正常。 但若使用未通过存储库分析的存储库，快照数据将面临风险。 可通过验证相同存储协议参考实现是否出现相同问题，来确认分析失败是否由存储实现不兼容导致。 例如，若使用的存储声称兼容AWS S3，应验证AWS S3存储库能否通过分析。 这有助于向供应商证明问题源于与AWS S3的不兼容性而非Elasticsearch。 除非能证明相同问题出现在参考实现中，否则请勿提交涉及第三方存储系统的Elasticsearch问题报告。 您需要与存储供应商合作解决Elasticsearch检测到的不兼容问题。

若分析成功，API将返回测试过程详情（可选包含各操作耗时）。 此信息可用于评估存储系统性能。 若任何操作失败或返回错误结果，API将返回错误。 出错时API可能未完全清理写入数据，错误信息会指示残留数据位置（该路径也会记录在Elasticsearch日志中），您需手动清理。

若客户端等待分析结果期间连接关闭，测试将被取消。 某些客户端配置会在超时无响应时关闭连接。 分析耗时较长，可能需要放宽客户端超时设置。 取消时会尝试清理写入数据，但可能无法完全清除。残留路径记录在日志中，需手动清理。

分析成功仅表示未检测到异常行为，不保证绝对正确。 分析旨在检测常见缺陷，但无法100%覆盖。此外不测试以下内容：

• 存储库必须实现持久化写入。写入的blob在删除前必须持久存在（即使断电或发生灾难）
• 存储库不得发生静默数据损坏。写入的blob内容在主动修改/删除前必须保持不变
• 集群连接中断时存储库必须行为正确（读写可能失败，但不得返回错误结果）

重要提示：分析会向存储库写入大量数据并回读，将消耗集群与存储库间的网络带宽，以及存储库自身的存储空间和I/O带宽。 需确保不影响其他系统用户。 分析会遵循存储库设置max_snapshot_bytes_per_sec、max_restore_bytes_per_sec（若可用）及集群设置indices.recovery.max_bytes_per_sec来限制带宽消耗。

注意：本API仅供人工探索使用，未来版本可能变更请求参数和响应格式。响应暴露的分析实现细节可能随版本变化。

注意：不同Elasticsearch版本可能执行不同的存储库兼容性检查，新版通常更严格。 通过某版本分析的存储系统可能在另一版本中失败，说明旧版未检测到其错误行为。 您必须与存储供应商合作解决任何版本中分析API检测到的不兼容问题。

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

实现细节

注意：本节描述当前版本分析API的工作原理，但实现可能随版本变化。 请求参数和响应格式依赖实现细节，新版可能不同。

分析包含由blob_count参数设定的blob级任务，以及由register_operation_count参数设定的可线性化寄存器比较交换操作。 这些任务会分配到集群的数据节点和主节点执行。

多数blob任务中，执行节点先写入blob，再指示其他节点读取刚写入的数据。 blob大小根据max_blob_size和max_total_data_size参数随机选择。 若任何读取失败，说明存储库未实现Elasticsearch要求的写后读语义。

部分blob任务会在写入完成前让其他节点尝试读取。 这些读取允许失败，但不得返回部分数据。返回部分数据说明存储库未实现必要的原子性语义。

部分blob任务会在其他节点读取时覆盖blob。 此时读取结果可来自原blob或覆盖后的blob，但不得返回部分数据或混合数据。 若返回部分/混合数据，说明存储库未实现覆盖操作所需的原子性语义。

执行节点会使用多种写入方法（如适用时同时使用单部分和多部分上传）。 读取节点也会使用多种方法回读数据（如完整读取或部分读取）。

部分blob任务会在写入完成前取消。 此时仍会让其他节点尝试读取，但这些读取必须无法找到blob。

可线性化寄存器是Elasticsearch通过原子比较交换操作操作的特殊blob。 该操作确保即使多节点并发访问也能保持强一致性。 比较交换操作的具体实现因存储库类型而异。 分析会验证无竞争条件下的比较交换操作始终成功，有竞争时操作要么成功要么报告竞争（但不得返回错误结果）。 因竞争失败的操作会被重试直至成功。 多数比较交换操作会对表示为8字节blob的计数器执行原子递增。 部分操作还会验证其他尺寸小blob的行为。

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-repository-analyze

Parameters:

• name (str) – 存储库名称

• blob_count (int | None) – 测试期间写入存储库的blob总数。建议至少设为`2000`

• concurrency (int | None) – 测试期间并发运行的操作数

• detailed (bool | None) – 是否返回详细结果（包含每个操作的计时信息）。为false时仅返回分析摘要

• early_read_node_count (int | None) – 写入每个blob时执行早期读取操作的节点数。早期读取很少执行

• max_blob_size (int | str | None) – 测试期间写入blob的最大尺寸。建议至少设为`2gb`

• max_total_data_size (int | str | None) – 测试期间所有写入blob的总尺寸上限。建议至少设为`1tb`

• rare_action_probability (float | None) – 对每个blob执行早期读取/覆盖/中止写入等罕见操作的概率

• rarely_abort_writes (bool | None) – 是否偶尔在写入完成前取消

• read_node_count (int | None) – 写入后读取blob的节点数

• register_operation_count (int | None) – 总共执行的可线性化寄存器操作最小数量。建议至少设为`100`

• seed (int | None) – 生成测试操作列表的伪随机数生成器种子。重复实验使用相同种子可生成相同操作集（注意并发执行可能导致操作顺序不同）

• timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待测试完成的超时时间。超时未收到响应将取消测试并返回错误

• error_trace (bool | None)

• filter_path (str | Sequence[str] | None)

• human (bool | None)

• pretty (bool | None)

Return type:

ObjectApiResponse[Any]

repository_verify_integrity(*, name, blob_thread_pool_concurrency=None, error_trace=None, filter_path=None, human=None, index_snapshot_verification_concurrency=None, index_verification_concurrency=None, max_bytes_per_sec=None, max_failed_shard_snapshots=None, meta_thread_pool_concurrency=None, pretty=None, snapshot_verification_concurrency=None, verify_blob_contents=None)

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

此API允许您对存储库内容进行全面检查，查找可能导致无法从该存储库恢复快照或可能导致未来快照创建/删除操作失败的数据或元数据异常。

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

• 可能无法从此存储库恢复某些快照
• 可搜索快照可能在搜索时报错或出现未分配分片
• 向此存储库创建快照可能失败，或看似成功但实际创建了无法恢复的快照
• 从此存储库删除快照可能失败，或看似成功但底层数据仍留在磁盘上
• 在存储库处于无效状态时继续写入可能导致内容进一步损坏

若API发现存储库内容存在完整性问题，Elasticsearch无法修复损坏。 内容损坏后使存储库恢复完全可用状态的唯一方法是从损坏前备份中恢复内容。 您还需查明损坏原因并采取措施防止再次发生。

若无法恢复存储库备份，请注册新存储库用于未来所有快照操作。 某些情况下可能恢复损坏存储库的部分内容，可通过恢复所需快照后对新数据创建快照，或使用reindex API从损坏存储库挂载的可搜索快照复制数据。

执行验证存储库完整性API期间请避免所有写入操作。 若完整性验证期间存储库内容发生变化，Elasticsearch可能因并发写入错误报告内容异常，或遗漏因并发写入未能检测的异常。

注意：此API仅供人工探索使用，未来版本中请求参数和响应格式可能变化。

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

本API参数的默认值旨在限制完整性验证对集群其他活动的影响。 例如默认最多使用半数snapshot_meta线程验证每个快照完整性，另一半线程池可供其他快照操作使用。 若修改参数加速验证过程，可能干扰集群中其他快照相关操作。 对于大型存储库，建议设置独立单节点Elasticsearch集群专门运行完整性验证API。

响应暴露的分析实现细节可能随版本变化，因此响应体格式不稳定，新版本中可能不同。

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-repository-verify-integrity

Parameters:

• name (str | Sequence[str]) – 快照存储库名称

• blob_thread_pool_concurrency (int | None) – 当`verify_blob_contents`为`true`时， 指定同时验证的blob数量

• index_snapshot_verification_concurrency (int | None) – 每个索引验证中 并发验证的最大索引快照数

• index_verification_concurrency (int | None) – 并发验证的索引数。 默认使用整个`snapshot_meta`线程池

• max_bytes_per_sec (str | None) – 当`verify_blob_contents`为`true`时， 指定Elasticsearch每秒从存储库读取的最大数据量

• max_failed_shard_snapshots (int | None) – 完整性验证期间跟踪的分片快照失败数， 以避免资源过度使用。若存储库包含超过此数值的失败分片快照，验证将失败

• meta_thread_pool_concurrency (int | None) – 并发运行的快照元数据操作最大数。 默认行为是每次最多使用半数`snapshot_meta`线程池

• snapshot_verification_concurrency (int | None) – 并发验证的快照数。 默认行为是每次最多使用半数`snapshot_meta`线程池

• verify_blob_contents (bool | None) – 是否验证存储库中每个数据blob的校验和。 启用后将读取整个存储库内容，可能极其耗时耗资源

• error_trace (bool | None)

• filter_path (str | Sequence[str] | None)

• human (bool | None)

• pretty (bool | None)

Return type:

ObjectApiResponse[Any]

restore(*, repository, snapshot, error_trace=None, feature_states=None, filter_path=None, human=None, ignore_index_settings=None, ignore_unavailable=None, include_aliases=None, include_global_state=None, index_settings=None, indices=None, master_timeout=None, partial=None, pretty=None, rename_pattern=None, rename_replacement=None, wait_for_completion=None, body=None)

恢复快照。 恢复集群或数据流和索引的快照。

只能将快照恢复到已选举出主节点的运行中集群。 快照仓库必须已注册且对集群可用。 快照版本与集群版本必须兼容。

要恢复快照，集群的全局元数据必须可写。确保没有任何集群块阻止写入。恢复操作会忽略索引块。

在恢复数据流之前，请确保集群包含启用了数据流的匹配索引模板。可使用 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 的数据，必须在恢复快照前恢复 Enterprise Search 加密密钥。

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-restore

Parameters:

• repository (str) – 要从中恢复快照的仓库名称。

• snapshot (str) – 要恢复的快照名称。

• feature_states (Sequence[str] | None) – 要恢复的功能状态。如果 include_global_state 为 true，默认请求会恢复快照中的所有功能状态。 如果 include_global_state 为 false，默认请求不会恢复任何功能状态。 注意指定空数组将导致默认行为。要恢复零个功能状态（无论 include_global_state 值如何），需指定仅包含值 none 的数组（[“none”]）。

• ignore_index_settings (Sequence[str] | None) – 不从快照恢复的索引设置。 不能使用此选项忽略 index.number_of_shards。对于数据流， 此选项仅适用于恢复的后备索引。新的后备索引 使用数据流的匹配索引模板进行配置。

• ignore_unavailable (bool | None) – 如果为 true，请求将忽略快照中缺失的任何索引或数据流。 如果为 false，请求将对任何缺失的索引或数据流返回错误。

• include_aliases (bool | None) – 如果为 true，请求将恢复任何已恢复 数据流和索引的别名。如果为 false，请求不会恢复别名。

• include_global_state (bool | None) – 如果为 true，恢复集群状态。集群 状态包括：* 持久化集群设置 * 索引模板 * 旧版 索引模板 * 摄取管道 * 索引生命周期管理 (ILM) 策略 * 存储脚本 * 对于 7.12.0 之后拍摄的快照，还包括功能状态。如果 include_global_state 为 true，恢复操作会将集群中的旧版索引模板与快照中包含的模板合并， 替换名称与快照中匹配的任何现有模板。它会完全移除集群中所有持久化 设置、非旧版索引模板、摄取管道和 ILM 生命周期 策略，并用快照中的对应项替换它们。使用 feature_states 参数配置 功能状态的恢复方式。如果 include_global_state 为 true 且 快照创建时没有全局状态，则恢复请求将失败。

• index_settings (Mapping[str, Any] | None) – 要在恢复的索引（包括后备索引）中添加或更改的索引设置。 不能使用此选项更改 index.number_of_shards。 对于数据流，此选项仅适用于恢复的后备索引。新的 后备索引使用数据流的匹配索引模板进行配置。

• indices (str | Sequence[str] | None) – 要恢复的索引和数据流的逗号分隔列表。 支持多目标语法。默认行为是恢复快照中所有常规索引 和常规数据流。不能使用此参数恢复 系统索引或系统数据流。应改用 feature_states。

• master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待主节点的时长。如果主 节点在超时前不可用，请求将失败并返回 错误。要表示请求永不过期，请设置为 -1。

• partial (bool | None) – 如果为 false，快照中包含的一个或多个 索引没有所有主分片可用时，整个恢复操作将失败。 如果为 true，则允许恢复具有不可用 分片的索引的部分快照。只有成功包含在快照中的分片 会被恢复。所有缺失的分片将作为空分片重新创建。

• rename_pattern (str | None) – 应用于恢复的数据流和索引的重命名模式。 匹配重命名模式的数据流和索引将根据 rename_replacement 重命名。 重命名模式按照支持引用原始文本的正则表达式应用， 遵循 appendReplacement 逻辑。

• rename_replacement (str | None) – 与 rename_pattern 一起使用的重命名替换字符串。

• wait_for_completion (bool | None) – 如果为 true，请求将在 恢复操作完成时返回响应。当为所有恢复的索引完成 恢复主分片的所有尝试时，操作即完成。即使 一个或多个恢复尝试失败也是如此。如果为 false，请求将在 恢复操作初始化时返回响应。

• error_trace (bool | None)

• filter_path (str | Sequence[str] | None)

• human (bool | None)

• pretty (bool | None)

• body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

status(*, repository=None, snapshot=None, error_trace=None, filter_path=None, human=None, ignore_unavailable=None, master_timeout=None, pretty=None)

获取快照状态。 获取参与快照的每个分片当前状态的详细描述。

注意此 API 应仅用于获取正在进行中的快照的详细分片级别信息。 如果不需要这些细节或想获取一个或多个现有快照的信息，请使用获取快照 API。

如果省略 <snapshot> 请求路径参数，请求仅检索当前正在运行的快照信息。 这是推荐用法。 如果需要，可以指定 <repository> 和 <snapshot> 来检索特定快照的信息，即使它们当前未在运行。

注意对于由（即使短暂）离开集群的节点完成的正在进行中的快照中的任何分片快照，统计信息将不可用。 从仓库加载统计信息是一项昂贵操作（参见下面的警告）。 因此这些分片的统计值将为 -1，尽管 "stage" 值为 "DONE"，以最小化延迟。 对于由离开节点完成的分片快照，将存在一个 "description" 字段解释为何分片快照的统计结果无效。 因此，由于这些分片的缺失值，索引的总统计信息将少于预期。

警告：使用此 API 返回非当前运行快照的任何快照状态可能非常昂贵。 API 需要对每个快照中的每个分片从仓库读取一次。 例如如果有 100 个快照，每个快照有 1,000 个分片，包含所有快照的 API 请求将需要 100,000 次读取（100 快照 x 1,000 分片）。

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

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-status

Parameters:

• repository (str | None) – 用于限制请求的快照仓库名称。 如果未指定 <snapshot>，支持通配符 (*)。

• snapshot (str | Sequence[str] | None) – 要检索状态的快照的逗号分隔列表。 默认为当前正在运行的快照。不支持通配符 (*)。

• ignore_unavailable (bool | None) – 如果为 false，请求将对任何不可用的快照返回错误。 如果为 true，请求将忽略不可用的快照，例如损坏或暂时无法返回的快照。

• master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待主节点的时长。如果主 节点在超时前不可用，请求将失败并返回 错误。要表示请求永不过期，请设置为 -1。

• error_trace (bool | None)

• filter_path (str | Sequence[str] | None)

• human (bool | None)

• pretty (bool | None)

Return type:

ObjectApiResponse[Any]

verify_repository(*, name, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, timeout=None)

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

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-verify-repository

Parameters:

• name (str) – 要验证的快照仓库名称。

• master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待主节点的时长。如果主 节点在超时前不可用，请求将失败并返回 错误。要表示请求永不过期，请设置为 -1。

• timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 更新集群元数据后等待集群中所有相关节点响应的时长。 如果在超时前未收到响应，集群元数据更新仍会应用但 响应将指示未完全确认。要表示请求永不过期，请设置为 -1。

• error_trace (bool | None)

• filter_path (str | Sequence[str] | None)

• human (bool | None)

• pretty (bool | None)

Return type:

ObjectApiResponse[Any]