« Snapshot and restore APIs SQL APIs »
Elastic Docs ›Elasticsearch Guide ›REST APIs

快照生命周期管理API

edit

快照生命周期管理API

edit

您可以使用以下API来设置策略，以自动创建快照并控制它们的保留时间。

有关快照生命周期管理（SLM）的更多信息，请参阅使用SLM自动创建快照。

策略管理API

edit

快照管理API

edit

操作管理API

edit

创建或更新快照生命周期策略 API

edit

创建或更新快照生命周期策略。

请求

edit

PUT /_slm/policy/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage_slm集群权限和任何包含索引的manage索引权限才能使用此API。 有关更多信息，请参阅安全权限。

描述

edit

使用创建或更新快照生命周期策略 API 来创建或更新快照生命周期策略。

如果策略已经存在，此请求会增加策略的版本。只有最新版本的策略会被存储。

路径参数

edit
<snapshot-lifecycle-policy-id>
(必需, 字符串) 您要创建或更新的快照生命周期策略的ID。

查询参数

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

请求体

edit
config

(必需，对象) 策略创建的每个快照的配置。

Properties of config
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，允许对包含不可用分片的索引进行部分快照。

name
(必需，字符串) 策略自动分配给每个创建的快照的名称。 日期数学 是支持的。 为了避免快照名称冲突，UUID 会自动附加到每个快照名称中。
repository
(必需，字符串) 用于存储此策略创建的快照的仓库。此仓库必须在策略创建之前存在。您可以使用 快照仓库 API 创建仓库。
retention

(可选, 对象) 用于保留和删除由策略创建的快照的保留规则。

Properties of retention
expire_after
(可选, 时间单位) 快照在被视为过期并符合删除条件后的时间周期。SLM根据 slm.retention_schedule删除过期的快照。
max_count
(可选, 整数) 要保留的最大快照数量，即使这些快照尚未过期。如果存储库中的快照数量超过此限制，策略将保留最近的快照并删除较旧的快照。此限制仅包括状态为 state为 SUCCESS的快照。
min_count
(可选, 整数) 要保留的最小快照数量，即使这些快照已过期。
schedule
(必需，Cron 语法 或 时间单位) 策略创建快照的周期性或绝对时间表。SLM 会立即应用 schedule 更改。 时间表可以是 Cron 时间表或描述快照之间间隔的时间单位。 当使用时间单位间隔时，第一个快照将在策略修改时间后一个间隔进行调度，然后每隔一个间隔再次进行调度。

示例

edit

创建一个策略

edit

创建一个daily-snapshots生命周期策略：

PUT /_slm/policy/daily-snapshots
{
  "schedule": "0 30 1 * * ?", 
  "name": "<daily-snap-{now/d}>", 
  "repository": "my_repository", 
  "config": { 
    "indices": ["data-*", "important"], 
    "ignore_unavailable": false,
    "include_global_state": false
  },
  "retention": { 
    "expire_after": "30d", 
    "min_count": 5, 
    "max_count": 50 
  }
}

当快照应该被拍摄时，在这种情况下，每天凌晨1:30

每个快照应被赋予的名称

在哪个仓库中进行快照

任何额外的快照配置

快照应包含的数据流和索引

可选的保留配置

保留快照30天

始终保留至少5个成功的快照，即使它们超过30天

保留不超过50个成功的快照，即使它们不到30天

使用间隔调度

edit

使用间隔调度创建一个每小时快照生命周期策略：

PUT /_slm/policy/hourly-snapshots
{
  "schedule": "1h",
  "name": "<hourly-snap-{now/d}>",
  "repository": "my_repository",
  "config": {
    "indices": ["data-*", "important"]
  }
}

每小时创建一次快照。第一个快照将在策略修改后一小时创建，之后每小时创建一次后续快照。

获取快照生命周期策略 API

edit

检索一个或多个快照生命周期策略定义以及有关最新快照尝试的信息。

请求

edit

GET _slm/policy/

GET _slm/policy

先决条件

edit

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

描述

edit

返回指定的策略定义以及关于最近成功和失败的快照创建尝试的信息。如果没有指定策略，则返回所有已定义的策略。

路径参数

edit
<policy-id>
(可选, 字符串) 逗号分隔的快照生命周期策略ID列表。

示例

edit

获取特定策略

edit

获取 daily-snapshots 策略：

GET _slm/policy/daily-snapshots?human

此请求返回以下响应：

