Link Search Menu Expand Document Documentation Menu
文档

ISM API

使用索引状态管理操作以编程方式处理策略和托管索引。

目录

创建策略

1.0 版引入

创建策略。

请求示例

PUT _plugins/_ism/policies/policy_1
{
  "policy": {
    "description": "ingesting logs",
    "default_state": "ingest",
    "states": [
      {
        "name": "ingest",
        "actions": [
          {
            "rollover": {
              "min_doc_count": 5
            }
          }
        ],
        "transitions": [
          {
            "state_name": "search"
          }
        ]
      },
      {
        "name": "search",
        "actions": [],
        "transitions": [
          {
            "state_name": "delete",
            "conditions": {
              "min_index_age": "5m"
            }
          }
        ]
      },
      {
        "name": "delete",
        "actions": [
          {
            "delete": {}
          }
        ],
        "transitions": []
      }
    ]
  }
}

示例响应

{
  "_id": "policy_1",
  "_version": 1,
  "_primary_term": 1,
  "_seq_no": 7,
  "policy": {
    "policy": {
      "policy_id": "policy_1",
      "description": "ingesting logs",
      "last_updated_time": 1577990761311,
      "schema_version": 1,
      "error_notification": null,
      "default_state": "ingest",
      "states": [
        {
          "name": "ingest",
          "actions": [
            {
              "rollover": {
                "min_doc_count": 5
              }
            }
          ],
          "transitions": [
            {
              "state_name": "search"
            }
          ]
        },
        {
          "name": "search",
          "actions": [],
          "transitions": [
            {
              "state_name": "delete",
              "conditions": {
                "min_index_age": "5m"
              }
            }
          ]
        },
        {
          "name": "delete",
          "actions": [
            {
              "delete": {}
            }
          ],
          "transitions": []
        }
      ]
    }
  }
}

添加策略

1.0 版引入

向索引添加策略。如果索引已存在策略，此操作不会更改该策略。

请求示例

POST _plugins/_ism/add/index_1
{
  "policy_id": "policy_1"
}

示例响应

{
  "updated_indices": 1,
  "failures": false,
  "failed_indices": []
}

如果您在向索引添加策略时使用通配符 *，ISM 插件会将 * 解释为所有索引，包括 .opendistro-security 等系统索引，这些索引存储用户、角色和租户。策略中的删除操作可能会意外删除集群中的所有用户角色和租户。请勿使用宽泛的 * 通配符，而是在使用 _ism/add API 指定索引时添加前缀，例如 my-logs*。

更新策略

1.0 版引入

更新策略。使用 seq_no 和 primary_term 参数更新现有策略。如果这些数字与现有策略不匹配或策略不存在，ISM 将抛出错误。

当前应用于您的索引的策略可能不是最新可用的策略。要查看当前应用于您的索引的策略，请参阅解释索引。要获取最新版本的策略，请参阅获取策略。

请求示例

PUT _plugins/_ism/policies/policy_1?if_seq_no=7&if_primary_term=1
{
  "policy": {
    "description": "ingesting logs",
    "default_state": "ingest",
    "states": [
      {
        "name": "ingest",
        "actions": [
          {
            "rollover": {
              "min_doc_count": 5
            }
          }
        ],
        "transitions": [
          {
            "state_name": "search"
          }
        ]
      },
      {
        "name": "search",
        "actions": [],
        "transitions": [
          {
            "state_name": "delete",
            "conditions": {
              "min_index_age": "5m"
            }
          }
        ]
      },
      {
        "name": "delete",
        "actions": [
          {
            "delete": {}
          }
        ],
        "transitions": []
      }
    ]
  }
}

示例响应

{
  "_id": "policy_1",
  "_version": 2,
  "_primary_term": 1,
  "_seq_no": 10,
  "policy": {
    "policy": {
      "policy_id": "policy_1",
      "description": "ingesting logs",
      "last_updated_time": 1577990934044,
      "schema_version": 1,
      "error_notification": null,
      "default_state": "ingest",
      "states": [
        {
          "name": "ingest",
          "actions": [
            {
              "rollover": {
                "min_doc_count": 5
              }
            }
          ],
          "transitions": [
            {
              "state_name": "search"
            }
          ]
        },
        {
          "name": "search",
          "actions": [],
          "transitions": [
            {
              "state_name": "delete",
              "conditions": {
                "min_index_age": "5m"
              }
            }
          ]
        },
        {
          "name": "delete",
          "actions": [
            {
              "delete": {}
            }
          ],
          "transitions": []
        }
      ]
    }
  }
}

