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

示例

edit

以下示例创建了一个名为 my_policy 的新策略。此外，您可以使用 _meta 参数向策略添加任意元数据，_meta 参数是可选的，不会被 Elasticsearch 自动生成或使用。要取消设置 _meta，请在不指定的情况下替换策略。要检查 _meta，您可以使用获取生命周期策略 API。

PUT _ilm/policy/my_policy
{
  "policy": {
    "_meta": {
      "description": "used for nginx log",
      "project": {
        "name": "myProject",
        "department": "myDepartment"
      }
    },
    "phases": {
      "warm": {
        "min_age": "10d",
        "actions": {
          "forcemerge": {
            "max_num_segments": 1
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

如果请求成功，您将收到以下结果：

{
  "acknowledged": true
}

获取生命周期策略 API

edit

检索一个生命周期策略。

请求

edit

GET _ilm/policy

GET _ilm/policy/

先决条件

edit

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

描述

edit

返回指定的策略定义。包括策略版本和最后修改日期。如果没有指定策略，则返回所有已定义的策略。

路径参数

edit

<policy_id>: （可选，字符串）策略的标识符。

查询参数

edit

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

示例

edit

以下示例检索 my_policy：

GET _ilm/policy/my_policy

如果请求成功，响应的主体包含策略定义：

{
  "my_policy": {
    "version": 1, 
    "modified_date": 82392349, 
    "policy": {
      "phases": {
        "warm": {
          "min_age": "10d",
          "actions": {
            "forcemerge": {
              "max_num_segments": 1
            }
          }
        },
        "delete": {
          "min_age": "30d",
          "actions": {
            "delete": {
              "delete_searchable_snapshot": true
            }
          }
        }
      }
    },
    "in_use_by" : { 
      "indices" : [],
      "data_streams" : [],
      "composable_templates" : []
    }
  }
}

	每当策略更新时，策略版本都会递增
	此政策上次修改时间
	哪些索引、数据流或模板当前使用此策略

删除生命周期策略 API

edit

删除一个索引生命周期策略。

请求

edit

DELETE _ilm/policy/

先决条件

edit

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

描述

edit

删除指定的生命周期策略定义。您不能删除当前正在使用的策略。如果该策略正在用于管理任何索引，请求将失败并返回错误。

路径参数

edit

<policy_id>: （必需，字符串）策略的标识符。

查询参数

edit

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

示例

edit

以下示例删除 my_policy：

DELETE _ilm/policy/my_policy

当策略成功删除时，您会收到以下结果：

{
  "acknowledged": true
}

移动到生命周期步骤 API

edit

触发执行生命周期策略中的特定步骤。

请求

edit

POST _ilm/move/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须对正在管理的索引具有manage_ilm权限才能使用此API。更多信息，请参阅安全权限。

描述

edit

此操作可能导致数据丢失。手动将索引导入特定步骤会执行该步骤，即使它已经执行过。这是一个潜在的破坏性操作，应视为专家级API。

手动将索引移动到指定步骤并执行该步骤。您必须在请求的正文中同时指定当前步骤和要执行的步骤。

如果当前步骤与索引当前正在执行的步骤不匹配，请求将会失败。这是为了防止索引从意外的步骤移动到下一步。

在指定索引将移动到的目标（next_step）时，name 或 action 和 name 字段都是可选的。如果仅指定了阶段，索引将移动到目标阶段中第一个操作的第一个步骤。如果指定了阶段和操作，索引将移动到指定阶段中指定操作的第一个步骤。只有在 ILM 策略中指定的操作才被视为有效，索引不能移动到其策略中不存在的步骤。

路径参数

edit

<index>: （必需，字符串）索引的标识符。

查询参数

edit

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

请求体

edit

current_step

（必需，对象）

Properties of current_step

phase: (必需，字符串) 当前阶段的名称。必须与explain API返回的阶段匹配。
action: (必需，字符串) 当前操作的名称。必须与explain API返回的操作匹配。
name: (必需，字符串) 当前步骤的名称。必须与explain API返回的步骤匹配。如果ILM在执行操作时遇到问题，它会停止执行策略并转换到ERROR步骤。如果您在排除故障后尝试推进策略，您需要将此ERROR步骤指定为当前步骤。有关更多信息，请参阅ILM错误处理。

next_step

（必需，对象）

Properties of next_step

phase: (必需，字符串) 包含您要执行或恢复的操作的阶段的名称。
action: (可选，字符串) 您要执行或恢复的操作名称。如果使用name，则必需。
name: (可选，字符串) 要移动到并执行的步骤的名称。如果使用action，则必需。

示例

edit

以下示例将 my-index-000001 从初始步骤移动到 forcemerge 步骤：

POST _ilm/move/my-index-000001
{
  "current_step": { 
    "phase": "new",
    "action": "complete",
    "name": "complete"
  },
  "next_step": { 
    "phase": "warm",
    "action": "forcemerge", 
    "name": "forcemerge" 
  }
}

	索引预计所处的步骤
	您想要执行的步骤
	可选的操作，索引将被移动到该操作
	可选的步骤名称，索引将被移动到该步骤

如果请求成功，您将收到以下结果：

{
  "acknowledged": true
}

如果索引不在由current_step指定的new阶段，请求将会失败。

以下示例将 my-index-000001 从热阶段的末尾推入温阶段的开始：

POST _ilm/move/my-index-000001
{
  "current_step": {
    "phase": "hot",
    "action": "complete",
    "name": "complete"
  },
  "next_step": {
    "phase": "warm"
  }
}

从索引中移除策略 API

edit

从索引或数据流的备份索引中移除分配的生命周期策略。

请求

edit

POST /_ilm/remove

先决条件

edit

如果启用了Elasticsearch安全功能，您必须对正在管理的索引具有manage_ilm权限才能使用此API。更多信息，请参阅安全权限。

描述

edit

对于索引，remove lifecycle policy API 移除分配的生命周期策略并停止管理指定的索引。

对于数据流，API 会移除分配给流支持索引的任何生命周期策略，并停止管理这些索引。

路径参数

edit

<target>: (必需，字符串) 以逗号分隔的数据流、索引和别名的列表，用于目标。支持通配符 (*)。要针对所有数据流和索引，请使用 * 或 _all。

查询参数

edit

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

示例

edit

以下示例从 my-index-000001 中移除分配的策略。

POST my-index-000001/_ilm/remove

如果请求成功，您将收到以下结果：

{
  "has_failures" : false,
  "failed_indexes" : []
}

重试策略执行 API

edit

重试执行处于ERROR步骤的索引的生命周期策略。

请求

edit

POST /_ilm/retry

先决条件

edit

如果启用了Elasticsearch安全功能，您必须对正在管理的索引具有manage_ilm权限才能使用此API。更多信息，请参阅安全权限。

描述

edit

将策略回退到错误发生的步骤并执行该步骤。使用ILM Explain API来确定索引是否处于ERROR步骤。

路径参数

edit

<index>: (必需，字符串) 以逗号分隔的索引标识符，用于重试。

查询参数

edit

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

示例

edit

以下示例重试了 my-index-000001 的策略。

POST my-index-000001/_ilm/retry

如果请求成功，您将收到以下结果：

{
  "acknowledged": true
}

获取索引生命周期管理状态 API

edit

检索当前的索引生命周期管理 (ILM) 状态。

您可以使用启动 ILM 和停止 ILM API 来启动或停止索引生命周期管理。

请求

edit

GET /_ilm/status

先决条件

edit

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

查询参数

edit

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

响应体

edit

operation_mode

(字符串) ILM 的当前操作模式。

可能的 operation_mode 值

RUNNING: ILM 正在运行。
STOPPING: ILM 正在完成敏感操作，例如 shrink，这些操作正在进行中。当这些操作完成后，ILM 将移动到 STOPPED。
STOPPED: ILM 没有运行。

示例

edit

以下示例获取ILM插件状态。

GET _ilm/status

如果请求成功，响应的主体将显示操作模式：

{
  "operation_mode": "RUNNING"
}

解释生命周期 API

edit

检索一个或多个索引的当前生命周期状态。对于数据流，API检索流的后备索引的当前生命周期状态。

请求

edit

GET /_ilm/explain

先决条件

edit

如果启用了Elasticsearch的安全功能，您必须对正在管理的索引具有view_index_metadata或manage_ilm或两者权限才能使用此API。有关更多信息，请参阅安全权限。

描述

edit

检索有关索引当前生命周期状态的信息，例如当前正在执行的阶段、操作和步骤。显示索引进入每个阶段的时间、正在运行的阶段的定义以及有关任何故障的信息。

路径参数

edit

<target>: (必需，字符串) 以逗号分隔的数据流、索引和别名列表，用于目标。支持通配符 (*)。要针对所有数据流和索引，请使用 * 或 _all。

查询参数

edit

only_managed: (可选，布尔值) 过滤返回的索引，仅返回由 ILM 管理的索引。
only_errors: (可选，布尔值) 过滤返回的索引，仅返回由 ILM 管理且处于错误状态的索引，这些错误状态可能是由于执行策略时遇到错误，或尝试使用不存在的策略导致的。
master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

示例

edit

以下示例检索my-index-000001的生命周期状态：

GET my-index-000001/_ilm/explain?human

当索引管理首次由ILM接管时，explain显示索引已被管理并处于new阶段：

{
  "indices": {
    "my-index-000001": {
      "index": "my-index-000001",
      "index_creation_date_millis": 1538475653281,        
      "index_creation_date": "2018-10-15T13:45:21.981Z",
      "time_since_index_creation": "15s",                 
      "managed": true,                                    
      "policy": "my_policy",                              
      "lifecycle_date_millis": 1538475653281,             
      "lifecycle_date": "2018-10-15T13:45:21.981Z",
      "age": "15s",                                       
      "phase": "new",
      "phase_time_millis": 1538475653317,                 
      "phase_time": "2018-10-15T13:45:22.577Z",
      "action": "complete"
      "action_time_millis": 1538475653317,                
      "action_time": "2018-10-15T13:45:22.577Z",
      "step": "complete",
      "step_time_millis": 1538475653317,                  
      "step_time": "2018-10-15T13:45:22.577Z"
    }
  }
}

	当索引被创建时，这个时间戳用于确定何时进行滚动更新
	自索引创建以来的时间（用于通过`max_age`计算何时滚动更新索引）
	显示索引是否由ILM管理。如果索引不由ILM管理，则不会显示其他字段
	ILM 用于此索引的策略名称
	用于 `min_age` 的时间戳
	索引的年龄（用于计算何时进入下一阶段）
	当指数进入当前阶段时
	当索引进入当前操作时
	当索引进入当前步骤时

一旦策略在索引上运行，响应中会包含一个phase_execution对象，显示当前阶段的定义。对底层策略的更改不会影响此索引，直到当前阶段完成。

{
  "indices": {
    "test-000069": {
      "index": "test-000069",
      "index_creation_date_millis": 1538475653281,
      "time_since_index_creation": "25.14s",
      "managed": true,
      "policy": "my_lifecycle3",
      "lifecycle_date_millis": 1538475653281,
      "lifecycle_date": "2018-10-15T13:45:21.981Z",
      "age": "25.14s",
      "phase": "hot",
      "phase_time_millis": 1538475653317,
      "phase_time": "2018-10-15T13:45:22.577Z",
      "action": "rollover",
      "action_time_millis": 1538475653317,
      "action_time": "2018-10-15T13:45:22.577Z",
      "step": "attempt-rollover",
      "step_time_millis": 1538475653317,
      "step_time": "2018-10-15T13:45:22.577Z",
      "phase_execution": {
        "policy": "my_lifecycle3",
        "phase_definition": { 
          "min_age": "0ms",
          "actions": {
            "rollover": {
              "max_age": "30s",
              "max_primary_shard_docs": 200000000, 
              "min_docs": 1
            }
          }
        },
        "version": 3, 
        "modified_date": "2018-10-15T13:21:41.576Z", 
        "modified_date_in_millis": 1539609701576 
      }
    }
  }
}

	从指定策略加载的JSON阶段定义，当索引进入此阶段时
	滚动操作包括默认的 `max_primary_shard_docs` 和 `min_docs` 条件。更多信息请参见 ILM 滚动选项。
	加载的策略版本
	加载的策略上次修改的日期
	加载的策略上次修改的时间戳

如果ILM正在等待一个步骤完成，响应将包含正在对索引执行的步骤的状态信息。

{
  "indices": {
    "test-000020": {
      "index": "test-000020",
      "index_creation_date_millis": 1538475653281,
      "time_since_index_creation": "4.12m",
      "managed": true,
      "policy": "my_lifecycle3",
      "lifecycle_date_millis": 1538475653281,
      "lifecycle_date": "2018-10-15T13:45:21.981Z",
      "age": "4.12m",
      "phase": "warm",
      "phase_time_millis": 1538475653317,
      "phase_time": "2018-10-15T13:45:22.577Z",
      "action": "allocate",
      "action_time_millis": 1538475653317,
      "action_time": "2018-10-15T13:45:22.577Z",
      "step": "check-allocation",
      "step_time_millis": 1538475653317,
      "step_time": "2018-10-15T13:45:22.577Z",
      "step_info": { 
        "message": "Waiting for all shard copies to be active",
        "shards_left_to_allocate": -1,
        "all_shards_active": false,
        "number_of_replicas": 2
      },
      "phase_execution": {
        "policy": "my_lifecycle3",
        "phase_definition": {
          "min_age": "0ms",
          "actions": {
            "allocate": {
              "number_of_replicas": 2,
              "include": {
                "box_type": "warm"
              },
              "exclude": {},
              "require": {}
            },
            "forcemerge": {
              "max_num_segments": 1
            }
          }
        },
        "version": 2,
        "modified_date": "2018-10-15T13:20:02.489Z",
        "modified_date_in_millis": 1539609602489
      }
    }
  }
}

正在进行的步骤的状态。

如果索引处于ERROR步骤，说明在执行策略中的某个步骤时出现了问题，您需要采取行动以使索引进入下一步。在某些情况下，某些步骤可以安全地自动重试。为了帮助您诊断问题，explain响应显示了失败的步骤、提供错误信息的步骤信息，以及如果适用的话，关于失败步骤的重试尝试的信息。

{
  "indices": {
    "test-000056": {
      "index": "test-000056",
      "index_creation_date_millis": 1538475653281,
      "time_since_index_creation": "50.1d",
      "managed": true,
      "policy": "my_lifecycle3",
      "lifecycle_date_millis": 1538475653281,
      "lifecycle_date": "2018-10-15T13:45:21.981Z",
      "age": "50.1d",
      "phase": "hot",
      "phase_time_millis": 1538475653317,
      "phase_time": "2018-10-15T13:45:22.577Z",
      "action": "rollover",
      "action_time_millis": 1538475653317,
      "action_time": "2018-10-15T13:45:22.577Z",
      "step": "ERROR",
      "step_time_millis": 1538475653317,
      "step_time": "2018-10-15T13:45:22.577Z",
      "failed_step": "check-rollover-ready", 
      "is_auto_retryable_error": true, 
      "failed_step_retry_count": 1, 
      "step_info": { 
        "type": "cluster_block_exception",
        "reason": "index [test-000057/H7lF9n36Rzqa-KfKcnGQMg] blocked by: [FORBIDDEN/5/index read-only (api)",
        "index_uuid": "H7lF9n36Rzqa-KfKcnGQMg",
        "index": "test-000057"
      },
      "previous_step_info": { 
        "type": "cluster_block_exception",
        "reason": "index [test-000057/H7lF9n36Rzqa-KfKcnGQMg] blocked by: [FORBIDDEN/5/index read-only (api)",
        "index_uuid": "H7lF9n36Rzqa-KfKcnGQMg",
        "index": "test-000057"
      },
      "phase_execution": {
        "policy": "my_lifecycle3",
        "phase_definition": {
          "min_age": "0ms",
          "actions": {
            "rollover": {
              "max_age": "30s"
            }
          }
        },
        "version": 3,
        "modified_date": "2018-10-15T13:21:41.576Z",
        "modified_date_in_millis": 1539609701576
      }
    }
  }
}

	导致错误的步骤
	指示重试失败步骤是否可以克服错误。如果为真，ILM将自动重试失败的步骤。
	显示尝试自动重试执行失败步骤的次数。
	出了什么问题
	包含用于诊断目的的最后一个尝试或执行步骤的 `step_info` 字段（当其存在时）的副本，因为 `step_info` 在每次新尝试期间会被覆盖。

开始索引生命周期管理API

edit

启动索引生命周期管理 (ILM) 插件。

请求

edit

POST /_ilm/start

先决条件

edit

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

描述

edit

如果当前已停止，启动ILM插件。当集群形成时，ILM会自动启动。只有在使用停止ILM API停止了ILM时，才需要重新启动ILM。

查询参数

edit

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

示例

edit

以下示例启动ILM插件。

POST _ilm/start

如果请求成功，您将收到以下结果：

{
  "acknowledged": true
}

停止索引生命周期管理 API

edit

停止索引生命周期管理（ILM）插件。

请求

edit

POST /_ilm/stop

先决条件

edit

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

描述

edit

停止所有生命周期管理操作并停止ILM插件。这在您对集群进行维护并需要防止ILM对索引执行任何操作时非常有用。

API 在停止请求被确认后立即返回，但插件可能会继续运行，直到正在进行中的操作完成并且插件可以安全停止。使用获取 ILM 状态 API 来查看 ILM 是否正在运行。

查询参数

edit

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

示例

edit

以下示例停止ILM插件。

POST _ilm/stop

如果请求没有遇到错误，您将收到以下结果：

{
  "acknowledged": true
}

迁移到数据层路由API

edit

将索引、ILM策略以及传统的、可组合的和组件模板从使用自定义节点属性和基于属性的分配过滤器切换到使用数据层，并可选地删除一个传统的索引模板。使用节点角色使ILM能够自动在数据层之间移动索引。

迁移自定义节点属性路由可以手动执行，如将索引分配过滤器迁移到节点角色页面所示。

此API提供了一种自动执行迁移指南中列出的四个手动步骤中的三个的方法：

请求

edit

POST /_ilm/migrate_to_data_tiers

API接受一个可选的body，允许您指定：

要删除的遗留索引模板名称。默认为无。
用于索引和ILM策略分配过滤的自定义节点属性名称。默认为 data。

先决条件

edit

在执行迁移之前，必须停止ILM。使用停止ILM API 来停止ILM，并使用获取状态API来等待，直到报告的操作模式为STOPPED。

查询参数

edit

dry_run: (可选, 布尔值) 如果 true，模拟从基于节点属性分配过滤器迁移到数据层的过程，但不执行迁移。这提供了一种方法来检索需要迁移的索引和ILM策略。默认为 false。

当模拟迁移时（即 dry_run 为 true），ILM 不需要停止。

示例

edit

以下示例将索引、ILM策略、旧版模板、可组合模板和组件模板从使用custom_attribute_name节点属性定义自定义分配过滤的方式迁移，并删除系统中存在的名为global-template的旧版模板。

POST /_ilm/migrate_to_data_tiers
{
  "legacy_template_to_delete": "global-template",
  "node_attribute": "custom_attribute_name"
}

如果请求成功，将收到类似以下的响应：

{
  "dry_run": false,
  "removed_legacy_template":"global-template", 
  "migrated_ilm_policies":["policy_with_allocate_action"], 
  "migrated_indices":["warm-index-to-migrate-000001"], 
  "migrated_legacy_templates":["a-legacy-template"], 
  "migrated_composable_templates":["a-composable-template"], 
  "migrated_component_templates":["a-component-template"] 
}

	显示已删除的旧索引模板的名称。如果没有删除旧索引模板，则此项将缺失。
	已更新的ILM策略。
	已迁移到层偏好路由的索引。
	已更新的旧版索引模板，不再包含为提供的数据属性设置的自定义路由设置。
	已更新的可组合索引模板，不再包含针对所提供数据属性的自定义路由设置。
	已更新的组件模板，不再包含为所提供数据属性设置的自定义路由配置。

« Index APIs Inference APIs »

索引生命周期管理API