{
  "daily-snapshots": {
    "version": 1,                                 
    "modified_date": "2099-05-06T01:30:00.000Z",  
    "modified_date_millis": 4081757400000,
    "policy" : {
      "schedule": "0 30 1 * * ?",
      "name": "<daily-snap-{now/d}>",
      "repository": "my_repository",
      "config": {
        "indices": ["data-*", "important"],
        "ignore_unavailable": false,
        "include_global_state": false
      },
      "retention": {
        "expire_after": "30d",
        "min_count": 5,
        "max_count": 50
      }
    },
    "stats": {
      "policy": "daily-snapshots",
      "snapshots_taken": 0,
      "snapshots_failed": 0,
      "snapshots_deleted": 0,
      "snapshot_deletion_failures": 0
    },
    "next_execution": "2099-05-07T01:30:00.000Z", 
    "next_execution_millis": 4081843800000
  }
}

快照策略的版本，仅存储最新版本，并在策略更新时递增

此策略上次修改的时间。

该策略下一次将被执行的时间。

获取所有策略

edit
GET _slm/policy

删除快照生命周期策略 API

edit

删除现有的快照生命周期策略。

请求

edit

DELETE /_slm/policy/

先决条件

edit

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

描述

edit

删除指定的生命周期策略定义。 这将阻止未来快照的拍摄， 但不会取消正在进行的快照 或删除之前拍摄的快照。

路径参数

edit
<policy-id>
(必需，字符串) 要删除的快照生命周期策略的ID。

示例

edit
DELETE /_slm/policy/daily-snapshots

执行快照生命周期策略 API

edit

立即根据生命周期策略创建快照，而无需等待预定时间。

请求

edit

PUT /_slm/policy//_execute

先决条件

edit

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

描述

edit

手动应用快照策略以立即创建快照。 快照策略通常根据其计划应用， 但在执行升级或其他维护之前，您可能希望手动执行策略。

路径参数

edit
<policy-id>
(必需，字符串) 要执行的快照生命周期策略的ID。

示例

edit

根据daily-snapshots策略立即创建快照：

POST /_slm/policy/daily-snapshots/_execute

如果成功，此请求将返回生成的快照名称：

{
  "snapshot_name": "daily-snap-2019.04.24-gwrqoo2xtea3q57vvg0uea"
}

快照在后台进行。您可以使用 快照API来 监控快照的状态。

要查看策略最新快照的状态，您可以使用获取快照生命周期策略 API。

执行快照保留策略 API

edit

根据策略的保留规则删除任何已过期的快照。

请求

edit

POST /_slm/_execute_retention

先决条件

edit

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

描述

edit

手动应用保留策略以强制立即删除过期的快照。保留策略通常根据其计划应用。

示例

edit

要强制删除过期的快照：

POST /_slm/_execute_retention

保留操作在后台异步运行。

获取快照生命周期管理状态 API

edit

检索快照生命周期管理 (SLM) 的状态。

请求

edit

GET /_slm/status

描述

edit

返回SLM插件的状态。 响应中的operation_mode字段显示三种状态之一： RUNNING、STOPPING或STOPPED。 您可以使用 停止和启动API来停止和重新启动SLM插件。

查询参数

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

先决条件

edit

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

示例

edit
GET _slm/status

API返回以下结果：

{
  "operation_mode": "RUNNING"
}

获取快照生命周期统计信息 API

edit

返回快照生命周期管理所采取操作的全局和策略级别统计信息。

请求

edit

GET /_slm/stats

先决条件

edit

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

示例

edit
GET /_slm/stats

API返回以下响应：

{
  "retention_runs": 13,
  "retention_failed": 0,
  "retention_timed_out": 0,
  "retention_deletion_time": "1.4s",
  "retention_deletion_time_millis": 1404,
  "policy_stats": [ ],
  "total_snapshots_taken": 1,
  "total_snapshots_failed": 1,
  "total_snapshots_deleted": 0,
  "total_snapshot_deletion_failures": 0
}

启动快照生命周期管理 API

edit

开启快照生命周期管理 (SLM)。

请求

edit

POST /_slm/start

先决条件

edit

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

描述

edit

如果SLM插件未运行，则启动它。 当集群形成时，SLM会自动启动。 如果使用停止快照生命周期管理停止了SLM，则需要手动启动SLM。

查询参数

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

示例

edit

启动SLM插件：

POST _slm/start

如果成功，此请求将返回：

{
  "acknowledged": true
}

停止快照生命周期管理 API

edit

关闭快照生命周期管理（SLM）。

请求

edit

POST /_slm/stop

先决条件

edit

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

描述

edit

停止所有快照生命周期管理（SLM）操作并停止SLM插件。 当你在对集群进行维护并需要防止SLM对你的数据流或索引执行任何操作时，这非常有用。 停止SLM不会停止任何正在进行的快照。 即使SLM已停止，你也可以使用执行快照生命周期策略手动触发快照。

API在请求被确认后立即返回响应，但插件可能会继续运行，直到正在进行中的操作完成并且可以安全停止。

使用 获取快照生命周期管理状态 来查看 SLM 是否正在运行。

查询参数

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

示例

edit
POST _slm/stop
« Snapshot and restore APIs SQL APIs »