获取策略

1.0 版引入

按 policy_id 获取策略。

请求示例

GET _plugins/_ism/policies/policy_1

示例响应

{
  "_id": "policy_1",
  "_version": 2,
  "_seq_no": 10,
  "_primary_term": 1,
  "policy": {
    "policy_id": "policy_1",
    "description": "ingesting logs",
    "last_updated_time": 1577990934044,
    "schema_version": 1,
    "error_notification": null,
    "default_state": "ingest",
    "states": [
      {
        "name": "ingest",
        "actions": [
          {
            "rollover": {
              "min_doc_count": 5
            }
          }
        ],
        "transitions": [
          {
            "state_name": "search"
          }
        ]
      },
      {
        "name": "search",
        "actions": [],
        "transitions": [
          {
            "state_name": "delete",
            "conditions": {
              "min_index_age": "5m"
            }
          }
        ]
      },
      {
        "name": "delete",
        "actions": [
          {
            "delete": {}
          }
        ],
        "transitions": []
      }
    ]
  }
}

从索引中移除策略

1.0 版引入

从索引中移除所有 ISM 策略。

请求示例

POST _plugins/_ism/remove/index_1

示例响应

{
  "updated_indices": 1,
  "failures": false,
  "failed_indices": []
}

更新托管索引策略

1.0 版引入

将托管索引策略更新为新策略（或策略的新版本）。您可以使用索引模式一次更新多个索引。在更新多个索引时，您可能希望包含一个状态过滤器，以仅影响特定的托管索引。更改策略会过滤掉所有现有托管索引，并且仅将更改应用于您指定状态的索引。您还可以明确指定更改策略生效后托管索引将转换到的状态。

策略更改是一个异步后台进程。这些更改会被排队，并且不会立即由后台进程执行。这种执行延迟可以保护当前正在运行的托管索引不被置于损坏状态。如果您要更改的策略只有一些小的配置更改，则更改会立即生效。例如，如果策略将滚动条件中的 min_index_age 参数从 1000d 更改为 100d，则此更改将在下次执行时立即生效。如果更改修改了索引当前所处状态的状态、操作或操作顺序，则更改将在当前状态结束时发生，然后才转换为新状态。

在此示例中，应用于 index_1 索引的策略更改为 policy_1，这可能是一个全新的策略，也可能是其现有策略的更新版本。该过程仅在索引当前处于 searches 状态时应用更改。此策略更改生效后，index_1 将转换为 delete 状态。

请求示例

POST _plugins/_ism/change_policy/index_1
{
  "policy_id": "policy_1",
  "state": "delete",
  "include": [
    {
      "state": "searches"
    }
  ]
}

示例响应

{
  "updated_indices": 0,
  "failures": false,
  "failed_indices": []
}

重试失败的索引

1.0 版引入

重试索引的失败操作。要使重试调用成功，ISM 必须管理该索引，且该索引必须处于失败状态。您可以使用索引模式 (*) 重试多个失败的索引。

请求示例

POST _plugins/_ism/retry/index_1
{
  "state": "delete"
}

示例响应

{
  "updated_indices": 0,
  "failures": false,
  "failed_indices": []
}

解释索引

1.0 版引入

获取索引的当前状态。您可以使用索引模式获取多个索引的状态。

请求示例

GET _plugins/_ism/explain/index_1

示例响应

{
  "index_1": {
    "index.plugins.index_state_management.policy_id": "policy_1"
  }
}

（可选）您可以将 show_policy 参数添加到请求路径中，以获取当前应用于您的索引的策略，这有助于查看应用于您索引的策略是否为最新策略。要获取最新策略，请参阅获取策略 API。

请求示例

GET _plugins/_ism/explain/index_1?show_policy=true

示例响应

{
  "index_1": {
    "index.plugins.index_state_management.policy_id": "sample-policy",
    "index.opendistro.index_state_management.policy_id": "sample-policy",
    "index": "index_1",
    "index_uuid": "gCFlS_zcTdih8xyxf3jQ-A",
    "policy_id": "sample-policy",
    "enabled": true,
    "policy": {
      "policy_id": "sample-policy",
      "description": "ingesting logs",
      "last_updated_time": 1647284980148,
      "schema_version": 13,
      "error_notification": null,
      "default_state": "ingest",
      "states": [...],
      "ism_template": null
    }
  },
  "total_managed_indices": 1
}

自 ODFE 1.13.0 版起，plugins.index_state_management.policy_id 设置已被弃用。为了保持一致性，我们仍在响应 API 中保留此字段。

删除策略

1.0 版引入

按 policy_id 删除策略。

请求示例

DELETE _plugins/_ism/policies/policy_1

示例响应

{
  "_index": ".opendistro-ism-config",
  "_id": "policy_1",
  "_version": 3,
  "result": "deleted",
  "forced_refresh": true,
  "_shards": {
    "total": 2,
    "successful": 2,
    "failed": 0
  },
  "_seq_no": 15,
  "_primary_term": 1
}

错误预防验证

2.4 版引入

ISM 允许您自动运行操作。但是，运行操作可能会因多种原因而失败。您可以使用错误预防验证来测试操作，以排除故障。

要启用错误预防验证，请将 plugins.index_state_management.action_validation.enabled 设置为 true

PUT _cluster/settings
{
   "persistent":{
      "plugins.index_state_management.action_validation.enabled": true
   }
}

示例响应

{
  "acknowledged" : true,
  "persistent" : {
    "plugins" : {
      "index_state_management" : {
        "validation_action" : {
          "enabled" : "true"
        }
      }
    }
  },
  "transient" : { }
}

要检查错误预防验证状态和消息，请将 validate_action=true 传递给 _plugins/_ism/explain 端点

GET _plugins/_ism/explain/test-000001?validate_action=true

示例响应

响应包含一个额外的 validate 对象，其中包含验证消息和状态

{
  "test-000001" : {
    "index.plugins.index_state_management.policy_id" : "test_rollover",
    "index.opendistro.index_state_management.policy_id" : "test_rollover",
    "index" : "test-000001",
    "index_uuid" : "CgKsxFmQSIa8dWqpbSJmyA",
    "policy_id" : "test_rollover",
    "policy_seq_no" : -2,
    "policy_primary_term" : 0,
    "rolled_over" : false,
    "index_creation_date" : 1667410460649,
    "state" : {
      "name" : "rollover",
      "start_time" : 1667410766045
    },
    "action" : {
      "name" : "rollover",
      "start_time" : 1667411127803,
      "index" : 0,
      "failed" : false,
      "consumed_retries" : 0,
      "last_retry_time" : 0
    },
    "step" : {
      "name" : "attempt_rollover",
      "start_time" : 1667411127803,
      "step_status" : "starting"
    },
    "retry_info" : {
      "failed" : true,
      "consumed_retries" : 0
    },
    "info" : {
      "message" : "Previous action was not able to update IndexMetaData."
    },
    "enabled" : false,
    "validate" : {
      "validation_message" : "Missing rollover_alias index setting [index=test-000001]",
      "validation_status" : "re_validating"
    }
  },
  "total_managed_indices" : 1
}

如果您传递 validate_action=false 或不向 _plugins/_ism/explain 端点传递 validate_action 值，则响应将不包含错误预防验证状态和消息

GET _plugins/_ism/explain/test-000001?validate_action=false

或

GET _plugins/_ism/explain/test-000001

示例响应

{
  "test-000001" : {
    "index.plugins.index_state_management.policy_id" : "test_rollover",
    "index.opendistro.index_state_management.policy_id" : "test_rollover",
    "index" : "test-000001",
    "index_uuid" : "CgKsxFmQSIa8dWqpbSJmyA",
    "policy_id" : "test_rollover",
    "policy_seq_no" : -2,
    "policy_primary_term" : 0,
    "rolled_over" : false,
    "index_creation_date" : 1667410460649,
    "state" : {
      "name" : "rollover",
      "start_time" : 1667410766045
    },
    "action" : {
      "name" : "rollover",
      "start_time" : 1667411127803,
      "index" : 0,
      "failed" : false,
      "consumed_retries" : 0,
      "last_retry_time" : 0
    },
    "step" : {
      "name" : "attempt_rollover",
      "start_time" : 1667411127803,
      "step_status" : "starting"
    },
    "retry_info" : {
      "failed" : true,
      "consumed_retries" : 0
    },
    "info" : {
      "message" : "Previous action was not able to update IndexMetaData."
    },
    "enabled" : false
  },
  "total_managed_indices" : 1
}
剩余 350 字符

有问题？。

想贡献？或。