description: (可选，字符串) 预定事件的描述。
end_time: (必需，日期) 预定事件结束的时间戳，以自纪元以来的毫秒数或ISO 8601格式表示。
start_time: (必需，日期) 预定事件开始的时间戳，以自纪元以来的毫秒数或ISO 8601格式表示。
skip_results: (可选，布尔值) 如果为true，则在预定事件期间不会创建结果。默认值为true。
skip_model_update: (可选，布尔值) 如果为true，则在预定事件期间不会更新模型。默认值为true。
force_time_shift: (可选，整数) 允许你在异常检测器中按指定方向和秒数移动时间。这对于快速调整已知的夏令时(DST)事件非常有用。例如，为了在秋季DST事件期间考虑一小时的时间回退，请使用值-3600。该参数默认不设置。时间在预定事件开始时移动一次。移动量以秒为单位。

示例

edit

POST _ml/calendars/planned-outages/events
{
  "events" : [
    {"description": "event 1", "start_time": 1513641600000, "end_time": 1513728000000},
    {"description": "event 2", "start_time": 1513814400000, "end_time": 1513900800000},
    {"description": "event 3", "start_time": 1514160000000, "end_time": 1514246400000}
  ]
}

API返回以下结果：

{
  "events": [
    {
      "description": "event 1",
      "start_time": 1513641600000,
      "end_time": 1513728000000,
      "skip_result": true,
      "skip_model_update": true,
      "calendar_id": "planned-outages"
    },
    {
      "description": "event 2",
      "start_time": 1513814400000,
      "end_time": 1513900800000,
      "skip_result": true,
      "skip_model_update": true,
      "calendar_id": "planned-outages"
    },
    {
      "description": "event 3",
      "start_time": 1514160000000,
      "end_time": 1514246400000,
      "skip_result": true,
      "skip_model_update": true,
      "calendar_id": "planned-outages"
    }
  ]
}

POST _ml/calendars/dst-germany/events
{
  "events" : [
    {"description": "Fall 2024", "start_time": 1729994400000, "end_time": 1730167200000, "skip_result": false, "skip_model_update": false, "force_time_shift": -3600},
    {"description": "Spring 2025", "start_time": 1743296400000, "end_time": 1743469200000, "skip_result": false, "skip_model_update": false, "force_time_shift": 3600}
  ]
}

API返回以下结果：

{
  "events": [
    {
      "description": "Fall 2024",
      "start_time": 1729994400000,
      "end_time": 1730167200000,
      "skip_result": false,
      "skip_model_update": false,
      "force_time_shift": -3600,
      "calendar_id": "dst-germany"
    },
    {
      "description": "Spring 2025",
      "start_time": 1743296400000,
      "end_time": 1743469200000,
      "skip_result": false,
      "skip_model_update": false,
      "force_time_shift": 3600,
      "calendar_id": "dst-germany"
    }
  ]
}

将异常检测作业添加到日历 API

edit

将异常检测作业添加到日历中。

请求

edit

PUT _ml/calendars//jobs/

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

路径参数

edit

<calendar_id>: (必需, 字符串) 一个唯一标识日历的字符串。
<job_id>: (必需，字符串) 异常检测作业的标识符。它可以是作业标识符、组名或逗号分隔的作业或组列表。

示例

edit

PUT _ml/calendars/planned-outages/jobs/total-requests

API返回以下结果：

{
  "calendar_id": "planned-outages",
  "job_ids": [
    "total-requests"
  ]
}

关闭异常检测作业 API

edit

关闭一个或多个异常检测作业。

请求

edit

POST _ml/anomaly_detectors//_close

POST _ml/anomaly_detectors/,/_close

POST _ml/anomaly_detectors/_all/_close

先决条件

edit

需要manage_ml集群权限。此权限包含在machine_learning_admin内置角色中。

描述

edit

一个职位在其生命周期中可以被打开和关闭多次。

已关闭的工作无法接收数据或执行分析操作，但您仍然可以浏览和导航结果。

如果您关闭一个正在运行的数据馈送的异常检测作业，请求首先尝试停止数据馈送。此行为等同于使用与关闭作业请求相同的timeout和force参数调用停止数据馈送。

当你关闭一个作业时，它会运行一些维护任务，例如修剪模型历史记录、刷新缓冲区、计算最终结果并持久化模型快照。根据作业的大小，关闭和重新打开可能需要几分钟的时间。

关闭后，作业在集群上的开销最小，除了维护其元数据。因此，关闭不再需要处理数据的作业是一个最佳实践。

当一个指定了结束日期的数据馈送停止时，它会自动关闭其关联的作业。

如果您使用force查询参数，请求将在不执行相关操作（如刷新缓冲区和持久化模型快照）的情况下返回。因此，如果您希望在关闭作业API返回后作业处于一致状态，请不要使用此参数。force查询参数仅应在作业已经失败或您对作业最近可能产生或未来可能产生的结果不感兴趣的情况下使用。

路径参数

edit

<job_id>

(必需，字符串) 异常检测作业的标识符。它可以是作业标识符、组名或通配符表达式。

您可以通过使用 _all 或通过指定 * 作为作业标识符来关闭所有作业。

查询参数

edit

allow_no_match

(可选, 布尔值) 指定在请求时执行的操作：

包含通配符表达式且没有匹配的作业。
包含 _all 字符串或没有标识符且没有匹配项。
包含通配符表达式且只有部分匹配。

默认值为 true，在没有匹配项时返回一个空的 jobs 数组，在有部分匹配项时返回部分结果。如果此参数为 false，在没有匹配项或只有部分匹配项时，请求将返回 404 状态码。

force

(可选, 布尔值) 用于关闭失败的作业，或强制关闭未响应初始关闭请求的作业。

timeout

(可选，时间单位) 控制等待作业关闭的时间。默认值为30分钟。

请求体

edit

您还可以在请求体中指定查询参数（例如 allow_no_match 和 force）。

响应代码

edit

404 (Missing resources): 如果 allow_no_match 是 false，此代码表示没有与请求匹配的资源，或者只有部分匹配的请求。

示例

edit

POST _ml/anomaly_detectors/low_request_rate/_close

当作业关闭时，您会收到以下结果：

{
  "closed": true
}

创建异常检测作业 API

edit

实例化一个异常检测作业。

请求

edit

PUT _ml/anomaly_detectors/

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

如果你包含一个datafeed_config，你还必须拥有源索引上的read索引权限。

描述

edit

您必须使用 Kibana 或此 API 来创建异常检测作业。不要直接使用 Elasticsearch 索引 API 将作业放入 .ml-config 索引中。如果启用了 Elasticsearch 安全功能，请不要为用户提供 .ml-config 索引的 write 权限。
如果您包含一个 datafeed_config 并且启用了 Elasticsearch 安全功能，您的数据馈送会记住创建它的用户在创建时拥有的角色，并使用这些相同的角色运行查询。如果您提供了二次授权头，则将使用这些凭据。

路径参数

edit

<job_id>: (必需，字符串) 异常检测作业的标识符。此标识符可以包含小写字母数字字符（a-z 和 0-9）、连字符和下划线。它必须以字母数字字符开头和结尾。

请求体

edit

allow_lazy_open: (可选, 布尔值) 高级配置选项。指定当没有足够的机器学习节点容量立即将其分配到节点时，此作业是否可以打开。默认值为 false；如果找不到具有运行作业容量的机器学习节点，打开异常检测作业 API 将返回错误。但是，这也受集群范围的 xpack.ml.max_lazy_ml_nodes 设置的限制；请参阅高级机器学习设置。如果此选项设置为 true，打开异常检测作业 API 不会返回错误，并且作业将保持在 opening 状态，直到有足够的机器学习节点容量可用。

analysis_config

(必需的, 对象) 分析配置, 指定如何分析数据。创建作业后, 您不能更改分析配置; 所有属性都是信息性的。

Properties of analysis_config

bucket_span

(时间单位) 分析被聚合到的间隔的大小, 通常在 5m 和 1h 之间。此值应为整数天数或等于一天中整数个桶的数量; [8.1] 在 8.1 中已弃用。不符合这些建议的值已被弃用, 并在未来版本中将不允许使用 . 如果异常检测作业使用带有聚合的数据馈送, 此值还必须可被日期直方图聚合的间隔整除。默认值是 5m。有关更多信息, 请参阅桶跨度。

categorization_analyzer

(对象或字符串) 如果指定了categorization_field_name, 您还可以定义用于解释分类字段的分析器。此属性不能与categorization_filters同时使用。分类分析器指定了categorization_field在分类过程中如何被解释。语法与定义analyzer的语法非常相似, 用于Analyze endpoint。有关更多信息, 请参阅分类日志消息。

categorization_analyzer 字段可以指定为字符串或对象。如果它是字符串, 则必须引用内置分析器或由其他插件添加的分析器。如果它是对象, 则具有以下属性：

Properties of categorization_analyzer

char_filter: (字符串或对象数组) 一个或多个字符过滤器。除了内置字符过滤器, 其他插件可以提供更多字符过滤器。此属性是可选的。如果未指定, 则在分类之前不应用字符过滤器。如果您自定义分析器的其他方面, 并且需要实现与categorization_filters等效的功能（当自定义分析器的其他方面时, 不允许使用categorization_filters）, 请在此处添加它们作为模式替换字符过滤器。
tokenizer: (字符串或对象) 在应用字符过滤器后使用的分词器的名称或定义。如果 categorization_analyzer 指定为对象, 则此属性是必需的。机器学习提供了一个名为 ml_standard 的分词器, 该分词器以一种已被确定为在各种日志文件格式上产生良好分类结果的方式进行分词, 适用于英语日志。如果您想使用该分词器但更改字符或分词过滤器, 请在您的 categorization_analyzer 中指定 "tokenizer": "ml_standard"。此外, ml_classic 分词器也可用, 它以与产品旧版本（6.2 之前）中的非自定义分词器相同的方式进行分词。ml_classic 是 6.2 到 7.13 版本中的默认分类分词器, 因此如果您需要与在这些版本中创建的作业的默认分类相同, 请在您的 categorization_analyzer 中指定 "tokenizer": "ml_classic"。

从 Elasticsearch 8.10.0 开始, 使用了一个新的版本号来跟踪机器学习插件中的配置和状态变化。这个新的版本号与产品版本解耦, 并将独立递增。

filter: (字符串或对象数组) 一个或多个分词过滤器。除了内置分词过滤器, 其他插件可以提供更多分词过滤器。此属性是可选的。如果未指定, 则在分类之前不应用分词过滤器。

categorization_field_name

(字符串) 如果指定了此属性, 则指定字段的值将被分类。生成的类别必须在检测器中通过设置 by_field_name, over_field_name, 或 partition_field_name 为关键字 mlcategory 来使用。有关更多信息, 请参阅分类日志消息。

categorization_filters

(字符串数组) 如果指定了categorization_field_name, 您还可以定义可选过滤器。此属性期望一个正则表达式数组。这些表达式用于从分类字段值中过滤掉匹配的序列。您可以使用此功能通过排除在定义类别时考虑的序列来微调分类。例如, 您可以排除日志文件中出现的 SQL 语句。有关更多信息, 请参阅分类日志消息。此属性不能与categorization_analyzer同时使用。如果您只想定义在分词之前应用的简单正则表达式过滤器, 设置此属性是最简单的方法。如果您还想自定义分词器或分词后过滤, 请使用 categorization_analyzer 属性, 并将过滤器包含为 pattern_replace 字符过滤器。效果完全相同。

detectors

(数组) 一个检测器配置对象的数组。检测器配置对象指定作业分析哪些数据字段。它们还指定使用哪些分析函数。您可以为一个作业指定多个检测器。

如果 detectors 数组中不包含至少一个检测器, 则无法进行分析, 并会返回一个错误。

Properties of detectors

by_field_name: (字符串) 用于分割数据的字段。特别是, 此属性用于分析分割数据相对于其自身历史的情况。它用于在分割的上下文中查找异常值。

custom_rules

(数组) 一个自定义规则对象的数组, 使您能够自定义检测器的工作方式。例如, 规则可以指示检测器在何种条件下应跳过结果。Kibana将自定义规则称为作业规则。更多示例, 请参见使用自定义规则自定义检测器。

Properties of custom_rules

actions

(数组) 当规则适用时要触发的操作集合。如果指定了多个操作, 所有操作的效果将合并。可用的操作包括：

skip_result: 结果将不会被创建。这是默认值。除非您也指定 skip_model_update, 否则模型将照常更新相应的系列值。
skip_model_update: 该系列的值将不会用于更新模型。除非您也指定 skip_result, 否则结果将照常创建。此操作适用于某些值预期会持续异常且它们以某种方式影响模型, 从而对其余结果产生负面影响的情况。
force_time_shift: 此操作将按指定量在异常检测器内移动时间。这很有用, 例如, 可以快速适应已知的夏令时事件。此操作需要 params 对象中的 force_time_shift 参数。

params

(对象) 一组参数对象, 用于自定义在自定义规则中定义的操作 actions 数组。可用的参数（取决于指定的操作）包括： force_time_shift。

Properties of params

force_time_shift: (对象) 将 time_shift_amount 设置为要移动时间的秒数的带符号数字。

conditions

(数组) 一个可选的数值条件数组, 当规则适用时。规则必须要么有一个非空的范围, 要么至少有一个条件。多个条件通过逻辑AND组合在一起。一个条件具有以下属性：

Properties of conditions

applies_to: (字符串) 指定条件适用的结果属性。可用的选项是 actual, typical, diff_from_typical, time。如果您的检测器使用 lat_long, metric, rare, 或 freq_rare 函数, 您只能指定适用于 time 的条件。
operator: (字符串) 指定条件运算符。可用的选项是 gt (大于), gte (大于或等于), lt (小于) 和 lte (小于或等于)。
value: (双精度) 使用 operator 与 applies_to 字段进行比较的值。

scope: (对象) 规则适用的可选系列范围。规则必须具有非空范围或至少一个条件。默认情况下, 范围包括所有系列。范围允许用于在by_field_name、over_field_name</code

analysis_limits

(可选, 对象) 可以为在内存中保存数学模型所需的资源应用限制。这些限制是近似的，可以按作业设置。它们不控制其他进程使用的内存，例如 Elasticsearch Java 进程。

Properties of analysis_limits

categorization_examples_limit

(长整型) 每个类别在内存和结果数据存储中存储的最大示例数量。默认值是4。如果增加这个值，会有更多的示例可用，但这需要你有更多的存储空间。如果将这个值设置为0，则不会存储任何示例。

分类示例限制（categorization_examples_limit）仅适用于使用分类的分析。更多信息，请参阅分类日志消息。

model_memory_limit

(长整型或字符串) 分析处理所需的大致最大内存资源。一旦接近此限制，数据修剪将变得更加激进。超过此限制后，不再对新实体进行建模。在6.1及更高版本中创建的作业的默认值为1024mb。然而，如果xpack.ml.max_model_memory_limit设置的值大于0且小于1024mb，则使用该值。如果未设置xpack.ml.max_model_memory_limit，但设置了xpack.ml.use_auto_machine_memory_percent，则默认的model_memory_limit将设置为集群中可能分配的最大大小，上限为1024mb。默认值相对较小，以确保高资源使用是经过深思熟虑的决定。如果您有预期会分析高基数字段的作业，您可能需要使用更高的值。

从 Elasticsearch 8.10.0 开始，使用了一个新的版本号来跟踪机器学习插件中的配置和状态变化。这个新的版本号与产品版本解耦，并将独立递增。

如果你指定一个数字而不是字符串，单位将被假定为MiB。为了清晰起见，建议指定一个字符串。如果你指定一个字节大小单位为b或kb，并且该数字不等于一个离散的兆字节数，它将被向下舍入到最接近的MiB。最小有效值是1 MiB。如果你指定一个小于1 MiB的值，将会发生错误。有关支持的字节大小单位的更多信息，请参阅字节大小单位。

如果您为 xpack.ml.max_model_memory_limit 设置指定了一个值，当您尝试创建 model_memory_limit 值大于该设置值的作业时，将会发生错误。更多信息，请参阅 Elasticsearch 中的机器学习设置。

background_persist_interval

(可选, 时间单位) 高级配置选项。每次周期性持久化模型之间的时间间隔。默认值是3到4小时之间的随机值，以避免所有作业在完全相同的时间持久化。允许的最小值是1小时。

对于非常大的模型（几个GB），持久化可能需要10-20分钟，因此不要将background_persist_interval值设置得太低。

custom_settings

(可选, 对象) 高级配置选项。包含关于作业的自定义元数据。例如，它可以包含自定义URL信息，如在向机器学习结果添加自定义URL中所示。

daily_model_snapshot_retention_after_days

(可选，长整型) 高级配置选项，影响此作业的旧模型快照的自动删除。它指定了一个时间段（以天为单位），在此时间段后，每天仅保留第一个快照。此时间段相对于此作业的最新快照的时间戳。有效值范围从0到model_snapshot_retention_days。对于新作业，默认值为1。对于7.8.0版本之前创建的作业，默认值与model_snapshot_retention_days匹配。有关更多信息，请参阅模型快照。

从 Elasticsearch 8.10.0 开始，使用了一个新的版本号来跟踪机器学习插件中的配置和状态变化。这个新的版本号与产品版本解耦，并将独立递增。

data_description

(必需，对象) 数据描述定义了在使用post data API向作业发送数据时输入数据的格式。请注意，当使用数据馈送时，只需设置time_field，其余属性会自动设置。当通过post data API接收数据时，数据不会存储在Elasticsearch中。仅保留异常检测的结果。

Properties of data_description

format: (字符串) 目前仅支持 xcontent 格式，这是默认值。
time_field: (字符串) 包含时间戳的字段的名称。默认值是 time。
time_format: (字符串) 时间格式，可以是 epoch、epoch_ms 或自定义模式。默认值是 epoch，表示 UNIX 或 Epoch 时间（自 1970 年 1 月 1 日以来的秒数）。值 epoch_ms 表示时间是从 Epoch 时间以来的毫秒数。epoch 和 epoch_ms 时间格式接受整数或实数值。

自定义模式必须符合 Java DateTimeFormatter 类。在使用日期时间格式化模式时，建议您提供完整的日期、时间和时区。例如：yyyy-MM-dd'T'HH:mm:ssX。如果您指定的模式不足以生成完整的 timestamp，作业创建将失败。

datafeed_config

(可选，对象) 数据馈送，用于从Elasticsearch中检索数据，供作业分析。每个异常检测作业只能关联一个数据馈送。

Properties of datafeed

aggregations

(可选, 对象) 如果设置，数据馈送执行聚合搜索。对聚合的支持有限，应仅与低基数数据一起使用。有关更多信息，请参阅 Aggregating data for faster performance。

chunking_config

(可选, 对象) 数据馈送可能需要搜索长时间段，例如几个月或几年。为了确保Elasticsearch的负载得到管理，这种搜索被分割成时间块。块配置控制这些时间块的大小如何计算，这是一个高级配置选项。

Properties of chunking_config

mode

(字符串) 有三种可用模式：

auto: 块大小是动态计算的。这是默认值，当数据馈送不使用聚合时推荐使用。
manual: 根据指定的 time_span 应用分块。当数据馈送使用聚合时使用此模式。
off: 不应用分块。

time_span

(时间单位) 每个搜索将查询的时间跨度。此设置仅在模式设置为 manual 时适用。例如：3h。

datafeed_id

(可选, 字符串) 一个唯一标识数据流的数字字符串。此标识符可以包含小写字母数字字符（a-z 和 0-9）、连字符和下划线。它必须以字母数字字符开头和结尾。

默认为与异常检测作业相同的ID。

delayed_data_check_config

(可选, 对象) 指定数据馈送是否检查缺失数据以及窗口的大小。例如：{"enabled": true, "check_window": "1h"}。

数据馈送可以选择性地搜索已经读取的索引，以确定是否有数据随后被添加到索引中。如果发现数据缺失，这表明query_delay选项设置过低，数据在数据馈送通过该时间点后才被索引。请参阅处理延迟数据。

此检查仅在实时数据馈送上运行。

Properties of delayed_data_check_config

check_window: (时间单位) 搜索延迟数据的时间窗口。此窗口以最新的最终桶结束。它默认为 null，这会导致在实时数据馈送运行时计算适当的 check_window。特别是，默认的 check_window 跨度计算基于 2h 或 8 * bucket_span 的最大值。
enabled: (布尔值) 指定数据馈送是否定期检查延迟数据。默认为 true。

frequency

(可选, 时间单位) 数据馈送在实时运行时计划查询的时间间隔。默认值是短桶跨度的桶跨度，或长桶跨度的桶跨度的一个合理分数。例如：150s。当 frequency 短于桶跨度时，最后（部分）桶的临时结果会被写入，然后最终被完整桶的结果覆盖。如果数据馈送使用聚合，此值必须可被日期直方图聚合的间隔整除。

indices

(必需，数组) 索引名称的数组。支持通配符。例如： ["it_ops_metrics", "server*"]。

如果任何索引位于远程集群中，则机器学习节点需要具有remote_cluster_client角色。

indices_options

(可选, 对象) 指定在搜索期间使用的索引扩展选项。

例如：

{
   "expand_wildcards": ["all"],
   "ignore_unavailable": true,
   "allow_no_indices": "false",
   "ignore_throttled": true
}

有关这些选项的更多信息，请参阅多目标语法。

max_empty_searches

(可选, 整数) 如果实时数据馈送从未看到任何数据（包括在任何初始训练期间），则它将在返回无文档的实时搜索次数达到此值后自动停止并关闭其关联的作业。换句话说，它将在实时操作的 frequency 乘以 max_empty_searches 次后停止。如果未设置，则没有结束时间且未看到数据的数据馈送将保持启动状态，直到明确停止。默认情况下，此设置未设置。

query

(可选, 对象) Elasticsearch查询领域特定语言（DSL）。此值对应于Elasticsearch搜索POST正文中的查询对象。Elasticsearch支持的所有选项都可以使用，因为此对象按原样传递给Elasticsearch。默认情况下，此属性具有以下值：{"match_all": {"boost": 1}}。

query_delay

(可选, 时间单位) 查询数据落后于实时的时间秒数。例如，如果10:04 a.m.的数据可能直到10:06 a.m.才可在Elasticsearch中搜索，请将此属性设置为120秒。默认值在 60s 和 120s 之间随机选择。这种随机性在同一节点上运行多个作业时提高了查询性能。有关更多信息，请参阅 Handling delayed data。

runtime_mappings

(可选, 对象) 指定数据馈送搜索的运行时字段。

例如：

{
  "day_of_week": {
    "type": "keyword",
    "script": {
      "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ENGLISH))"
    }
  }
}

script_fields

(可选, 对象) 指定评估自定义表达式并返回脚本字段到数据馈送的脚本。作业中的检测器配置对象可以包含使用这些脚本字段的功能。有关更多信息，请参阅 Transforming data with script fields 和 Script fields。

scroll_size

(可选, 无符号整数) 当数据馈送不使用聚合时，在Elasticsearch搜索中使用的 size 参数。默认值为 1000。最大值为 index.max_result_window 的值，默认值为10,000。

description

(可选, 字符串) 作业的描述。

groups

(可选, 字符串数组) 一组作业组。一个作业可以不属于任何组，也可以属于多个组。

model_plot_config

(可选, 对象) 此高级配置选项将模型信息与结果一起存储。它提供了对异常检测的更详细视图。

如果您启用模型绘图，它可能会显著增加系统的性能开销；对于包含许多实体的任务来说，这是不可行的。

模型图提供了一个简化和指示性的模型及其边界视图。它不显示复杂特征，如多元相关性或多模态数据。因此，可能会偶尔报告一些在模型图中无法看到的异常。

模型绘图配置可以在创建作业时或稍后更新时进行配置。如果遇到性能问题，必须禁用它。

Properties of model_plot_config

annotations_enabled: (布尔值) 如果为真，则启用计算和存储正在分析的每个实体的模型变化注释。默认为enabled。
enabled: (布尔值) 如果为真，则启用计算和存储正在分析的每个实体的模型边界。默认情况下，此功能未启用。
terms: [preview] 此功能处于技术预览阶段，可能会在未来的版本中进行更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 (字符串) 将数据收集限制为此逗号分隔的分区或字段值列表。如果未指定术语或为空字符串，则不应用过滤。例如，"CPU,NetworkIn,DiskWrites"。不支持通配符。使用单指标查看器时，只能查看指定的terms。

model_snapshot_retention_days

(可选，长整型) 高级配置选项，影响此作业的旧模型快照的自动删除。它指定快照保留的最大时间（以天为单位）。此时间段相对于此作业的最新快照的时间戳。默认值为 10，这意味着比最新快照早十天的快照将被删除。有关更多信息，请参阅模型快照。

renormalization_window_days

(可选, 长整型) 高级配置选项。在新数据出现时，调整分数所覆盖的时间段。默认值是30天或100个bucket_spans中较长的一个。

results_index_name

(可选，字符串) 一个影响机器学习结果索引名称的文本字符串。默认值为shared，它生成一个名为.ml-anomalies-shared的索引。

results_retention_days

(可选, 长整型) 高级配置选项。结果保留的时间段（以天为单位）。年龄是相对于最新桶结果的时间戳计算的。如果此属性具有非空值，则在每天的00:30（服务器时间），将删除比最新桶结果早指定天数的结果。默认值为null，这意味着所有结果都将保留。系统生成的注释也计入保留结果；它们在相同天数后被删除。用户添加的注释将永久保留。

示例

edit

创建一个异常检测作业和数据馈送：

PUT _ml/anomaly_detectors/test-job1?pretty
{
  "analysis_config": {
    "bucket_span": "15m",
    "detectors": [
      {
        "detector_description": "Sum of bytes",
        "function": "sum",
        "field_name": "bytes"
      }
    ]
  },
  "data_description": {
    "time_field": "timestamp",
    "time_format": "epoch_ms"
  },
  "analysis_limits": {
    "model_memory_limit": "11MB"
  },
  "model_plot_config": {
    "enabled": true,
    "annotations_enabled": true
  },
  "results_index_name": "test-job1",
  "datafeed_config":
  {
    "indices": [
    "kibana_sample_data_logs"
    ],
    "query": {
      "bool": {
        "must": [
          {
            "match_all": {}
          }
        ]
      }
    },
    "runtime_mappings": {
      "hour_of_day": {
        "type": "long",
        "script": {
          "source": "emit(doc['timestamp'].value.getHour());"
        }
      }
    },
    "datafeed_id": "datafeed-test-job1"
  }
}

API返回以下结果：

{
  "job_id" : "test-job1",
  "job_type" : "anomaly_detector",
  "job_version" : "8.4.0",
  "create_time" : 1656087283340,
  "datafeed_config" : {
    "datafeed_id" : "datafeed-test-job1",
    "job_id" : "test-job1",
    "authorization" : {
      "roles" : [
        "superuser"
      ]
    },
    "query_delay" : "61499ms",
    "chunking_config" : {
      "mode" : "auto"
    },
    "indices_options" : {
      "expand_wildcards" : [
        "open"
      ],
      "ignore_unavailable" : false,
      "allow_no_indices" : true,
      "ignore_throttled" : true
    },
    "query" : {
      "bool" : {
        "must" : [
          {
            "match_all" : { }
          }
        ]
      }
    },
    "indices" : [
      "kibana_sample_data_logs"
    ],
    "scroll_size" : 1000,
    "delayed_data_check_config" : {
      "enabled" : true
    },
    "runtime_mappings" : {
      "hour_of_day" : {
        "type" : "long",
        "script" : {
          "source" : "emit(doc['timestamp'].value.getHour());"
        }
      }
    }
  },
  "analysis_config" : {
    "bucket_span" : "15m",
    "detectors" : [
      {
        "detector_description" : "Sum of bytes",
        "function" : "sum",
        "field_name" : "bytes",
        "detector_index" : 0
      }
    ],
    "influencers" : [ ],
    "model_prune_window" : "30d"
  },
  "analysis_limits" : {
    "model_memory_limit" : "11mb",
    "categorization_examples_limit" : 4
  },
  "data_description" : {
    "time_field" : "timestamp",
    "time_format" : "epoch_ms"
  },
  "model_plot_config" : {
    "enabled" : true,
    "annotations_enabled" : true
  },
  "model_snapshot_retention_days" : 10,
  "daily_model_snapshot_retention_after_days" : 1,
  "results_index_name" : "custom-test-job1",
  "allow_lazy_open" : false
}

创建日历 API

edit

实例化一个日历。

请求

edit

PUT _ml/calendars/

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

有关更多信息，请参阅日历和预定事件。

路径参数

edit

<calendar_id>: (必需, 字符串) 一个唯一标识日历的字符串。

请求体

edit

description: (可选, 字符串) 日历的描述。

示例

edit

PUT _ml/calendars/planned-outages

当创建日历时，您会收到以下结果：

{
  "calendar_id": "planned-outages",
  "job_ids": []
}

创建数据流 API

edit

实例化一个数据馈送。

请求

edit

PUT _ml/datafeeds/

先决条件

edit

在创建数据馈送之前，您必须创建一个异常检测作业。
需要以下权限：
- cluster: manage_ml (the machine_learning_admin 内置角色授予此权限)
- 数据馈送中配置的源索引: read

描述

edit

数据馈送从Elasticsearch中检索数据，以供异常检测作业进行分析。每个异常检测作业只能关联一个数据馈送。

数据馈送包含一个以定义的时间间隔（frequency）运行的查询。如果您担心数据延迟，可以在每个间隔添加一个延迟（query_delay）。请参阅处理延迟数据。

您必须使用Kibana、此API或创建异常检测作业API来创建数据馈送。不要直接使用Elasticsearch索引API将数据馈送添加到.ml-config索引中。如果启用了Elasticsearch安全功能，请不要为用户提供.ml-config索引的write权限。
当启用了Elasticsearch安全功能时，您的数据馈送会记住创建它的用户在创建时拥有的角色，并使用这些相同的角色运行查询。如果您提供了二次授权头，则将使用这些凭据。

路径参数

edit

<feed_id>: (必需, 字符串) 一个唯一标识数据流的数字字符串。此标识符可以包含小写字母数字字符（a-z 和 0-9）、连字符和下划线。它必须以字母数字字符开头和结尾。

查询参数

edit

allow_no_indices

(可选，布尔值) 如果为 true，则通配符索引表达式解析为无具体索引时将被忽略。这包括 _all 字符串或未指定索引的情况。默认为 true。

expand_wildcards

(可选，字符串) 通配符模式可以匹配的索引类型。如果请求可以针对数据流，此参数确定通配符表达式是否匹配隐藏的数据流。支持逗号分隔的值，例如 open,hidden。有效值为：

all: 匹配任何数据流或索引，包括隐藏的数据流和索引。
open: 匹配开放的、非隐藏的索引。同时也匹配任何非隐藏的数据流。
closed: 匹配关闭的、非隐藏的索引。同时也匹配任何非隐藏的数据流。数据流不能被关闭。
hidden: 匹配隐藏的数据流和隐藏的索引。必须与 open、 closed 或两者结合使用。
none: 不接受通配符模式。

默认为 open。

ignore_throttled

(可选，布尔值) 如果为 true，冻结时会忽略具体的、扩展的或别名的索引。默认为 true。

[7.16.0] 在7.16.0中已弃用。

ignore_unavailable

(可选，布尔值) 如果为true，则忽略不可用的索引（缺失或关闭）。默认为false。

请求体

edit

aggregations

(可选, 对象) 如果设置，数据馈送执行聚合搜索。聚合的支持是有限的，并且应该仅用于低基数数据。更多信息，请参阅聚合数据以加快性能。

chunking_config

Properties of chunking_config

mode

(字符串) 有三种可用模式：

auto: 块大小是动态计算的。这是默认值，并且在数据馈送不使用聚合时推荐使用。
manual: 根据指定的time_span应用分块。当数据馈送使用聚合时使用此模式。
off: 不应用分块。

time_span

(时间单位) 每个搜索将查询的时间跨度。此设置仅在模式设置为manual时适用。例如：3h。

delayed_data_check_config

(可选, 对象) 指定数据馈送是否检查缺失数据以及窗口的大小。例如：{"enabled": true, "check_window": "1h"}。

此检查仅在实时数据馈送上运行。

Properties of delayed_data_check_config

check_window: (时间单位) 搜索延迟数据的窗口时间。此窗口时间以最新的最终化桶结束。它默认为null，这会在实时数据馈送运行时计算适当的check_window。特别是，默认的check_window跨度计算基于2h或8 * bucket_span的最大值。
enabled: (布尔值) 指定数据馈送是否定期检查延迟数据。默认为true。

frequency

(可选, 时间单位) 在数据馈送实时运行时，计划查询的时间间隔。默认值是短桶跨度的桶跨度，或者对于较长的桶跨度，是桶跨度的一个合理分数。例如： 150s。当 frequency 比桶跨度短时，最后一个（部分）桶的临时结果会被写入，然后最终被完整的桶结果覆盖。如果数据馈送使用聚合，此值必须能被日期直方图聚合的间隔整除。

indices

(必需，数组) 索引名称的数组。支持通配符。例如： ["it_ops_metrics", "server*"]。

如果任何索引位于远程集群中，则机器学习节点需要具有remote_cluster_client角色。

indices_options

(可选, 对象) 指定在搜索期间使用的索引扩展选项。

例如：

{
   "expand_wildcards": ["all"],
   "ignore_unavailable": true,
   "allow_no_indices": "false",
   "ignore_throttled": true
}

有关这些选项的更多信息，请参阅多目标语法。

job_id

(必需，字符串) 异常检测作业的标识符。

max_empty_searches

(可选，整数) 如果一个实时数据馈送从未见过任何数据（包括在任何初始训练期间），那么它将在返回无文档的实时搜索达到此数量后自动停止并关闭其关联的作业。换句话说，它将在实时操作中停止 frequency 乘以 max_empty_searches 次。如果未设置，则没有结束时间且未见任何数据的数据馈送将保持启动状态，直到明确停止。默认情况下，此设置未设置。

query

(可选, 对象) Elasticsearch 查询领域特定语言 (DSL)。此值对应于 Elasticsearch 搜索 POST 请求体中的 query 对象。所有 Elasticsearch 支持的选项都可以使用，因为这个对象会原封不动地传递给 Elasticsearch。默认情况下，此属性具有以下值：{"match_all": {"boost": 1}}。

query_delay

(可选，时间单位) 查询数据时，数据比实时时间落后的秒数。例如，如果10:04 a.m.的数据可能直到10:06 a.m.才能在Elasticsearch中搜索到，请将此属性设置为120秒。默认值在60s和120s之间随机选择。这种随机性在同一节点上运行多个作业时提高了查询性能。有关更多信息，请参阅处理延迟数据。

runtime_mappings

(可选, 对象) 指定数据馈送搜索的运行时字段。

例如：

{
  "day_of_week": {
    "type": "keyword",
    "script": {
      "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ENGLISH))"
    }
  }
}

script_fields

(可选，对象) 指定用于评估自定义表达式并返回脚本字段的脚本。作业中的检测器配置对象可以包含使用这些脚本字段的函数。有关更多信息，请参阅使用脚本字段转换数据和脚本字段。

scroll_size

(可选，无符号整数) 在 Elasticsearch 搜索中使用的 size 参数，当数据馈送不使用聚合时。默认值为 1000。最大值为 index.max_result_window 的值，默认情况下为 10,000。

示例

edit

为异常检测作业创建一个数据源（test-job）：

PUT _ml/datafeeds/datafeed-test-job?pretty
{
  "indices": [
    "kibana_sample_data_logs"
  ],
  "query": {
    "bool": {
      "must": [
        {
          "match_all": {}
        }
      ]
    }
  },
  "job_id": "test-job"
}

当数据馈送创建时，您会收到以下结果：

{
  "datafeed_id" : "datafeed-test-job",
  "job_id" : "test-job",
  "authorization" : {
    "roles" : [
      "superuser"
    ]
  },
  "query_delay" : "91820ms",
  "chunking_config" : {
    "mode" : "auto"
  },
  "indices_options" : {
    "expand_wildcards" : [
      "open"
    ],
    "ignore_unavailable" : false,
    "allow_no_indices" : true,
    "ignore_throttled" : true
  },
  "query" : {
    "bool" : {
      "must" : [
        {
          "match_all" : { }
        }
      ]
    }
  },
  "indices" : [
    "kibana_sample_data_logs"
  ],
  "scroll_size" : 1000,
  "delayed_data_check_config" : {
    "enabled" : true
  }
}

创建过滤器 API

edit

实例化一个过滤器。

请求

edit

PUT _ml/filters/

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

过滤器包含一个字符串列表。它可以被一个或多个作业使用。具体来说，过滤器在检测器配置对象的custom_rules属性中被引用。更多信息，请参阅自定义规则。

路径参数

edit

<filter_id>: (必需, 字符串) 一个唯一标识过滤器的字符串。

请求体

edit

description: (可选，字符串) 过滤器的描述。
items: (必需，字符串数组) 过滤器的项目。通配符 * 可以用于项目的开头或结尾。每个过滤器中最多允许 10000 个项目。

示例

edit

PUT _ml/filters/safe_domains
{
  "description": "A list of safe domains",
  "items": ["*.google.com", "wikipedia.org"]
}

当创建过滤器时，您会收到以下响应：

{
  "filter_id": "safe_domains",
  "description": "A list of safe domains",
  "items": ["*.google.com", "wikipedia.org"]
}

删除日历 API

edit

删除一个日历。

请求

edit

DELETE _ml/calendars/

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

此API从日历中移除所有预定的事件，然后删除日历。

路径参数

edit

<calendar_id>: (必需, 字符串) 一个唯一标识日历的字符串。

示例

edit

DELETE _ml/calendars/planned-outages

当删除日历时，您会收到以下结果：

{
  "acknowledged": true
}

删除数据流 API

edit

删除现有的数据馈送。

请求

edit

DELETE _ml/datafeeds/

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。
除非使用 force 参数，否则必须在删除之前停止数据馈送。

路径参数

edit

<feed_id>: (必需，字符串) 一个唯一标识数据流的数字字符串。此标识符可以包含小写字母数字字符（a-z 和 0-9）、连字符和下划线。它必须以字母数字字符开头和结尾。

查询参数

edit

force: (可选，布尔值) 用于强制删除一个已启动的数据馈送；此方法比停止并删除数据馈送更快。

示例

edit

DELETE _ml/datafeeds/datafeed-total-requests

当数据源被删除时，您会收到以下结果：

{
  "acknowledged": true
}

从日历 API 删除事件

edit

从日历中删除预定的事件。

请求

edit

DELETE _ml/calendars//events/

前提条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

此API从日历中删除单个事件。要删除所有预定的事件并删除日历，请参阅删除日历API。

路径参数

edit

<calendar_id>: (必需, 字符串) 一个唯一标识日历的字符串。
<event_id>: (必需，字符串) 计划事件的标识符。您可以通过使用获取计划事件 API 来获取此标识符。

示例

edit

DELETE _ml/calendars/planned-outages/events/LS8LJGEBMTCMA-qz49st

当事件被移除时，您会收到以下结果：

{
  "acknowledged": true
}

删除过滤器 API

edit

删除一个过滤器。

请求

edit

DELETE _ml/filters/

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

此API删除一个过滤器。如果一个异常检测作业引用了该过滤器，您无法删除该过滤器。您必须先更新或删除该作业，然后才能删除该过滤器。更多信息，请参阅自定义规则。

路径参数

edit

<filter_id>: (必需, 字符串) 一个唯一标识过滤器的字符串。

示例

edit

DELETE _ml/filters/safe_domains

当删除过滤器时，您会收到以下结果：

{
  "acknowledged": true
}

删除预测 API

edit

从机器学习作业中删除预测。

请求

edit

DELETE _ml/anomaly_detectors//_forecast

DELETE _ml/anomaly_detectors//_forecast/

DELETE _ml/anomaly_detectors//_forecast/_all

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

默认情况下，预测会保留14天。您可以通过forecast jobs API中的expires_in参数指定不同的保留期限。删除预测API使您能够在预测过期之前删除一个或多个预测。

当你删除一个作业时，与其相关的预测也会被删除。

有关更多信息，请参阅预测未来。

路径参数

edit

<forecast_id>: (可选，字符串) 一个逗号分隔的预测标识符列表。如果你不指定这个可选参数，或者你指定 _all 或 *，API 将删除作业中的所有预测。
<job_id>: (必需, 字符串) 异常检测作业的标识符。

查询参数

edit

allow_no_forecasts: (可选，布尔值) 指定在没有预测时是否发生错误。特别是，如果此参数设置为 false 并且没有与作业关联的预测，尝试删除所有预测将返回错误。默认值为 true。
timeout: (可选，时间单位) 指定等待删除操作完成的时间段。当此时间段过去后， API将失败并返回错误。默认值为30s。

示例

edit

DELETE _ml/anomaly_detectors/total-requests/_forecast/_all

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

{
  "acknowledged": true
}

删除异常检测作业 API

edit

删除现有的异常检测作业。

请求

edit

DELETE _ml/anomaly_detectors/

前提条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。
在删除作业之前，您必须关闭它（除非指定了 force 参数）。请参阅关闭作业。

描述

edit

所有作业配置、模型状态和结果均被删除。

删除异常检测作业必须仅通过此API完成。不要使用Elasticsearch删除文档API直接从.ml-*索引中删除作业。当启用了Elasticsearch安全功能时，确保没有向任何人授予对.ml-*索引的write权限。

目前无法使用通配符或逗号分隔列表删除多个作业。

如果你删除一个带有数据馈送的作业，请求首先尝试删除数据馈送。这种行为等同于使用与删除作业请求相同的timeout和force参数调用删除数据馈送API。

路径参数

edit

<job_id>: (必需, 字符串) 异常检测作业的标识符。

查询参数

edit

force: (可选，布尔值) 用于强制删除一个已打开的任务；此方法比先关闭再删除任务更快。
wait_for_completion: (可选，布尔值) 指定请求是否应立即返回或等待作业删除完成。默认为 true。
delete_user_annotations: (可选，布尔值) 指定在重置作业时，是否应删除用户添加的注释以及任何自动生成的注释。默认为 false。

示例

edit

DELETE _ml/anomaly_detectors/total-requests

当作业被删除时，您会收到以下结果：

{
  "acknowledged": true
}

在下一个示例中，我们异步删除 total-requests 作业：

DELETE _ml/anomaly_detectors/total-requests?wait_for_completion=false

当 wait_for_completion 设置为 false 时，响应包含作业删除任务的ID：

{
  "task": "oTUltX4IQMOUUVeiohTt8A:39"
}

从日历API中删除异常检测作业

edit

从日历中删除异常检测作业。

请求

edit

DELETE _ml/calendars//jobs/

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

路径参数

edit

<calendar_id>: (必需, 字符串) 一个唯一标识日历的字符串。
<job_id>: (必需，字符串) 异常检测作业的标识符。它可以是作业标识符、组名或逗号分隔的作业或组列表。

示例

edit

DELETE _ml/calendars/planned-outages/jobs/total-requests

当任务从日历中移除时，您会收到以下结果：

{
   "calendar_id": "planned-outages",
   "job_ids": []
}

删除模型快照 API

edit

删除现有的模型快照。

请求

edit

DELETE _ml/anomaly_detectors//model_snapshots/

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

您不能删除活动模型快照。要删除该快照，请先恢复到其他快照。要识别活动模型快照，请参考get jobs API结果中的model_snapshot_id。

路径参数

edit

<job_id>: (必需，字符串) 异常检测作业的标识符。
<snapshot_id>: (必需，字符串) 模型快照的标识符。

示例

edit

DELETE _ml/anomaly_detectors/farequote/model_snapshots/1491948163

当快照被删除时，您会收到以下结果：

{
  "acknowledged": true
}

删除过期数据 API

edit

删除过期且未使用的机器学习数据。

请求

edit

DELETE _ml/_delete_expired_data

DELETE _ml/_delete_expired_data/

前提条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

删除所有已超过其保留天数期限的作业结果、模型快照和预测数据。同时也会删除与任何作业无关的机器学习状态文档。

您可以通过使用作业标识符、组名称、逗号分隔的作业列表或通配符表达式，将请求限制为单个或一组异常检测作业。您可以通过使用_all，将*指定为，或者省略来删除所有异常检测作业的过期数据。

路径参数

edit

<job_id>: (可选, 字符串) 异常检测作业的标识符。它可以是作业标识符、组名或通配符表达式。

查询参数

edit

requests_per_second: (可选, 浮点数) 删除过程所需的每秒请求数。默认行为是不进行限制。
timeout: (可选，字符串) 底层删除过程可以运行多长时间，直到它们被取消。默认值是 8h（8小时）。

请求体

edit

您还可以在请求体中指定查询参数（requests_per_second 和 timeout）。

示例

edit

DELETE _ml/_delete_expired_data?timeout=1h

当过期数据被删除时，您会收到以下响应：

{
  "deleted": true
}

估计异常检测作业模型内存 API

edit

对异常检测作业模型的内存使用量进行估算。它是基于作业的分析配置详细信息以及它所引用的字段的基数估计。

请求

edit

POST _ml/anomaly_detectors/_estimate_model_memory

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

请求体

edit

analysis_config: (必需, 对象) 有关在此 API 的请求体中 analysis_config 组件可以指定的属性列表，请参阅 analysis_config。
max_bucket_cardinality: (必需^*, 对象) 在作业分析数据的时间段内，观察到的影响者字段在单个桶中的最高基数估计值。为了得到良好的答案，必须为所有影响者字段提供值。为未列为影响者的字段提供值不会影响估计。
^*如果没有影响者，则可以从请求中省略。
overall_cardinality: (必需^*, 对象) 在整个作业分析数据的时间段内，为字段观察到的基数估计值。为了得到一个好的答案，必须为任何检测器中的by_field_name、over_field_name和partition_field_name引用的字段提供值。为其他字段提供值不会影响估计。
^*如果没有任何检测器具有by_field_name、over_field_name或partition_field_name，则可以从请求中省略。

示例

edit

POST _ml/anomaly_detectors/_estimate_model_memory
{
  "analysis_config": {
    "bucket_span": "5m",
    "detectors": [
      {
        "function": "sum",
        "field_name": "bytes",
        "by_field_name": "status",
        "partition_field_name": "app"
      }
    ],
    "influencers": [ "source_ip", "dest_ip" ]
  },
  "overall_cardinality": {
    "status": 10,
    "app": 50
  },
  "max_bucket_cardinality": {
    "source_ip": 300,
    "dest_ip": 30
  }
}

估计返回以下结果：

{
  "model_memory_estimate": "21mb"
}

刷新作业 API

edit

强制将任何缓冲的数据通过作业进行处理。

请求

edit

POST _ml/anomaly_detectors//_flush

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

刷新作业 API 仅适用于使用 post data API 发送数据进行分析时。根据缓冲区的内容，它可能还会额外计算新的结果。

flush 和 close 操作类似，但如果您预计要发送更多数据进行分析，flush 更为高效。在执行 flush 操作时，作业保持打开状态，并可继续用于分析数据。close 操作还会修剪并将模型状态持久化到磁盘，并且必须在分析更多数据之前重新打开作业。

路径参数

edit

<job_id>: (必需，字符串) 异常检测作业的标识符。

查询参数

edit

advance_time: (字符串) 可选。指定前进到特定的时间值。生成结果并为指定时间间隔内的数据更新模型。
calc_interim: (布尔值) 可选。如果为 true，则计算最近一个桶或延迟周期内所有桶的中间结果。
end: (字符串) 可选。当与 calc_interim 和 start 一起使用时，指定要在其上计算中间结果的存储桶范围。
skip_time: (字符串) 可选。指定跳到特定的时间值。不会生成结果，并且模型不会更新指定时间间隔内的数据。
start: (字符串) 可选。当与 calc_interim 一起使用时，指定计算中间结果的桶的范围。

请求体

edit

您还可以在请求体中指定查询参数（例如 advance_time 和 calc_interim）。

示例

edit

POST _ml/anomaly_detectors/low_request_rate/_flush
{
  "calc_interim": true
}

当操作成功时，您会收到以下结果：

{
  "flushed": true,
  "last_finalized_bucket_end": 1455234900000
}

The last_finalized_bucket_end 提供了最后一个已处理桶的结束时间戳（自纪元以来的毫秒数）。

如果你想将作业刷新到特定的时间戳，可以使用 advance_time 或 skip_time 参数。例如，要前进到2018年1月1日格林尼治标准时间上午11点：

POST _ml/anomaly_detectors/total-requests/_flush
{
  "advance_time": "1514804400000"
}

当操作成功时，您会收到以下结果：

{
  "flushed": true,
  "last_finalized_bucket_end": 1514804400000
}

预测作业 API

edit

通过使用时间序列的历史行为来预测其未来行为。

请求

edit

POST _ml/anomaly_detectors//_forecast

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

您可以根据异常检测作业创建预测作业，以推断未来的行为。请参阅预测未来和预测限制以了解更多信息。

您可以通过使用删除预测 API来删除预测。

不支持对执行人口分析的任务进行预测；如果您尝试为配置中具有over_field_name属性的任务创建预测，将会发生错误。
创建预测时，任务必须处于打开状态。否则，将会发生错误。

路径参数

edit

<job_id>: (必需, 字符串) 异常检测作业的标识符。

查询参数

edit

duration: (可选，时间单位) 表示预测未来多长时间的周期。例如，30d 对应 30 天。默认值为 1 天。预测从处理的最后一条记录开始。
expires_in: (可选，时间单位) 预测结果保留的时间段。预测过期后，结果将被删除。默认值为14天。如果设置为0，预测将不会自动删除。
max_model_memory: (可选, 字节值) 预测可以使用的最大内存。如果预测需要使用的内存超过提供的数量，它将溢出到磁盘。默认值为20mb，最大值为500mb，最小值为1mb。如果设置为作业配置内存限制的40%或更多，它将自动减少到低于该数量。

请求体

edit

您还可以在请求体中指定查询参数（例如 duration 和 expires_in）。

示例

edit

POST _ml/anomaly_detectors/low_request_rate/_forecast
{
  "duration": "10d"
}

当预测创建时，您会收到以下结果：

{
  "acknowledged": true,
  "forecast_id": "wkCWa2IB2lF8nSE_TzZo"
}

您随后可以在 Kibana 的 单一指标查看器 中查看预测。

获取存储桶 API

edit

检索一个或多个桶的异常检测作业结果。

请求

edit

GET _ml/anomaly_detectors//results/buckets

GET _ml/anomaly_detectors//results/buckets/

先决条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

描述

edit

get buckets API 按桶分组，以时间顺序展示记录。

路径参数

edit

<job_id>: (必需, 字符串) 异常检测作业的标识符。
<timestamp>: (可选，字符串) 单个桶结果的时间戳。如果您不指定此参数，API将返回有关所有桶的信息。

查询参数

edit

anomaly_score: (可选，双精度) 返回异常分数大于或等于此值的桶。默认为 0.0。
desc: (可选，布尔值) 如果为 true，则桶按降序排序。默认为 false。
end: (可选，字符串) 返回时间戳早于该时间的水桶。默认为 -1，这意味着它未设置，结果不受特定时间戳的限制。
exclude_interim: (可选, 布尔值) 如果为true，输出将排除中间结果。默认为false，这意味着中间结果会被包含。
expand: (可选，布尔值) 如果为 true，输出将包含异常记录。默认为 false。
from: (可选，整数) 跳过指定数量的桶。默认为 0。
size: (可选，整数) 指定要获取的最大桶数。默认为 100。
sort: (可选，字符串) 指定请求的桶的排序字段。默认情况下，桶按 timestamp 字段排序。
start: (可选，字符串) 返回时间戳在此时间之后的数据桶。默认为 -1，表示未设置，结果不受特定时间戳的限制。

请求体

edit

您也可以在请求体中指定查询参数；例外的是from和size，请使用page代替：

page

属性 page

from: (可选, 整数) 跳过指定数量的桶。默认为 0。
size: (可选, 整数) 指定要获取的最大桶数。默认为 100。

响应体

edit

API返回一个存储桶对象数组，这些对象具有以下属性：

anomaly_score

(数字) 任何桶影响者的最大异常分数，介于0-100之间。这是作业的一个整体、速率限制的分数。桶中的所有异常记录都对此分数有贡献。随着新数据的分析，此值可能会更新。

bucket_influencers

(数组) 一个包含桶影响者对象的数组。

Properties of bucket_influencers

anomaly_score: (数字) 一个在0-100之间的标准化分数，为每个桶影响者计算。这个分数可能会随着新数据的分析而更新。
bucket_span: (数字) 桶的长度，以秒为单位。这个值与作业中指定的bucket_span相匹配。
influencer_field_name: (字符串) 影响者的字段名称。

initial_anomaly_score: (数字) 每个桶影响者的分数在0-100之间。这个分数是在处理桶时计算的初始值。
is_interim: (布尔值) 如果true，这是一个临时结果。换句话说，结果是基于部分输入数据计算的。
job_id: (字符串) 异常检测作业的标识符。
probability: (数字) 桶具有这种行为的概率，范围在0到1之间。这个值可以保持超过300位小数的高精度，因此提供了anomaly_score作为人类可读和友好的解释。
raw_anomaly_score: (数字) 内部使用。
result_type: (字符串) 内部使用。这个值总是设置为bucket_influencer。
timestamp: (日期) 计算这些结果的桶的开始时间。

bucket_span

(数字) 存储桶的长度，以秒为单位。该值与作业中指定的bucket_span相匹配。

event_count

(数字) 在此桶中处理的数据记录数量。

initial_anomaly_score

(数字) 任何桶影响者的最大 anomaly_score。这是在处理桶时计算的初始值。

is_interim

(布尔值) 如果true，这是一个中间结果。换句话说，结果是基于部分输入数据计算的。

job_id

(字符串) 异常检测作业的标识符。

processing_time_ms

(数字) 分析存储桶内容并计算结果所花费的时间，以毫秒为单位。

result_type

(字符串) 内部使用。此值始终设置为 bucket。

timestamp

(日期) 存储桶的开始时间。此时间戳唯一标识存储桶。

发生在桶时间戳上的事件会被包含在该桶的结果中。

示例

edit

GET _ml/anomaly_detectors/low_request_rate/results/buckets
{
  "anomaly_score": 80,
  "start": "1454530200001"
}

在这个例子中，API返回了一个符合指定分数和时间约束的单一结果：

{
  "count" : 1,
  "buckets" : [
    {
      "job_id" : "low_request_rate",
      "timestamp" : 1578398400000,
      "anomaly_score" : 91.58505459594764,
      "bucket_span" : 3600,
      "initial_anomaly_score" : 91.58505459594764,
      "event_count" : 0,
      "is_interim" : false,
      "bucket_influencers" : [
        {
          "job_id" : "low_request_rate",
          "result_type" : "bucket_influencer",
          "influencer_field_name" : "bucket_time",
          "initial_anomaly_score" : 91.58505459594764,
          "anomaly_score" : 91.58505459594764,
          "raw_anomaly_score" : 0.5758246639716365,
          "probability" : 1.7340849573442696E-4,
          "timestamp" : 1578398400000,
          "bucket_span" : 3600,
          "is_interim" : false
        }
      ],
      "processing_time_ms" : 0,
      "result_type" : "bucket"
    }
  ]
}

获取日历 API

edit

检索日历的配置信息。

请求

edit

GET _ml/calendars/

GET _ml/calendars/_all

先决条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

描述

edit

有关更多信息，请参阅日历和预定事件。

路径参数

edit

<calendar_id>

(必需, 字符串) 一个唯一标识日历的字符串。

您可以通过使用逗号分隔的ID列表或通配符表达式，在单个API请求中获取多个日历的信息。您可以通过使用_all，将*指定为日历标识符，或者省略标识符来获取所有日历的信息。

查询参数

edit

from: (可选，整数) 跳过指定数量的日历。此参数仅在你省略时才受支持。默认为 0。
size: (可选，整数) 指定要获取的最大日历数量。此参数仅在你省略时才受支持。默认值为 100。

请求体

edit

page

page的属性

from: (可选, 整数) 跳过指定数量的日历。此对象仅在你省略时受支持。默认为0。
size: (可选, 整数) 指定要获取的最大日历数量。此对象仅在你省略时受支持。默认为100。

响应体

edit

API返回一个日历资源数组，这些资源具有以下属性：

calendar_id: (字符串) 一个唯一标识日历的字符串。
job_ids: (数组) 一个异常检测作业标识符的数组。例如： ["total-requests"]。

示例

edit

GET _ml/calendars/planned-outages

API返回以下结果：

{
  "count": 1,
  "calendars": [
    {
      "calendar_id": "planned-outages",
      "job_ids": [
        "total-requests"
      ]
    }
  ]
}

获取分类 API

edit

检索一个或多个类别的异常检测作业结果。

请求

edit

GET _ml/anomaly_detectors//results/categories

GET _ml/anomaly_detectors//results/categories/

先决条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

描述

edit

当在作业配置中指定categorization_field_name时，可以查看生成的类别的定义。类别定义描述了匹配的常用术语，并包含匹配值的示例。

异常结果来自分类分析，可作为桶、影响者和记录结果使用。例如，结果可能表明在16:45时，日志消息类别11的计数异常。然后，您可以检查该类别的描述和示例。有关更多信息，请参阅分类日志消息。

路径参数

edit

<job_id>: (必需, 字符串) 异常检测作业的标识符。
<category_id>: (可选，长整型) 类别的标识符，在作业中是唯一的。如果你既没有指定类别ID，也没有指定partition_field_value，API将返回所有类别的信息。如果你只指定了partition_field_value，它将返回指定分区的所有类别的信息。

查询参数

edit

from: (可选，整数) 跳过指定数量的类别。默认为 0。
partition_field_value: (可选, 字符串) 仅返回指定分区的类别。
size: (可选, 整数) 指定要获取的最大类别数量。默认为 100。

请求体

edit

您还可以在请求体中指定partition_field_value查询参数。

page

属性 page

from: (可选, 整数) 跳过指定数量的分类。默认为 0。
size: (可选, 整数) 指定要获取的最大分类数量。默认为 100。

响应体

edit

API返回一个类别对象数组，这些对象具有以下属性：

category_id: (无符号整数) 类别的唯一标识符。category_id 在作业级别是唯一的，即使启用了按分区分类。
examples: (数组) 匹配该类别的实际值示例列表。
grok_pattern: [预览] 此功能处于技术预览阶段，可能会在未来的版本中进行更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 (字符串) 一个 Grok 模式，可用于 Logstash 或摄取管道中，以从匹配类别的消息中提取字段。此字段是实验性的，可能会在未来的版本中进行更改或移除。找到的 Grok 模式并非最佳，但通常是手动调整的良好起点。
job_id: (字符串) 异常检测作业的标识符。
max_matching_length: (无符号整数) 匹配类别的字段的最大长度。该值增加了10%，以启用对未分析的类似字段的匹配。

partition_field_name: (字符串) 如果启用了按分区分类，此属性标识用于分割分类的字段。当按分区分类被禁用时，此属性不存在。
partition_field_value: (字符串) 如果启用了按分区分类，此属性标识该类别的 partition_field_name 的值。当按分区分类被禁用时，此属性不存在。
regex: (字符串) 一个用于搜索与类别匹配的值的正则表达式。
terms: (字符串) 一个以空格分隔的常用标记列表，这些标记在类别值中匹配。
num_matches: (长整型) 该类别匹配的消息数量。只有在作业 _flush 或 _close 之后，才能保证这是最新的准确计数。
preferred_to_categories: (列表) 当前类别所包含的 category_id 条目列表。分类器处理的任何新消息都将与此类别匹配，而不是与此列表中的任何类别匹配。只有在作业 _flush 或 _close 之后，才能保证这是最新准确的类别列表。

示例

edit

GET _ml/anomaly_detectors/esxi_log/results/categories
{
  "page":{
    "size": 1
  }
}

{
  "count": 11,
  "categories": [
    {
      "job_id" : "esxi_log",
      "category_id" : 1,
      "terms" : "Vpxa verbose vpxavpxaInvtVm opID VpxaInvtVmChangeListener Guest DiskInfo Changed",
      "regex" : ".*?Vpxa.+?verbose.+?vpxavpxaInvtVm.+?opID.+?VpxaInvtVmChangeListener.+?Guest.+?DiskInfo.+?Changed.*",
      "max_matching_length": 154,
      "examples" : [
        "Oct 19 17:04:44 esxi1.acme.com Vpxa: [3CB3FB90 verbose 'vpxavpxaInvtVm' opID=WFU-33d82c31] [VpxaInvtVmChangeListener] Guest DiskInfo Changed",
        "Oct 19 17:04:45 esxi2.acme.com Vpxa: [3CA66B90 verbose 'vpxavpxaInvtVm' opID=WFU-33927856] [VpxaInvtVmChangeListener] Guest DiskInfo Changed",
        "Oct 19 17:04:51 esxi1.acme.com Vpxa: [FFDBAB90 verbose 'vpxavpxaInvtVm' opID=WFU-25e0d447] [VpxaInvtVmChangeListener] Guest DiskInfo Changed",
        "Oct 19 17:04:58 esxi2.acme.com Vpxa: [FFDDBB90 verbose 'vpxavpxaInvtVm' opID=WFU-bbff0134] [VpxaInvtVmChangeListener] Guest DiskInfo Changed"
      ],
      "grok_pattern" : ".*?%{SYSLOGTIMESTAMP:timestamp}.+?Vpxa.+?%{BASE16NUM:field}.+?verbose.+?vpxavpxaInvtVm.+?opID.+?VpxaInvtVmChangeListener.+?Guest.+?DiskInfo.+?Changed.*"
    }
  ]
}

获取数据流 API

edit

检索数据流的配置信息。

请求

edit

GET _ml/datafeeds/

GET _ml/datafeeds/,

GET _ml/datafeeds/

GET _ml/datafeeds/_all

先决条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

描述

edit

此API最多返回10,000个数据源。

路径参数

edit

<feed_id>

(可选, 字符串) 数据流的标识符。它可以是数据流标识符或通配符表达式。

您可以通过使用逗号分隔的数据馈送列表或通配符表达式，在单个API请求中获取多个数据馈送的信息。您可以通过使用_all，将*指定为数据馈送标识符，或者省略标识符来获取所有数据馈送的信息。

查询参数

edit

allow_no_match

(可选, 布尔值) 指定在请求时执行的操作：

包含通配符表达式且没有匹配的数据馈送。
包含 _all 字符串或没有标识符且没有匹配项。
包含通配符表达式且只有部分匹配。

默认值为 true，在没有匹配项时返回一个空的 datafeeds 数组，在有部分匹配项时返回部分结果。如果此参数为 false，则在没有任何匹配项或只有部分匹配项时，请求将返回 404 状态码。

exclude_generated

(可选，布尔值) 指示是否应在检索时从配置中移除某些字段。这允许配置以可接受的格式被检索，然后添加到另一个集群中。默认值为 false。

响应体

edit

API返回一个数据馈送资源的数组。有关完整的属性列表，请参阅创建数据馈送API。

响应代码

edit

404 (Missing resources): 如果 allow_no_match 是 false，此代码表示没有与请求匹配的资源，或者只有部分匹配的请求。

示例

edit

GET _ml/datafeeds/datafeed-high_sum_total_sales

API返回以下结果：

{
  "count" : 1,
  "datafeeds" : [
    {
      "datafeed_id" : "datafeed-high_sum_total_sales",
      "job_id" : "high_sum_total_sales",
      "authorization" : {
        "roles" : [
          "superuser"
        ]
      },
      "query_delay" : "93169ms",
      "chunking_config" : {
        "mode" : "auto"
      },
      "indices_options" : {
        "expand_wildcards" : [
          "open"
        ],
        "ignore_unavailable" : false,
        "allow_no_indices" : true,
        "ignore_throttled" : true
      },
      "query" : {
        "bool" : {
          "filter" : [
            {
              "term" : {
                "event.dataset" : "sample_ecommerce"
              }
            }
          ]
        }
      },
      "indices" : [
        "kibana_sample_data_ecommerce"
      ],
      "scroll_size" : 1000,
      "delayed_data_check_config" : {
        "enabled" : true
      }
    }
  ]
}

获取数据馈送统计信息 API

edit

检索数据馈送的使用信息。

请求

edit

GET _ml/datafeeds//_stats

GET _ml/datafeeds/,/_stats

GET _ml/datafeeds/_stats

GET _ml/datafeeds/_all/_stats

先决条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

描述

edit

如果数据馈送停止，您收到的唯一信息是datafeed_id和state。

此API最多返回10,000个数据源。

路径参数

edit

<feed_id>

(可选, 字符串) 数据流的标识符。它可以是数据流标识符或通配符表达式。

您可以通过使用逗号分隔的数据馈送列表或通配符表达式，在单个API请求中获取多个数据馈送的统计信息。您可以通过使用_all，将*指定为数据馈送标识符，或者省略标识符来获取所有数据馈送的统计信息。

查询参数

edit

allow_no_match

(可选, 布尔值) 指定在请求时执行的操作：

包含通配符表达式且没有匹配的数据馈送。
包含 _all 字符串或没有标识符且没有匹配项。
包含通配符表达式且只有部分匹配。

响应体

edit

API返回一个数据馈送计数对象数组。所有这些属性都是信息性的；您无法更新它们的值。

assignment_explanation

(字符串) 仅对于已启动的数据馈送，包含与节点选择相关的消息。

datafeed_id

(字符串) 一个唯一标识数据源的数字字符串。此标识符可以包含小写字母数字字符（a-z 和 0-9）、连字符和下划线。它必须以字母数字字符开头和结尾。

node

(对象) 仅对于已启动的数据馈送，此信息与启动数据馈送的节点相关。

详细信息

attributes: (对象) 列出节点属性，例如 ml.machine_memory 或 ml.max_open_jobs 设置。
ephemeral_id: (字符串) 节点的临时ID。
id: (字符串) 节点的唯一标识符。
name: (字符串) 节点名称。例如，0-o0tOo。
transport_address: (字符串) 接受传输HTTP连接的主机和端口。

running_state

(对象) 包含此数据馈送的运行状态的对象。仅当数据馈送启动时才会提供。

详情

real_time_configured

(布尔值) 指示数据馈送是否为“实时”；即数据馈送没有配置 end 时间。

real_time_running

(布尔值) 指示数据馈送是否已完成在可用历史数据上的运行。对于没有配置 end 时间的数据馈送，这意味着数据馈送现在正在“实时”数据上运行。

search_interval

（可选，对象）提供数据馈送已搜索的最新时间间隔。

详情

start_ms: 开始时间，以毫秒为单位的纪元时间。
end_ms: 结束时间，以毫秒为单位的纪元时间。

state

(字符串) 数据馈送的状态，可以是以下值之一：

starting: 数据馈送已被请求启动但尚未开始。
started: 数据馈送正在主动接收数据。
stopping: 数据馈送已被请求优雅停止，并正在完成其最终操作。
stopped: 数据馈送已停止，除非重新启动，否则不会接收数据。

timing_stats

(对象) 提供关于此数据馈送时间方面的统计信息的对象。

详情

average_search_time_per_bucket_ms: (double) 每个桶的平均搜索时间，以毫秒为单位。
bucket_count: (long) 处理的桶的数量。
exponential_average_search_time_per_hour_ms: (double) 每小时的指数平均搜索时间，以毫秒为单位。
job_id: 异常检测作业的标识符。
search_count: 数据馈送运行的搜索次数。
total_search_time_ms: 数据馈送花费的总搜索时间，以毫秒为单位。

响应代码

edit

404 (Missing resources): 如果 allow_no_match 是 false，此代码表示没有与请求匹配的资源，或者只有部分匹配的请求。

示例

edit

GET _ml/datafeeds/datafeed-high_sum_total_sales/_stats

API返回以下结果：

{
  "count" : 1,
  "datafeeds" : [
    {
      "datafeed_id" : "datafeed-high_sum_total_sales",
      "state" : "started",
      "node" : {
        "id" : "7bmMXyWCRs-TuPfGJJ_yMw",
        "name" : "node-0",
        "ephemeral_id" : "hoXMLZB0RWKfR9UPPUCxXX",
        "transport_address" : "127.0.0.1:9300",
        "attributes" : {
          "ml.machine_memory" : "17179869184",
          "ml.max_open_jobs" : "512"
        }
      },
      "assignment_explanation" : "",
      "timing_stats" : {
        "job_id" : "high_sum_total_sales",
        "search_count" : 7,
        "bucket_count" : 743,
        "total_search_time_ms" : 134.0,
        "average_search_time_per_bucket_ms" : 0.180349932705249,
        "exponential_average_search_time_per_hour_ms" : 11.514712961628677
      }
    }
  ]
}

获取影响者 API

edit

检索一个或多个影响者的异常检测作业结果。

请求

edit

GET _ml/anomaly_detectors//results/influencers

先决条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

描述

edit

影响者是那些对异常情况有贡献或应负责的实体。只有在作业配置中指定了influencer_field_name时，才会提供影响者结果。

路径参数

edit

<job_id>: (必需, 字符串) 异常检测作业的标识符。

查询参数

edit

desc: (可选，布尔值) 如果为true，结果按降序排序。
end: (可选，字符串) 返回时间戳早于此时间的 influencers。默认为 -1，这意味着它未设置，结果不受特定时间戳的限制。
exclude_interim: (可选, 布尔值) 如果为true，输出将排除中间结果。默认为false，这意味着中间结果会被包含。
from: (可选，整数) 跳过指定数量的影响者。默认为 0。
influencer_score: (可选，双精度) 返回异常分数大于或等于此值的影响者。默认为 0.0。
size: (可选, 整数) 指定要获取的最大影响者数量。默认为 100。
sort: (可选，字符串) 指定请求的影响者的排序字段。默认情况下，影响者按 influencer_score 值排序。
start: (可选，字符串) 返回时间戳在此时间之后的 influencers。默认为 -1，这意味着未设置，结果不受特定时间戳的限制。

请求体

edit

您也可以在请求体中指定查询参数；例外的是from和size，请使用page代替：

page

page的属性

from: (可选, 整数) 跳过指定数量的影响者。默认为0。
size: (可选, 整数) 指定要获取的最大影响者数量。默认为100。

响应体

edit

API返回一个影响者对象数组，这些对象具有以下属性：

bucket_span: (数字) 存储桶的长度，以秒为单位。该值与作业中指定的bucket_span相匹配。
influencer_score: (数字) 一个介于0-100之间的标准化分数，该分数基于检测器中影响者的概率聚合。与 initial_influencer_score不同，随着新数据的分析，此值将通过重新标准化过程进行更新。
influencer_field_name: (字符串) 影响者的字段名称。
influencer_field_value: (字符串) 对异常产生影响、贡献或应负责的实体。
initial_influencer_score: (数字) 一个介于0-100之间的标准化分数，基于检测器中聚合的影响者概率。这是在处理桶时计算的初始值。
is_interim: (布尔值) 如果true，这是一个中间结果。换句话说，结果是基于部分输入数据计算的。
job_id: (字符串) 异常检测作业的标识符。
probability: (数字) 影响者具有此行为的概率，范围在0到1之间。例如，0.0000109783。此值可以保持超过300位小数的精度，因此提供了influencer_score作为对此值的人类可读和友好的解释。
result_type: (字符串) 内部使用。此值始终设置为 influencer。
timestamp: (日期) 计算这些结果的存储桶的开始时间。

根据分析的字段，会添加额外的影响者属性。例如，如果它正在分析 user_name 作为影响者，那么会在结果文档中添加一个 user_name 字段。这些信息使您能够更轻松地过滤异常结果。

示例

edit

GET _ml/anomaly_detectors/high_sum_total_sales/results/influencers
{
  "sort": "influencer_score",
  "desc": true
}

在这个例子中，API返回以下信息，根据影响力评分按降序排序：

{
  "count": 189,
  "influencers": [
    {
      "job_id": "high_sum_total_sales",
      "result_type": "influencer",
      "influencer_field_name": "customer_full_name.keyword",
      "influencer_field_value": "Wagdi Shaw",
      "customer_full_name.keyword" : "Wagdi Shaw",
      "influencer_score": 99.02493,
      "initial_influencer_score" : 94.67233079580171,
      "probability" : 1.4784807245686567E-10,
      "bucket_span" : 3600,
      "is_interim" : false,
      "timestamp" : 1574661600000
    },
  ...
  ]
}

获取异常检测作业 API

edit

检索异常检测作业的配置信息。

请求

edit

GET _ml/anomaly_detectors/

GET _ml/anomaly_detectors/,

GET _ml/anomaly_detectors/

GET _ml/anomaly_detectors/_all

先决条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

描述

edit

此API最多返回10,000个职位。

路径参数

edit

<job_id>: (可选，字符串) 异常检测作业的标识符。它可以是作业标识符、组名或通配符表达式。您可以通过使用组名、逗号分隔的作业列表或通配符表达式，在单个API请求中获取多个异常检测作业的信息。您可以通过使用_all，将作业标识符指定为*，或者省略标识符来获取所有异常检测作业的信息。

查询参数

edit

allow_no_match

(可选, 布尔值) 指定在请求时执行的操作：

包含通配符表达式且没有匹配的作业。
包含 _all 字符串或没有标识符且没有匹配项。
包含通配符表达式且只有部分匹配。

exclude_generated

(可选，布尔值) 指示是否应在检索时从配置中移除某些字段。这允许配置以可接受的格式被检索，然后添加到另一个集群中。默认值为 false。

响应体

edit

API返回一个异常检测作业资源的数组。有关完整的属性列表，请参阅创建异常检测作业API。

blocked

(对象) 当存在时，它解释了在作业上执行的任务会阻止其打开。

Properties of blocked

reason: (字符串) 作业被阻止的原因。值可能是 delete、reset、revert。每个值表示正在执行相应的操作。
task_id: (字符串) 阻止操作的任务ID。您可以使用任务管理 API 来监控进度。

create_time

(字符串) 作业创建的时间。例如，1491007356077。此属性是信息性的；您无法更改其值。

datafeed_config

(对象) 为当前异常检测作业配置的数据馈送。

Properties of datafeed_config

authorization

(可选, 对象) 数据馈送用于运行其查询的安全权限。如果在最近一次更新数据馈送时禁用了Elastic Stack安全功能，则省略此属性。

Properties of authorization

api_key

(对象) 如果最近的更新数据源使用了API密钥，其名称和标识符将列在响应中。

Properties of api_key

id: (字符串) API密钥的标识符。
name: (字符串) API密钥的名称。

roles

(字符串数组) 如果最近一次更新数据馈送时使用了用户ID，则其更新时的角色将列在响应中。

service_account

(字符串) 如果最近一次更新数据馈送时使用了服务账户，则账户名称将列在响应中。

datafeed_id

(可选, 字符串) 一个唯一标识数据馈送的数字字符串。此标识符可以包含小写字母数字字符（a-z和0-9）、连字符和下划线。它必须以字母数字字符开头和结尾。

aggregations

(可选, 对象) 如果设置，数据馈送将执行聚合搜索。聚合的支持是有限的，应仅与低基数数据一起使用。有关更多信息，请参阅聚合数据以加快性能。

chunking_config

Properties of chunking_config

mode

(字符串) 有三种可用模式：

auto: 块大小是动态计算的。这是默认值，当数据馈送不使用聚合时推荐使用。
manual: 根据指定的time_span应用分块。当数据馈送使用聚合时使用此模式。
off: 不应用分块。

time_span

(时间单位) 每个搜索将查询的时间跨度。此设置仅在模式设置为manual时适用。例如：3h。

delayed_data_check_config

(可选, 对象) 指定数据馈送是否检查缺失数据以及窗口的大小。例如：{"enabled": true, "check_window": "1h"}。

此检查仅在实时数据馈送上运行。

Properties of delayed_data_check_config

check_window: (时间单位) 搜索延迟数据的时间窗口。此窗口以最新的最终桶结束。它默认为null，这会导致在实时数据馈送运行时计算适当的check_window。特别是，默认的check_window跨度计算基于2h或8 * bucket_span的最大值。
enabled: (布尔值) 指定数据馈送是否定期检查延迟数据。默认为true。

frequency

(可选, 时间单位) 数据馈送在实时运行时计划查询的时间间隔。默认值是短桶跨度的桶跨度，或长桶跨度的桶跨度的一个合理分数。例如：150s。当frequency短于桶跨度时，最后（部分）桶的临时结果会被写入，然后最终被完整桶的结果覆盖。如果数据馈送使用聚合，此值必须可被日期直方图聚合的间隔整除。

indices

(必需，数组) 索引名称的数组。支持通配符。例如： ["it_ops_metrics", "server*"]。

如果任何索引位于远程集群中，则机器学习节点需要具有remote_cluster_client角色。

indices_options

(可选, 对象) 指定在搜索期间使用的索引扩展选项。

例如：

{
   "expand_wildcards": ["all"],
   "ignore_unavailable": true,
   "allow_no_indices": "false",
   "ignore_throttled": true
}

有关这些选项的更多信息，请参阅多目标语法。

job_id

(必需, 字符串) 异常检测作业的标识符。

max_empty_searches

(可选, 整数) 如果实时数据馈送从未看到任何数据（包括在任何初始训练期间），则它将在返回无文档的实时搜索次数达到此值后自动停止并关闭其关联的作业。换句话说，它将在frequency乘以max_empty_searches的实时操作后停止。如果未设置，则没有结束时间且未看到数据的数据馈送将保持启动状态，直到明确停止。默认情况下，此设置未设置。

query

(可选, 对象) Elasticsearch查询领域特定语言（DSL）。此值对应于Elasticsearch搜索POST正文中的查询对象。Elasticsearch支持的所有选项都可以使用，因为此对象被原样传递给Elasticsearch。默认情况下，此属性具有以下值：{"match_all": {"boost": 1}}。

query_delay

(可选, 时间单位) 查询数据落后于实时的时间秒数。例如，如果10:04的数据可能在10:06之前无法在Elasticsearch中搜索到，请将此属性设置为120秒。默认值在60s和120s之间随机选择。这种随机性在同一节点上运行多个作业时提高了查询性能。有关更多信息，请参阅处理延迟数据。

runtime_mappings

(可选, 对象) 指定数据馈送搜索的运行时字段。

例如：

{
  "day_of_week": {
    "type": "keyword",
    "script": {
      "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ENGLISH))"
    }
  }
}

script_fields

(可选, 对象) 指定评估自定义表达式并返回脚本字段到数据馈送的脚本。作业中的检测器配置对象可以包含使用这些脚本字段的功能。有关更多信息，请参阅使用脚本字段转换数据和脚本字段。

scroll_size

(可选, 无符号整数) 当数据馈送不使用聚合时，在Elasticsearch搜索中使用的size参数。默认值为1000。最大值为index.max_result_window的值，默认值为10,000。

finished_time

(字符串) 如果作业关闭或失败，这是作业完成的时间，否则它是null。此属性是信息性的；您无法更改其值。

job_type

(字符串) 保留供将来使用，当前设置为 anomaly_detector。

job_version

(字符串) 创建作业时的机器学习配置版本号。

从 Elasticsearch 8.10.0 开始，使用一个新的版本号来跟踪机器学习插件中的配置和状态变化。这个新的版本号与产品版本解耦，并将独立递增。job_version 值表示新的版本号。

model_snapshot_id: (字符串) 一个唯一标识模型快照的数值字符串。例如，1575402236000。

响应代码

edit

404 (Missing resources): 如果 allow_no_match 是 false，此代码表示没有与请求匹配的资源，或者只有部分匹配的请求。

示例

edit

GET _ml/anomaly_detectors/high_sum_total_sales

API返回以下结果：

{
  "count": 1,
  "jobs": [
    {
      "job_id" : "high_sum_total_sales",
      "job_type" : "anomaly_detector",
      "job_version" : "8.4.0",
      "create_time" : 1655852735889,
      "finished_time" : 1655852745980,
      "model_snapshot_id" : "1575402237",
      "custom_settings" : {
        "created_by" : "ml-module-sample",
        ...
      },
      "datafeed_config" : {
        "datafeed_id" : "datafeed-high_sum_total_sales",
        "job_id" : "high_sum_total_sales",
        "authorization" : {
          "roles" : [
            "superuser"
          ]
        },
        "query_delay" : "93169ms",
        "chunking_config" : {
          "mode" : "auto"
        },
        "indices_options" : {
          "expand_wildcards" : [
            "open"
          ],
          "ignore_unavailable" : false,
          "allow_no_indices" : true,
          "ignore_throttled" : true
        },
        "query" : {
          "bool" : {
            "filter" : [
              {
                "term" : {
                  "event.dataset" : "sample_ecommerce"
                }
              }
            ]
          }
        },
        "indices" : [
          "kibana_sample_data_ecommerce"
        ],
        "scroll_size" : 1000,
        "delayed_data_check_config" : {
          "enabled" : true
        }
      },
      "groups" : [
        "kibana_sample_data",
        "kibana_sample_ecommerce"
      ],
      "description" : "Find customers spending an unusually high amount in an hour",
      "analysis_config" : {
        "bucket_span" : "1h",
        "detectors" : [
          {
            "detector_description" : "High total sales",
            "function" : "high_sum",
            "field_name" : "taxful_total_price",
            "over_field_name" : "customer_full_name.keyword",
            "detector_index" : 0
          }
        ],
        "influencers" : [
          "customer_full_name.keyword",
          "category.keyword"
        ],
        "model_prune_window": "30d"
      },
      "analysis_limits" : {
        "model_memory_limit" : "13mb",
        "categorization_examples_limit" : 4
      },
      "data_description" : {
        "time_field" : "order_date",
        "time_format" : "epoch_ms"
      },
      "model_plot_config" : {
        "enabled" : true,
        "annotations_enabled" : true
      },
      "model_snapshot_retention_days" : 10,
      "daily_model_snapshot_retention_after_days" : 1,
      "results_index_name" : "shared",
      "allow_lazy_open" : false
    }
  ]
}

获取异常检测作业统计信息 API

edit

检索异常检测作业的使用信息。

请求

edit

GET _ml/anomaly_detectors//_stats

GET _ml/anomaly_detectors/,/_stats

GET _ml/anomaly_detectors/_stats

GET _ml/anomaly_detectors/_all/_stats

先决条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

描述

edit

此API最多返回10,000个职位。

路径参数

edit

<job_id>: (可选，字符串) 异常检测作业的标识符。它可以是作业标识符、组名或通配符表达式。您可以通过使用组名、逗号分隔的作业列表或通配符表达式，在单个API请求中获取多个异常检测作业的统计信息。您可以通过使用_all，将*指定为作业标识符，或省略标识符来获取所有异常检测作业的统计信息。

查询参数

edit

allow_no_match

(可选, 布尔值) 指定在请求时执行的操作：

包含通配符表达式且没有匹配的作业。
包含 _all 字符串或没有标识符且没有匹配项。
包含通配符表达式且只有部分匹配。

响应体

edit

API返回有关作业操作进度的以下信息：

assignment_explanation: (字符串) 仅对于开放的异常检测作业，包含与选择运行作业的节点相关的消息。

data_counts

(对象) 一个描述作业输入数量及任何相关错误计数的对象。data_count 值是作业生命周期内的累积值。如果模型快照被还原或旧结果被删除，作业计数不会重置。

Properties of data_counts

bucket_count

(长整型) 作业生成的桶结果数量。

earliest_record_timestamp

(日期) 最早输入文档的时间戳。

empty_bucket_count

(长整型) 不包含任何数据的桶数量。如果您的数据包含许多空桶，请考虑增加您的 bucket_span 或使用对数据间隙容忍的函数，如 mean、non_null_sum 或 non_zero_count。

input_bytes

(长整型) 发布到异常检测作业的输入数据的字节数。

input_field_count

(长整型) 发布到异常检测作业的输入文档中的字段总数。此计数包括未在分析中使用的字段。但是，请注意，如果您使用数据馈送，它仅从检索到的文档中提取所需字段，然后将其发布到作业中。

input_record_count

(长整型) 发布到异常检测作业的输入文档数量。

invalid_date_count

(长整型) 缺少日期字段或日期无法解析的输入文档数量。

job_id

(字符串) 异常检测作业的标识符。

last_data_time

(日期) 根据服务器时间，数据最后一次被分析的时间戳。

latest_empty_bucket_timestamp

(日期) 不包含任何数据的最后一个桶的时间戳。

latest_record_timestamp

(日期) 最新输入文档的时间戳。

latest_sparse_bucket_timestamp

(日期) 被认为是稀疏的最后一个桶的时间戳。

log_time

(日期) data_counts 的时间戳，根据服务器时间。

missing_field_count

(长整型) 配置为分析异常检测作业的输入文档中缺少的字段数量。具有缺失字段的输入文档仍然会被处理，因为可能并非所有字段都缺失。

如果您正在使用数据馈送或将数据以JSON格式发布到作业中，高missing_field_count通常并不表示数据存在问题。这并不一定是一个需要关注的原因。

processed_record_count 的值包括此计数。

out_of_order_timestamp_count

(长整型) 时间戳在当前异常检测桶的延迟窗口偏移之前的时间戳的输入文档数量。此信息仅在您使用 post data API 向异常检测作业提供数据时适用。这些无序文档被丢弃，因为作业要求时间序列数据按时间顺序升序排列。

processed_field_count

异常检测作业处理的所有文档中的字段总数。仅在检测器配置对象中指定的字段对此计数有贡献。时间戳不包括在此计数中。

processed_record_count

(长整型) 异常检测作业处理的输入文档数量。此值包括具有缺失字段的文档，因为它们仍然被分析。如果您使用数据馈送并且在搜索查询中有聚合，processed_record_count 是处理的聚合结果数量，而不是Elasticsearch文档数量。

sparse_bucket_count

(长整型) 与预期数据点数量相比，包含较少数据点的桶数量。如果您的数据包含许多稀疏桶，请考虑使用更长的 bucket_span。

deleting

(布尔值) 表示删除作业的过程正在进行中，但尚未完成。仅当true时才会报告。

forecasts_stats

(对象) 提供关于属于此作业的预测的统计信息的对象。如果没有进行预测，则省略某些统计信息。

除非至少有一个预测，否则将省略 memory_bytes、records、processing_time_ms 和 status 属性。

Properties of forecasts_stats

forecasted_jobs: (long) 值为 0 表示此作业不存在预测。值为 1 表示至少存在一个预测。
memory_bytes: (对象) 与此作业相关的预测的内存使用量的 avg、min、max 和 total 值（以字节为单位）。如果没有预测，则省略此属性。
records: (对象) 与此作业相关的预测写入的 model_forecast 文档数量的 avg、min、max 和 total 值。如果没有预测，则省略此属性。
processing_time_ms: (对象) 与此作业相关的预测的运行时间的 avg、min、max 和 total 值（以毫秒为单位）。如果没有预测，则省略此属性。
status: (对象) 按状态统计的预测数量。例如：{"finished" : 2, "started" : 1}。如果没有预测，则省略此属性。
total: (long) 当前可用于该作业的单个预测的数量。值为 1 或更多表示存在预测。

job_id

(字符串) 异常检测作业的标识符。

model_size_stats

(对象) 一个提供有关模型大小和内容信息的对象。

Properties of model_size_stats

assignment_memory_basis

(字符串) 指示用于决定作业运行位置的内存需求的位置。可能的值有：

model_memory_limit: 作业的内存需求是基于其模型内存将增长到配置中的 model_memory_limit 来计算的。
current_model_bytes: 作业的内存需求是基于其当前模型内存大小来计算的，认为当前大小能很好地反映未来的情况。
peak_model_bytes: 作业的内存需求是基于其峰值模型内存大小来计算的，认为峰值大小能很好地反映未来的模型大小。

bucket_allocation_failures_count

(长整型) 由于模型内存不足而未处理传入数据中新实体的桶的数量。这种情况也通过 hard_limit: memory_status 属性值表示。

categorized_doc_count

(长整型) 已被分类字段分类的文档数量。

categorization_status

(字符串) 作业分类的状态。包含以下值之一：

ok: 分类表现良好（或根本未使用）。
warn: 分类检测到的类别分布表明输入数据不适合分类。问题可能是只有一个类别，超过90%的类别是稀有的，类别的数量大于已分类文档数量的50%，没有频繁匹配的类别，或者超过50%的类别是无效的。

dead_category_count

(长整型) 分类创建的永远不会再被分配的类别的数量，因为另一个类别的定义使其成为无效类别的超集。（无效类别是分类没有先验训练的副作用。）

failed_category_count

(长整型) 分类想要创建新类别但因作业达到其 model_memory_limit 而无法创建的次数。此计数不跟踪哪些特定类别未能创建。因此，您不能使用此值来确定错过的唯一类别数量。

frequent_category_count

(长整型) 匹配超过1%已分类文档的类别的数量。

job_id

(字符串) 异常检测作业的标识符。

log_time

(日期) 根据服务器时间，model_size_stats 的时间戳。

memory_status

(字符串) 数学模型的状态，可以具有以下值之一：

ok: 模型保持在配置值以下。
soft_limit: 模型使用了超过60%的配置内存限制，并且将修剪旧的未使用的模型以释放空间。此外，在分类作业中，不会存储更多的类别示例。
hard_limit: 模型使用的空间超过了配置的内存限制。因此，并非所有传入数据都被处理。

model_bytes

(长整型) 模型使用的内存字节数。这是自上次模型持久化以来的最大值。如果作业关闭，此值表示最新的大小。

model_bytes_exceeded

(长整型) 上次分配失败时内存使用量超过高限制的字节数。

model_bytes_memory_limit

(长整型) 模型内存使用量的上限，在增加值时检查。

peak_model_bytes

(长整型) 模型曾经使用的内存字节数的峰值。

rare_category_count

(长整型) 仅匹配一个已分类文档的类别的数量。

result_type

(字符串) 内部使用。结果的类型。

total_by_field_count

(长整型) 模型分析的 by 字段值的数量。此值是作业中所有检测器的累积值。

total_category_count

(长整型) 分类创建的类别的数量。

total_over_field_count

(长整型) 模型分析的 over 字段值的数量。此值是作业中所有检测器的累积值。

total_partition_field_count

(长整型) 模型分析的 partition 字段值的数量。此值是作业中所有检测器的累积值。

timestamp

(日期) 模型统计信息收集时的最后一条记录的时间戳。

node

(对象) 包含运行作业节点的属性。此信息仅对打开的作业可用。

Properties of node

attributes: (对象) 列出节点属性，例如 ml.machine_memory 或 ml.max_open_jobs 设置。
ephemeral_id: (字符串) 节点的临时ID。
id: (字符串) 节点的唯一标识符。
name: (字符串) 节点名称。
transport_address: (字符串) 接受传输HTTP连接的主机和端口。

open_time

(字符串) 仅针对开放职位，职位开放以来的已过时间。

state

(字符串) 异常检测作业的状态，可以是以下值之一：

closed: 作业成功完成，其模型状态已持久化。作业必须先打开才能接受进一步的数据。
closing: 作业关闭操作正在进行中，尚未完成。关闭的作业无法接受进一步的数据。
failed: 作业由于错误未能成功完成。这种情况可能由于无效的输入数据、分析过程中发生的致命错误或外部交互（如进程被Linux内存不足（OOM）杀手终止）引起。如果作业已不可逆转地失败，必须强制关闭然后删除。如果数据馈送可以修正，作业可以关闭然后重新打开。
opened: 作业可以接收和处理数据。
opening: 作业打开操作正在进行中，尚未完成。

timing_stats

(对象) 提供关于此作业时间方面的统计信息的对象。

Properties of timing_stats

average_bucket_processing_time_ms: (double) 所有桶处理时间的平均值，单位为毫秒。
bucket_count: (long) 处理的桶的数量。
exponential_average_bucket_processing_time_ms: (double) 所有桶处理时间的指数移动平均值，单位为毫秒。
exponential_average_bucket_processing_time_per_hour_ms: (double) 在1小时时间窗口内计算的桶处理时间的指数加权移动平均值，单位为毫秒。
job_id: (string) 异常检测作业的标识符。
maximum_bucket_processing_time_ms: (double) 所有桶处理时间中的最大值，单位为毫秒。
minimum_bucket_processing_time_ms: (double) 所有桶处理时间中的最小值，单位为毫秒。
total_bucket_processing_time_ms: (double) 所有桶处理时间的总和，单位为毫秒。

响应代码

edit

404 (Missing resources): 如果 allow_no_match 是 false，此代码表示没有与请求匹配的资源，或者只有部分匹配的请求。

示例

edit

GET _ml/anomaly_detectors/low_request_rate/_stats

API返回以下结果：

{
  "count" : 1,
  "jobs" : [
    {
      "job_id" : "low_request_rate",
      "data_counts" : {
        "job_id" : "low_request_rate",
        "processed_record_count" : 1216,
        "processed_field_count" : 1216,
        "input_bytes" : 51678,
        "input_field_count" : 1216,
        "invalid_date_count" : 0,
        "missing_field_count" : 0,
        "out_of_order_timestamp_count" : 0,
        "empty_bucket_count" : 242,
        "sparse_bucket_count" : 0,
        "bucket_count" : 1457,
        "earliest_record_timestamp" : 1575172659612,
        "latest_record_timestamp" : 1580417369440,
        "last_data_time" : 1576017595046,
        "latest_empty_bucket_timestamp" : 1580356800000,
        "input_record_count" : 1216
      },
      "model_size_stats" : {
        "job_id" : "low_request_rate",
        "result_type" : "model_size_stats",
        "model_bytes" : 41480,
        "model_bytes_exceeded" : 0,
        "model_bytes_memory_limit" : 10485760,
        "total_by_field_count" : 3,
        "total_over_field_count" : 0,
        "total_partition_field_count" : 2,
        "bucket_allocation_failures_count" : 0,
        "memory_status" : "ok",
        "categorized_doc_count" : 0,
        "total_category_count" : 0,
        "frequent_category_count" : 0,
        "rare_category_count" : 0,
        "dead_category_count" : 0,
        "failed_category_count" : 0,
        "categorization_status" : "ok",
        "log_time" : 1576017596000,
        "timestamp" : 1580410800000
      },
      "forecasts_stats" : {
        "total" : 1,
        "forecasted_jobs" : 1,
        "memory_bytes" : {
          "total" : 9179.0,
          "min" : 9179.0,
          "avg" : 9179.0,
          "max" : 9179.0
        },
        "records" : {
          "total" : 168.0,
          "min" : 168.0,
          "avg" : 168.0,
          "max" : 168.0
        },
        "processing_time_ms" : {
          "total" : 40.0,
          "min" : 40.0,
          "avg" : 40.0,
          "max" : 40.0
        },
        "status" : {
          "finished" : 1
        }
      },
      "state" : "opened",
      "node" : {
        "id" : "7bmMXyWCRs-TuPfGJJ_yMw",
        "name" : "node-0",
        "ephemeral_id" : "hoXMLZB0RWKfR9UPPUCxXX",
        "transport_address" : "127.0.0.1:9300",
        "attributes" : {
          "ml.machine_memory" : "17179869184",
          "xpack.installed" : "true",
          "ml.max_open_jobs" : "512"
        }
      },
      "assignment_explanation" : "",
      "open_time" : "13s",
      "timing_stats" : {
        "job_id" : "low_request_rate",
        "bucket_count" : 1457,
        "total_bucket_processing_time_ms" : 1094.000000000001,
        "minimum_bucket_processing_time_ms" : 0.0,
        "maximum_bucket_processing_time_ms" : 48.0,
        "average_bucket_processing_time_ms" : 0.75085792724777,
        "exponential_average_bucket_processing_time_ms" : 0.5571716855800993,
        "exponential_average_bucket_processing_time_per_hour_ms" : 15.0
      }
    }
  ]
}

获取模型快照 API

edit

检索有关模型快照的信息。

请求

edit

GET _ml/anomaly_detectors//model_snapshots

GET _ml/anomaly_detectors//model_snapshots/

先决条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

路径参数

edit

<job_id>

(必需, 字符串) 异常检测作业的标识符。

<snapshot_id>

(可选, 字符串) 模型快照的标识符。

您可以通过使用逗号分隔的列表或通配符表达式来获取多个快照的信息。您可以通过使用 _all，将快照 ID 指定为 *，或者省略快照 ID 来获取所有快照。

查询参数

edit

desc: (可选, 布尔值) 如果为 true，结果按降序排序。默认为 false。
end: (可选，日期) 返回时间戳早于该时间的快照。默认为未设置，这意味着结果不受特定时间戳的限制。
from: (可选，整数) 跳过指定数量的快照。默认为 0。
size: (可选，整数) 指定要获取的最大快照数量。默认为 100。
sort: (可选，字符串) 指定请求快照的排序字段。默认情况下，快照按其时间戳排序。
start: (可选，字符串) 返回时间戳在此时间之后的快照。默认为未设置，这意味着结果不受特定时间戳的限制。

请求体

edit

您也可以在请求体中指定查询参数；例外的是from和size，请使用page代替：

page

page的属性

from: (可选, 整数) 跳过指定数量的快照。默认为0。
size: (可选, 整数) 指定要获取的最大快照数量。默认为100。

响应体

edit

API返回一个模型快照对象数组，这些对象具有以下属性：

description: (字符串) 作业的可选描述。
job_id: (字符串) 一个唯一标识为快照创建的任务的数值字符串。
latest_record_time_stamp: (日期) 最新处理记录的时间戳。
latest_result_time_stamp: (日期) 最新存储桶结果的时间戳。
min_version: (字符串) 恢复模型快照所需的最小机器学习配置版本号。

从 Elasticsearch 8.10.0 开始，使用了一个新的版本号来跟踪机器学习插件中的配置和状态变化。这个新的版本号与产品版本解耦，并将独立递增。min_version 值代表新的版本号。

model_size_stats

(对象) 描述模型的摘要信息。

Properties of model_size_stats

assignment_memory_basis

(字符串) 指示用于决定作业运行位置的内存需求的位置。可能的值有：

model_memory_limit: The job’s memory requirement is calculated on the basis that its model memory will grow to the model_memory_limit specified in the analysis_limits of its config.
current_model_bytes: The job’s memory requirement is calculated on the basis that its current model memory size is a good reflection of what it will be in the future.
peak_model_bytes: The job’s memory requirement is calculated on the basis that its peak model memory size is a good reflection of what the model size will be in the future.

bucket_allocation_failures_count

(长整型) 由于内存限制约束而未处理实体的桶的数量。

categorized_doc_count

(长整型) 已对字段进行分类的文档数量。

categorization_status

(字符串) 该作业的分类状态。包含以下值之一。

ok: Categorization is performing acceptably well (or not being used at all).
warn: Categorization is detecting a distribution of categories that suggests the input data is inappropriate for categorization. Problems could be that there is only one category, more than 90% of categories are rare, the number of categories is greater than 50% of the number of categorized documents, there are no frequently matched categories, or more than 50% of categories are dead.

dead_category_count

(长整型) 分类创建的永远不会再分配的类别数量，因为另一个类别的定义使其成为死类别的超集。（死类别是分类没有先前训练的副作用。）

failed_category_count

(长整型) 分类想要创建新类别但因作业达到其model_memory_limit而无法创建的次数。此计数不跟踪哪些特定类别未能创建。因此，您无法使用此值来确定错过的唯一类别数量。

frequent_category_count

(长整型) 匹配超过1%的已分类文档的类别数量。

job_id

(字符串) 异常检测作业的标识符。

log_time

(日期) 根据服务器时间记录model_size_stats的时间戳。

memory_status

(字符串) 内存状态与其model_memory_limit的关系。包含以下值之一。

hard_limit: The internal models require more space than the configured memory limit. Some incoming data could not be processed.
ok: The internal models stayed below the configured value.
soft_limit: The internal models require more than 60% of the configured memory limit and more aggressive pruning will be performed in order to try to reclaim space.

model_bytes

(长整型) 此分析所需的内存资源的近似值。

model_bytes_exceeded

(长整型) 上次分配失败时内存使用量超过高限制的字节数。

model_bytes_memory_limit

(长整型) 内存使用量的上限，在增加值时进行检查。

peak_model_bytes

(长整型) 模型内存使用的最高记录值。

rare_category_count

(长整型) 仅匹配一个已分类文档的类别数量。

result_type

(字符串) 内部。此值始终为model_size_stats。

timestamp

(日期) 根据数据的桶时间戳记录model_size_stats的时间戳。

total_by_field_count

(长整型) 分析的by字段值的数量。请注意，这些值是针对每个检测器和分区单独计数的。

total_category_count

(长整型) 分类创建的类别数量。

total_over_field_count

(长整型) 分析的over字段值的数量。请注意，这些值是针对每个检测器和分区单独计数的。

total_partition_field_count

(长整型) 分析的partition字段值的数量。

retain

(布尔值) 如果为true，此快照在超过model_snapshot_retention_days的自动清理过程中不会被删除。然而，当作业被删除时，此快照将被删除。默认值为false。

snapshot_id

(字符串) 一个唯一标识模型快照的数值字符串。例如："1491852978"。

snapshot_doc_count

(长整型) 仅限内部使用。

timestamp

(日期) 快照的创建时间戳。

示例

edit

GET _ml/anomaly_detectors/high_sum_total_sales/model_snapshots
{
  "start": "1575402236000"
}

在这个例子中，API提供了一个单一的结果：

{
  "count" : 1,
  "model_snapshots" : [
    {
      "job_id" : "high_sum_total_sales",
      "min_version" : "6.4.0",
      "timestamp" : 1575402237000,
      "description" : "State persisted due to job close at 2019-12-03T19:43:57+0000",
      "snapshot_id" : "1575402237",
      "snapshot_doc_count" : 1,
      "model_size_stats" : {
        "job_id" : "high_sum_total_sales",
        "result_type" : "model_size_stats",
        "model_bytes" : 1638816,
        "model_bytes_exceeded" : 0,
        "model_bytes_memory_limit" : 10485760,
        "total_by_field_count" : 3,
        "total_over_field_count" : 3320,
        "total_partition_field_count" : 2,
        "bucket_allocation_failures_count" : 0,
        "memory_status" : "ok",
        "categorized_doc_count" : 0,
        "total_category_count" : 0,
        "frequent_category_count" : 0,
        "rare_category_count" : 0,
        "dead_category_count" : 0,
        "categorization_status" : "ok",
        "log_time" : 1575402237000,
        "timestamp" : 1576965600000
      },
      "latest_record_time_stamp" : 1576971072000,
      "latest_result_time_stamp" : 1576965600000,
      "retain" : false
    }
  ]
}

获取异常检测作业模型快照升级统计信息 API

edit

检索异常检测作业模型快照升级的使用信息。

请求

edit

GET _ml/anomaly_detectors//model_snapshots//_upgrade/_stats

GET _ml/anomaly_detectors/,/model_snapshots/_all/_upgrade/_stats

GET _ml/anomaly_detectors/_all/model_snapshots/_all/_upgrade/_stats

先决条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

描述

edit

异常检测作业模型快照升级是临时的。只有在此API被调用时正在进行中的升级才会被返回。

路径参数

edit

<job_id>

(字符串) 异常检测作业的标识符。它可以是作业标识符、组名或通配符表达式。

<snapshot_id>

(字符串) 模型快照的标识符。

您可以通过使用逗号分隔的快照ID列表，在单个API请求中获取多个异常检测作业模型快照升级的统计信息。您还可以使用通配符表达式或_all。

查询参数

edit

allow_no_match

(可选, 布尔值) 指定在请求时执行的操作：

包含通配符表达式且没有匹配的作业。
包含 _all 字符串或没有标识符且没有匹配项。
包含通配符表达式且只有部分匹配。

响应体

edit

API返回一个异常检测作业模型快照升级状态对象的数组。所有这些属性都是信息性的；您不能更新它们的值。

assignment_explanation

(字符串) 仅对于已启动的数据馈送，包含与节点选择相关的消息。

job_id

(字符串) 异常检测作业的标识符。

node

(对象) 包含运行升级任务的节点的属性。此信息仅适用于分配给节点的升级任务。

详情

attributes: (对象) 列出节点的属性，例如 ml.machine_memory 或 ml.max_open_jobs 设置。
ephemeral_id: (字符串) 节点的临时ID。
id: (字符串) 节点的唯一标识符。
name: (字符串) 节点名称。例如，0-o0tOo。
transport_address: (字符串) 接受传输HTTP连接的主机和端口。

snapshot_id

(字符串) 一个唯一标识模型快照的数值字符串。例如，1575402236000。

state

(字符串) 其中之一为 loading_old_state、saving_new_state、stopped 或 failed。

响应代码

edit

404 (Missing resources): 如果 allow_no_match 是 false，此代码表示没有与请求匹配的资源，或者只有部分匹配的请求。

示例

edit

GET _ml/anomaly_detectors/low_request_rate/model_snapshots/_all/_upgrade/_stats

API返回以下结果：

{
  "count" : 1,
  "model_snapshot_upgrades" : [
    {
      "job_id" : "low_request_rate",
      "snapshot_id" : "1828371",
      "state" : "saving_new_state",
      "node" : {
        "id" : "7bmMXyWCRs-TuPfGJJ_yMw",
        "name" : "node-0",
        "ephemeral_id" : "hoXMLZB0RWKfR9UPPUCxXX",
        "transport_address" : "127.0.0.1:9300",
        "attributes" : {
          "ml.machine_memory" : "17179869184",
          "ml.max_open_jobs" : "512"
        }
      },
      "assignment_explanation" : ""
    }
  ]
}

获取总体桶 API

edit

检索汇总多个异常检测作业的存储桶结果的总体存储桶结果。

请求

edit

GET _ml/anomaly_detectors//results/overall_buckets

GET _ml/anomaly_detectors/,/results/overall_buckets

GET _ml/anomaly_detectors/_all/results/overall_buckets

先决条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

描述

edit

默认情况下，总体桶的跨度等于指定异常检测作业中最大桶跨度。要覆盖此行为，请使用可选的bucket_span参数。要了解更多关于桶的概念，请参阅桶。

通过结合总体桶跨度内所有桶的分数来计算overall_score。首先，计算总体桶中每个异常检测作业的最大anomaly_score。然后对这些分数中的top_n进行平均，以得出overall_score。这意味着您可以微调overall_score，使其对同时检测到异常的作业数量更加敏感或不敏感。例如，如果将top_n设置为1，则overall_score是总体桶中的最大桶分数。或者，如果将top_n设置为作业数量，则仅当所有作业在该总体桶中检测到异常时，overall_score才会高。如果将bucket_span参数（设置为大于其默认值的值），则overall_score是具有等于作业最大桶跨度的跨度的总体桶的最大overall_score。

路径参数

edit

<job_id>

(必需, 字符串) 异常检测作业的标识符。它可以是作业标识符、组名称、逗号分隔的作业或组列表，或通配符表达式。

您可以通过使用 _all 或指定 * 作为作业标识符来汇总所有异常检测作业的存储桶结果。

查询参数

edit

allow_no_match

(可选, 布尔值) 指定在请求时执行的操作：

包含通配符表达式且没有匹配的作业。
包含 _all 字符串或没有标识符且没有匹配项。
包含通配符表达式且只有部分匹配。

bucket_span

(可选，字符串) 总体桶的跨度。必须大于或等于指定的异常检测作业的最大桶跨度，这是默认值。

end

(可选，字符串) 返回时间戳早于此时间的总体桶。默认为 -1，这意味着它未设置，结果不受特定时间戳的限制。

exclude_interim

(可选，布尔值) 如果为 true，输出将排除临时的整体桶。整体桶是临时的，如果整体桶区间内的任何作业桶是临时的。默认为 false，这意味着包含临时结果。

overall_score

(可选，双精度) 返回总体得分大于或等于此值的总体桶。默认为 0.0。

start

(可选，字符串) 返回时间戳在此时间之后的总体桶。默认为 -1，这意味着未设置，结果不受特定时间戳的限制。

top_n

(可选，整数) 用于计算 overall_score 的顶部异常检测作业桶分数的数量。默认为 1。

请求体

edit

您还可以在请求体中指定查询参数（例如 allow_no_match 和 bucket_span）。

响应体

edit

API返回一个整体存储桶对象的数组，这些对象具有以下属性：

bucket_span: (数字) 桶的长度，以秒为单位。匹配具有最长桶跨度的作业的 bucket_span。
is_interim: (布尔值) 如果true，这是一个中间结果。换句话说，结果是基于部分输入数据计算的。
jobs: (数组) 包含每个 job_id 的 max_anomaly_score 的对象数组。
overall_score: (数字) 每个作业的最大桶 anomaly_score 的 top_n 平均值。
result_type: (字符串) 内部使用。这总是设置为 overall_bucket。
timestamp: (日期) 计算这些结果的存储桶的开始时间。

示例

edit

GET _ml/anomaly_detectors/job-*/results/overall_buckets
{
  "overall_score": 80,
  "start": "1403532000000"
}

在这个例子中，API返回了一个符合指定分数和时间约束的单一结果。overall_score 是最大工作分数，因为当未指定时，top_n 默认为1：

{
  "count": 1,
  "overall_buckets": [
    {
      "timestamp" : 1403532000000,
      "bucket_span" : 3600,
      "overall_score" : 80.0,
      "jobs" : [
        {
          "job_id" : "job-1",
          "max_anomaly_score" : 30.0
        },
        {
          "job_id" : "job-2",
          "max_anomaly_score" : 10.0
        },
        {
          "job_id" : "job-3",
          "max_anomaly_score" : 80.0
        }
      ],
      "is_interim" : false,
      "result_type" : "overall_bucket"
    }
  ]
}

下一个示例与此类似，但这次top_n设置为2：

GET _ml/anomaly_detectors/job-*/results/overall_buckets
{
  "top_n": 2,
  "overall_score": 50.0,
  "start": "1403532000000"
}

注意overall_score现在是前2个工作分数的平均值：

{
  "count": 1,
  "overall_buckets": [
    {
      "timestamp" : 1403532000000,
      "bucket_span" : 3600,
      "overall_score" : 55.0,
      "jobs" : [
        {
          "job_id" : "job-1",
          "max_anomaly_score" : 30.0
        },
        {
          "job_id" : "job-2",
          "max_anomaly_score" : 10.0
        },
        {
          "job_id" : "job-3",
          "max_anomaly_score" : 80.0
        }
      ],
      "is_interim" : false,
      "result_type" : "overall_bucket"
    }
  ]
}

获取预定事件 API

edit

检索日历中预定事件的信息。

请求

edit

GET _ml/calendars//events

GET _ml/calendars/_all/events

前提条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

描述

edit

有关更多信息，请参阅日历和预定事件。

路径参数

edit

<calendar_id>

(必需, 字符串) 一个唯一标识日历的字符串。

您可以通过使用逗号分隔的id列表或通配符表达式，在单个API请求中获取多个日历的预定事件信息。您可以使用_all或*作为日历标识符来获取所有日历的预定事件信息。

查询参数

edit

end: (可选，字符串) 指定获取时间戳早于该时间的事件。
from: (可选，整数) 跳过指定数量的事件。默认为 0。
job_id: (可选，字符串) 指定获取特定异常检测作业标识符或作业组的事件。它必须与日历标识符 _all 或 * 一起使用。
size: (可选, 整数) 指定要获取的最大事件数量。默认为 100。
start: (可选，字符串) 指定获取时间戳在此时间之后的事件。

请求体

edit

您也可以在请求体中指定查询参数；例外的是from和size，请使用page代替：

page

属性 page

from: (可选, 整数) 跳过指定数量的事件。默认为 0。
size: (可选, 整数) 指定要获取的最大事件数量。默认为 100。

响应体

edit

API返回一个预定事件资源的数组，这些资源具有以下属性：

calendar_id: (字符串) 一个唯一标识日历的字符串。
description: (字符串) 计划事件的描述。
end_time: (日期) 计划事件结束时间的时间戳，自纪元以来的毫秒数或ISO 8601格式。
event_id: (字符串) 计划事件的自动生成标识符。
start_time: (日期) 计划事件开始的时间戳，以自纪元以来的毫秒数或ISO 8601格式表示。

示例

edit

GET _ml/calendars/planned-outages/events

API返回以下结果：

{
  "count": 3,
  "events": [
    {
      "description": "event 1",
      "start_time": 1513641600000,
      "end_time": 1513728000000,
      "calendar_id": "planned-outages",
      "event_id": "LS8LJGEBMTCMA-qz49st"
    },
    {
      "description": "event 2",
      "start_time": 1513814400000,
      "end_time": 1513900800000,
      "calendar_id": "planned-outages",
      "event_id": "Li8LJGEBMTCMA-qz49st"
    },
    {
      "description": "event 3",
      "start_time": 1514160000000,
      "end_time": 1514246400000,
      "calendar_id": "planned-outages",
      "event_id": "Ly8LJGEBMTCMA-qz49st"
    }
  ]
}

以下示例检索在特定时间段内发生的预定事件：

GET _ml/calendars/planned-outages/events?start=1635638400000&end=1635724800000

获取过滤器 API

edit

检索过滤器。

请求

edit

GET _ml/filters/

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

您可以获取单个过滤器或所有过滤器。更多信息，请参阅自定义规则。

路径参数

edit

<filter_id>: (可选, 字符串) 一个唯一标识过滤器的字符串。

查询参数

edit

from: (可选，整数) 跳过指定数量的过滤器。默认为 0。
size: (可选，整数) 指定要获取的最大过滤器数量。默认为 100。

响应体

edit

API返回一个过滤器资源的数组，这些资源具有以下属性：

description: (字符串) 过滤器的描述。
filter_id: (字符串) 一个唯一标识过滤器的字符串。
items: (字符串数组) 一个字符串数组，表示过滤项列表。

示例

edit

GET _ml/filters/safe_domains

API返回以下结果：

{
  "count": 1,
  "filters": [
    {
      "filter_id": "safe_domains",
      "description": "A list of safe domains",
      "items": [
        "*.google.com",
        "wikipedia.org"
      ]
    }
  ]
}

获取记录 API

edit

检索异常检测任务的异常记录。

请求

edit

GET _ml/anomaly_detectors//results/records

先决条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

描述

edit

记录包含详细的分析结果。它们描述了根据检测器配置在输入数据中识别出的异常活动。

根据输入数据的特性和大小，可能会有许多异常记录。在实际操作中，通常会有太多而无法手动处理。因此，机器学习功能会对异常记录进行复杂的聚合，将其分组到不同的桶中。

记录结果的数量取决于每个桶中发现的异常数量，这与正在建模的时间序列数量和检测器的数量有关。

路径参数

edit

<job_id>: (必需, 字符串) 异常检测作业的标识符。

查询参数

edit

desc: (可选，布尔值) 如果为true，结果按降序排序。
end: (可选，字符串) 返回时间戳早于此时间的记录。默认为 -1，这意味着它未设置，结果不受限于特定的时间戳。
exclude_interim: (可选, 布尔值) 如果为true，输出将排除中间结果。默认为false，这意味着中间结果会被包含。
from: (可选, 整数) 跳过指定数量的记录。默认为 0。
record_score: (可选，双精度) 返回异常分数大于或等于此值的记录。默认为 0.0。
size: (可选, 整数) 指定要获取的最大记录数。默认为 100。
sort: (可选，字符串) 指定请求记录的排序字段。默认情况下，记录按 record_score 值排序。
start: (可选，字符串) 返回时间戳在此时间之后的记录。默认为 -1，这意味着它未设置，结果不受特定时间戳的限制。

请求体

edit

您也可以在请求体中指定查询参数；例外的是from和size，请使用page代替：

page

属性 page

from: (可选, 整数) 跳过指定数量的记录。默认为 0。
size: (可选, 整数) 指定要获取的最大记录数。默认为 100。

响应体

edit

API返回一个记录对象数组，这些对象具有以下属性：

actual: (数组) 桶的实际值。

anomaly_score_explanation

(对象) 当存在时，它提供了影响初始异常分数的因素的信息。

Properties of anomaly_score_explanation

anomaly_characteristics_impact: (可选, 整数) 相对于历史平均值，检测到的异常的持续时间和幅度的影响。
anomaly_length: (可选, 整数) 检测到的异常在桶数量中的长度。
anomaly_type: (可选, 字符串) 检测到的异常类型：峰值或下降。
high_variance_penalty: (可选, 布尔值) 指示对具有大置信区间的桶的异常分数的减少。如果一个桶有大置信区间，分数会减少。
incomplete_bucket_penalty: (可选, 布尔值) 如果桶包含的样本少于预期，分数会减少。如果桶包含的样本少于预期，分数会减少。
lower_confidence_bound: (可选, 双精度浮点数) 95%置信区间的下限。
multimodal_distribution: (可选, 布尔值) 指示桶值的概率分布是否有几个模式。当有多个模式时，典型值可能不是最可能的。
multi_bucket_impact: (可选, 整数) 过去12个桶中实际值和典型值之间偏差的影响。
single_bucket_impact: (可选, 整数) 当前桶中实际值和典型值之间偏差的影响。
typical_value: (可选, 双精度浮点数) 此桶的典型（预期）值。
upper_confidence_bound: (可选, 双精度浮点数) 95%置信区间的上限。

bucket_span

(数字) 存储桶的长度，以秒为单位。该值与作业中指定的bucket_span相匹配。

by_field_name

(字符串) 用于分割数据的字段。特别是，此属性用于根据其自身历史分析分割。它用于在分割的上下文中查找异常值。

by_field_value

(字符串) by_field_name 的值。

causes

(数组) 对于人口分析，必须在检测器中指定一个over字段。此属性包含一个异常记录数组，这些记录是已识别的over字段异常的原因。如果没有over字段存在，则此字段不存在。此子资源包含over_field_name的最异常记录。出于可扩展性原因，最多返回10个最显著的异常原因。作为核心分析建模的一部分，这些低级异常记录会聚合到它们的父over字段记录中。原因资源包含与记录资源类似的元素，即actual、typical、geo_results.actual_point、 geo_results.typical_point、*_field_name和*_field_value。概率和分数不适用于原因。

detector_index

(数字) 检测器的唯一标识符。

field_name

(字符串) 某些函数需要一个字段来进行操作，例如，sum()。对于这些函数，此值是要分析的字段的名称。

function

(字符串) 在检测器配置中指定的发生异常的函数。例如，max。

function_description

(字符串) 异常发生时所在函数的描述，如检测器配置中所指定。

geo_results

(可选, 对象) 如果检测器函数是 lat_long，此对象包含实际值和典型值的纬度和经度的逗号分隔字符串。

Properties of geo_results

actual_point: (字符串) 该桶的实际值，格式为 geo_point。
typical_point: (字符串) 该桶的典型值，格式为 geo_point。

influencers

(数组) 如果在检测器配置中指定了influencers，则此数组包含对异常有贡献或应负责的影响者。

initial_record_score

(数字) 一个介于0-100之间的标准化分数，基于该记录异常性的概率。这是在处理桶时计算的初始值。

is_interim

(布尔值) 如果true，这是一个中间结果。换句话说，结果是基于部分输入数据计算的。

job_id

(字符串) 异常检测作业的标识符。

multi_bucket_impact

(数字) 表示异常是多桶还是单桶的强度。值的范围从 -5.0 到 +5.0，其中 -5.0 表示异常完全是单桶，而 +5.0 表示异常完全是多桶。

over_field_name

(字符串) 用于分割数据的字段。特别是，此属性用于根据所有分割的历史进行分析。它用于在所有分割的总体中查找异常值。有关更多信息，请参阅执行总体分析。

over_field_value

(字符串) over_field_name 的值。

partition_field_name

(字符串) 用于分割分析的字段。当您使用此属性时，您将为该字段的每个值设置完全独立的基线。

partition_field_value

(字符串) partition_field_name 的值。

probability

(数字) 个体异常发生的概率，范围在0到1之间。例如，0.0000772031。这个值可以保持超过300位小数的高精度，因此提供了record_score作为这个值的人类可读和友好的解释。

record_score

(数字) 一个介于0-100之间的标准化分数，基于该记录异常的概率。与initial_record_score不同，随着新数据的分析，该值会通过重新标准化过程进行更新。

result_type

(字符串) 内部使用。这总是设置为 record。

timestamp

(日期) 计算这些结果的存储桶的开始时间。

typical

(数组) 根据分析建模得出的桶的典型值。

根据正在分析的字段，会添加额外的记录属性。例如，如果它正在将 hostname 分析为 by 字段，那么会在结果文档中添加一个 hostname 字段。这些信息使您能够更轻松地过滤异常结果。

示例

edit

GET _ml/anomaly_detectors/low_request_rate/results/records
{
  "sort": "record_score",
  "desc": true,
  "start": "1454944100000"
}

{
  "count" : 4,
  "records" : [
    {
      "job_id" : "low_request_rate",
      "result_type" : "record",
      "probability" : 1.3882308899968812E-4,
      "multi_bucket_impact" : -5.0,
      "record_score" : 94.98554565630553,
      "initial_record_score" : 94.98554565630553,
      "bucket_span" : 3600,
      "detector_index" : 0,
      "is_interim" : false,
      "timestamp" : 1577793600000,
      "function" : "low_count",
      "function_description" : "count",
      "typical" : [
        28.254208230188834
      ],
      "actual" : [
        0.0
      ]
    },
  ...
  ]
}

打开异常检测作业 API

edit

打开一个或多个异常检测作业。

请求

edit

POST _ml/anomaly_detectors/{job_id}/_open

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

为了能够接收和分析数据，必须打开异常检测作业。在其生命周期中，它可以被多次打开和关闭。

当你打开一个新任务时，它会从一个空模型开始。

当您打开一个现有的作业时，最新的模型状态会自动加载。一旦收到新数据，作业就可以从上次中断的地方继续进行分析。

路径参数

edit

<job_id>: (必需, 字符串) 异常检测作业的标识符。

查询参数

edit

timeout: (可选，时间) 控制等待作业打开的时间。默认值是30分钟。

请求体

edit

您还可以在请求体中指定timeout查询参数。

响应体

edit

node: (字符串) 作业被打开的节点的ID。如果允许作业延迟打开且尚未分配给节点，则此值为空字符串。
opened: (布尔值) 对于成功的响应，此值始终为 true。在失败的情况下，将返回异常。

示例

edit

POST _ml/anomaly_detectors/low_request_rate/_open
{
  "timeout": "35m"
}

当作业打开时，您会收到以下结果：

{
  "opened" : true,
  "node" : "node-1"
}

向作业API发送数据

edit

在7.11.0中已弃用。

直接向异常检测作业发布数据已被弃用，在未来的主要版本中，将需要一个数据流。

将数据发送到异常检测作业进行分析。

请求

edit

POST _ml/anomaly_detectors//_data

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

作业必须处于打开状态才能接收和处理数据。

发送到作业的数据必须使用 JSON 格式。可以发送多个 JSON 文档，它们可以是相邻的，中间没有分隔符，或者是用空白分隔的。换行符分隔的 JSON（NDJSON）是一种可能的空白分隔格式，对于这种格式，Content-Type 头应设置为 application/x-ndjson。

上传大小限制为 Elasticsearch HTTP 接收缓冲区大小（默认 100 Mb）。如果您的数据较大，请将其拆分为多个块，并按时间顺序分别上传每个块。在实时运行时，通常建议您执行多次小规模上传，而不是将数据排队以上传较大的文件。

上传数据时，检查作业数据计数以了解进度。以下文档将不会被处理：

文档未按时间顺序排列且超出延迟窗口
带有无效时间戳的记录

对于每个任务，数据一次只能从一个连接接收。目前不支持使用通配符或逗号分隔列表向多个任务发送数据。

路径参数

edit

<job_id>: (必需, 字符串) 异常检测作业的标识符。

查询参数

edit

reset_start: (可选，字符串) 指定桶重置范围的开始。
reset_end: (可选，字符串) 指定桶重置范围的结束。

请求体

edit

包含要分析数据的一个或多个JSON文档序列。仅允许在文档之间使用空白字符。

示例

edit

以下示例将数据从 it_ops_new_kpi.json 文件发布到 it_ops_new_kpi 作业：

$ curl -s -H "Content-type: application/json"
-X POST http:\/\/localhost:9200/_ml/anomaly_detectors/it_ops_new_kpi/_data
--data-binary @it_ops_new_kpi.json

当数据发送时，您会收到有关作业操作进度的信息。例如：

{
	"job_id":"it_ops_new_kpi",
	"processed_record_count":21435,
	"processed_field_count":64305,
	"input_bytes":2589063,
	"input_field_count":85740,
	"invalid_date_count":0,
	"missing_field_count":0,
	"out_of_order_timestamp_count":0,
	"empty_bucket_count":16,
	"sparse_bucket_count":0,
	"bucket_count":2165,
	"earliest_record_timestamp":1454020569000,
	"latest_record_timestamp":1455318669000,
	"last_data_time":1491952300658,
	"latest_empty_bucket_timestamp":1454541600000,
	"input_record_count":21435
}

有关这些属性的更多信息，请参阅响应体。

预览数据馈送 API

edit

预览数据源。

请求

edit

GET _ml/datafeeds//_preview

POST _ml/datafeeds//_preview

GET _ml/datafeeds/_preview

POST _ml/datafeeds/_preview

先决条件

edit

需要以下权限：

集群：manage_ml（内置角色 machine_learning_admin 授予此权限）
数据馈送中配置的源索引：read。

描述

edit

预览数据馈送 API 返回数据馈送中搜索结果的第一页。您可以预览现有的数据馈送，或在 API 中提供数据馈送和异常检测作业的配置详细信息。预览显示将传递给异常检测引擎的数据结构。

当启用了Elasticsearch安全功能时，数据馈送查询将使用调用预览数据馈送API的用户的凭据进行预览。当数据馈送启动时，它将使用最后创建或更新它的用户的角色运行查询。如果这两组角色不同，则预览可能无法准确反映数据馈送启动时将返回的内容。为了避免此类问题，创建或更新数据馈送的同一用户应预览它，以确保它返回预期的数据。或者，使用二次授权头来提供凭据。

路径参数

edit

<datafeed_id>: (可选, 字符串) 一个唯一标识数据流的数字字符串。此标识符可以包含小写字母数字字符（a-z 和 0-9）、连字符和下划线。它必须以字母数字字符开头和结尾。

如果你提供作为路径参数，你不能在请求体中提供数据馈送或异常检测作业的配置细节。

查询参数

edit

end

(可选，字符串) 数据流预览应结束的时间。预览可能不会到达所提供值的末尾，因为仅返回结果的第一页。时间可以通过使用以下格式之一来指定：

ISO 8601格式带毫秒，例如 2017-01-22T06:00:00.000Z
ISO 8601格式不带毫秒，例如 2017-01-22T06:00:00+00:00
自纪元以来的毫秒数，例如 1485061200000

使用ISO 8601格式之一的日期时间参数必须具有时区标识符，其中Z被接受为UTC时间的缩写。

当需要一个URL时（例如，在浏览器中），时间区标识符中使用的+必须编码为%2B。

此值是独占的。

start

(可选，字符串) 数据流预览应开始的时间，可以使用与 end 参数相同的格式来指定。该值是包含的。

如果你没有提供start或end参数，数据馈送预览将在整个时间段内进行搜索，但会排除位于cold或frozen 数据层中的数据。

请求体

edit

datafeed_config: (可选, 对象) 要预览的数据馈送定义。有关有效的定义，请参阅创建数据馈送 API。
job_config: (可选，对象) 与数据馈送关联的异常检测作业的配置详细信息。如果 datafeed_config 对象不包含引用现有异常检测作业的 job_id，则必须提供此 job_config 对象。如果同时包含 job_id 和 job_config，则使用后者的信息。除非同时提供 datafeed_config 对象，否则不能指定 job_config 对象。有关有效定义，请参阅创建异常检测作业 API。

示例

edit

这是一个提供现有数据源ID的示例：

GET _ml/datafeeds/datafeed-high_sum_total_sales/_preview

此示例返回的数据如下：

[
  {
    "order_date" : 1574294659000,
    "category.keyword" : "Men's Clothing",
    "customer_full_name.keyword" : "Sultan Al Benson",
    "taxful_total_price" : 35.96875
  },
  {
    "order_date" : 1574294918000,
    "category.keyword" : [
      "Women's Accessories",
      "Women's Clothing"
    ],
    "customer_full_name.keyword" : "Pia Webb",
    "taxful_total_price" : 83.0
  },
  {
    "order_date" : 1574295782000,
    "category.keyword" : [
      "Women's Accessories",
      "Women's Shoes"
    ],
    "customer_full_name.keyword" : "Brigitte Graham",
    "taxful_total_price" : 72.0
  }
]

以下示例提供了数据馈送和异常检测作业配置的API详细信息：

POST _ml/datafeeds/_preview
{
  "datafeed_config": {
    "indices" : [
      "kibana_sample_data_ecommerce"
    ],
    "query" : {
      "bool" : {
        "filter" : [
          {
            "term" : {
              "_index" : "kibana_sample_data_ecommerce"
            }
          }
        ]
      }
    },
    "scroll_size" : 1000
  },
  "job_config": {
    "description" : "Find customers spending an unusually high amount in an hour",
    "analysis_config" : {
      "bucket_span" : "1h",
      "detectors" : [
        {
          "detector_description" : "High total sales",
          "function" : "high_sum",
          "field_name" : "taxful_total_price",
          "over_field_name" : "customer_full_name.keyword"
        }
      ],
      "influencers" : [
        "customer_full_name.keyword",
        "category.keyword"
      ]
    },
    "analysis_limits" : {
      "model_memory_limit" : "10mb"
    },
    "data_description" : {
      "time_field" : "order_date",
      "time_format" : "epoch_ms"
    }
  }
}

此示例返回的数据如下：

[
  {
    "order_date" : 1574294659000,
    "category.keyword" : "Men's Clothing",
    "customer_full_name.keyword" : "Sultan Al Benson",
    "taxful_total_price" : 35.96875
  },
  {
    "order_date" : 1574294918000,
    "category.keyword" : [
      "Women's Accessories",
      "Women's Clothing"
    ],
    "customer_full_name.keyword" : "Pia Webb",
    "taxful_total_price" : 83.0
  },
  {
    "order_date" : 1574295782000,
    "category.keyword" : [
      "Women's Accessories",
      "Women's Shoes"
    ],
    "customer_full_name.keyword" : "Brigitte Graham",
    "taxful_total_price" : 72.0
  }
]

重置异常检测作业 API

edit

重置现有的异常检测作业。

请求

edit

POST _ml/anomaly_detectors//_reset

前提条件

edit

需要manage_ml集群权限。此权限包含在machine_learning_admin内置角色中。
在重置作业之前，您必须关闭它。关闭作业时，可以将force设置为true，以避免等待作业完成。请参阅关闭作业。

描述

edit

所有模型状态和结果均已删除。作业已准备好重新开始，就像刚刚创建一样。

目前无法使用通配符或逗号分隔列表重置多个作业。

路径参数

edit

<job_id>: (必需, 字符串) 异常检测作业的标识符。

查询参数

edit

wait_for_completion: (可选，布尔值) 指定请求是否应立即返回或等待作业重置完成。默认为 true。
delete_user_annotations: (可选，布尔值) 指定在重置作业时，是否应删除用户添加的注释以及任何自动生成的注释。默认为 false。

示例

edit

POST _ml/anomaly_detectors/total-requests/_reset

当作业重置时，您会收到以下结果：

{
  "acknowledged": true
}

在下一个示例中，我们异步重置了 total-requests 作业：

POST _ml/anomaly_detectors/total-requests/_reset?wait_for_completion=false

当 wait_for_completion 设置为 false 时，响应包含作业重置任务的ID：

{
  "task": "oTUltX4IQMOUUVeiohTt8A:39"
}

如果您想检查重置任务的状态，请通过引用任务ID使用任务管理。

恢复模型快照 API

edit

恢复到特定快照。

请求

edit

POST _ml/anomaly_detectors//model_snapshots//_revert

先决条件

edit

在恢复到已保存的快照之前，您必须关闭作业。
需要manage_ml集群权限。此权限包含在machine_learning_admin内置角色中。

描述

edit

机器学习功能对异常输入反应迅速，能够在数据中学习新的行为。高度异常的输入会增加模型的方差，而系统则在学习这是否是行为的新步骤变化或一次性事件。如果已知这种异常输入是一次性的，那么可能需要将模型状态重置到此事件之前的时间点。例如，您可能会考虑在黑色星期五或系统严重故障后恢复到保存的快照。

恢复到快照不会改变异常检测作业的data_counts值，这些值不会恢复到之前的状态。

路径参数

edit

<job_id>

(必需, 字符串) 异常检测作业的标识符。

<snapshot_id>

(必需, 字符串) 模型快照的标识符。

您可以将 empty 指定为。恢复到 empty 快照意味着当异常检测作业启动时，它将从头开始学习一个新的模型。

查询参数

edit

delete_intervening_results: (可选，布尔值) 如果为 true，则删除最新结果与回退快照时间之间时间段内的结果。它还会将模型重置为接受该时间段内的记录。默认值为 false。

如果您选择在还原快照时不删除中间结果，作业将不接受比当前时间更早的输入数据。如果您想重新发送数据，请删除中间结果。

请求体

edit

您还可以在请求体中指定delete_intervening_results查询参数。

示例

edit

POST _ml/anomaly_detectors/low_request_rate/model_snapshots/1637092688/_revert
{
  "delete_intervening_results": true
}

当操作完成时，您将收到以下结果：

{
  "model" : {
    "job_id" : "low_request_rate",
    "min_version" : "7.11.0",
    "timestamp" : 1637092688000,
    "description" : "State persisted due to job close at 2021-11-16T19:58:08+0000",
    "snapshot_id" : "1637092688",
    "snapshot_doc_count" : 1,
    "model_size_stats" : {
      "job_id" : "low_request_rate",
      "result_type" : "model_size_stats",
      "model_bytes" : 45200,
      "peak_model_bytes" : 101552,
      "model_bytes_exceeded" : 0,
      "model_bytes_memory_limit" : 11534336,
      "total_by_field_count" : 3,
      "total_over_field_count" : 0,
      "total_partition_field_count" : 2,
      "bucket_allocation_failures_count" : 0,
      "memory_status" : "ok",
      "assignment_memory_basis" : "current_model_bytes",
      "categorized_doc_count" : 0,
      "total_category_count" : 0,
      "frequent_category_count" : 0,
      "rare_category_count" : 0,
      "dead_category_count" : 0,
      "failed_category_count" : 0,
      "categorization_status" : "ok",
      "log_time" : 1637092688530,
      "timestamp" : 1641495600000
    },
    "latest_record_time_stamp" : 1641502169000,
    "latest_result_time_stamp" : 1641495600000,
    "retain" : false
  }
}

有关这些属性的描述，请参阅获取模型快照 API。

启动数据流 API

edit

启动一个或多个数据流。

请求

edit

POST _ml/datafeeds//_start

先决条件

edit

在启动数据馈送之前，异常检测作业必须处于开启状态。否则，会发生错误。
需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

必须启动数据馈送才能从 Elasticsearch 检索数据。数据馈送可以在其生命周期内多次启动和停止。

如果你重新启动一个已停止的数据流，默认情况下它将继续处理输入数据，从停止后的下一毫秒开始。如果在停止和启动之间为该确切毫秒索引了新数据，它将被忽略。

当启用了Elasticsearch安全功能时，您的数据馈送会记住最后一位创建或更新它的用户在创建/更新时所拥有的角色，并使用这些相同的角色运行查询。如果您在创建或更新数据馈送时提供了二次授权头，则将使用这些凭据。

路径参数

edit

<feed_id>: (必需，字符串) 一个唯一标识数据流的数字字符串。此标识符可以包含小写字母数字字符（a-z 和 0-9）、连字符和下划线。它必须以字母数字字符开头和结尾。

查询参数

edit

end

(可选，字符串) 数据馈送应结束的时间，可以使用以下格式之一来指定：

ISO 8601格式带毫秒，例如 2017-01-22T06:00:00.000Z
ISO 8601格式不带毫秒，例如 2017-01-22T06:00:00+00:00
自纪元以来的毫秒数，例如 1485061200000

使用ISO 8601格式之一的日期时间参数必须具有时区标识符，其中Z被接受为UTC时间的缩写。

当需要一个URL时（例如，在浏览器中），时间区标识符中使用的+必须编码为%2B。

此值是排他的。如果您未指定结束时间，数据馈送将连续运行。

start

(可选，字符串) 数据馈送应开始的时间，可以使用与end参数相同的格式来指定。此值是包含的。

如果不指定开始时间，并且数据馈送与一个新的异常检测作业相关联，分析将从最早的可用数据时间开始。

如果您重新启动已停止的数据馈送并指定一个早于最新处理记录时间戳的start值，数据馈送将从最新处理记录时间戳后的1毫秒继续。

timeout

(可选，时间) 指定数据馈送开始前的等待时间。默认值是20秒。

请求体

edit

您还可以在请求体中指定查询参数（例如 end 和 start）。

响应体

edit

node: (字符串) 数据馈送启动的节点的ID。如果数据馈送被允许延迟打开且尚未分配给节点，则此值为空字符串。
started: (布尔值) 对于成功的响应，此值始终为 true。在失败的情况下，将返回异常。

示例

edit

POST _ml/datafeeds/datafeed-low_request_rate/_start
{
  "start": "2019-04-07T18:22:16Z"
}

当数据馈送启动时，您会收到以下结果：

{
  "started" : true,
  "node" : "node-1"
}

停止数据流 API

edit

停止一个或多个数据馈送。

请求

edit

POST _ml/datafeeds//_stop

POST _ml/datafeeds/,/_stop

POST _ml/datafeeds/_all/_stop

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

一个停止的数据馈送将不再从Elasticsearch中检索数据。数据馈送可以在其生命周期内多次启动和停止。

路径参数

edit

<feed_id>: (必需，字符串) 数据流的标识符。您可以通过使用逗号分隔的数据流列表或通配符表达式在单个API请求中停止多个数据流。您可以通过使用_all或指定*作为标识符来关闭所有数据流。

查询参数

edit

allow_no_match

(可选, 布尔值) 指定在请求时执行的操作：

包含通配符表达式且没有匹配的数据馈送。
包含 _all 字符串或没有标识符且没有匹配项。
包含通配符表达式且只有部分匹配。

force

(可选，布尔值) 如果为 true，则强制停止数据馈送。

timeout

(可选，时间) 指定数据馈送停止前等待的时间量。默认值是 20 秒。

请求体

edit

您还可以在请求体中指定查询参数（例如 allow_no_match 和 force）。

响应代码

edit

404 (Missing resources): 如果 allow_no_match 是 false，此代码表示没有与请求匹配的资源，或者只有部分匹配的请求。

示例

edit

POST _ml/datafeeds/datafeed-low_request_rate/_stop
{
  "timeout": "30s"
}

当数据馈送停止时，您会收到以下结果：

{
  "stopped": true
}

更新数据流 API

edit

更新数据流的某些属性。

请求

edit

POST _ml/datafeeds//_update

前提条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

您只能在数据馈送停止时更新数据馈送属性。然而，可以在不关闭关联作业的情况下停止数据馈送、更新其属性并重新启动它。

当启用了Elasticsearch安全功能时，您的数据馈送会记住更新时更新它的用户所拥有的角色，并使用这些相同的角色运行查询。如果您提供了二次授权头，则将使用这些凭证。

路径参数

edit

<feed_id>: (必需，字符串) 一个唯一标识数据流的数字字符串。此标识符可以包含小写字母数字字符（a-z 和 0-9）、连字符和下划线。它必须以字母数字字符开头和结尾。

查询参数

edit

allow_no_indices

(可选，布尔值) 如果为 true，则通配符索引表达式解析为无具体索引时将被忽略。这包括 _all 字符串或未指定索引的情况。默认为 true。

expand_wildcards

all: 匹配任何数据流或索引，包括隐藏的数据流和索引。
open: 匹配开放的、非隐藏的索引。同时也匹配任何非隐藏的数据流。
closed: 匹配关闭的、非隐藏的索引。同时也匹配任何非隐藏的数据流。数据流不能被关闭。
hidden: 匹配隐藏的数据流和隐藏的索引。必须与 open、 closed 或两者结合使用。
none: 不接受通配符模式。

默认为 open。

ignore_throttled

(可选，布尔值) 如果为 true，冻结时会忽略具体的、扩展的或别名的索引。默认为 true。

[7.16.0] 在7.16.0中已弃用。

ignore_unavailable

(可选，布尔值) 如果为true，则忽略不可用的索引（缺失或关闭）。默认为false。

请求体

edit

以下属性可以在数据馈送创建后进行更新：

aggregations

(可选, 对象) 如果设置，数据馈送执行聚合搜索。聚合的支持是有限的，并且应该仅用于低基数数据。更多信息，请参阅聚合数据以加快性能。

chunking_config

Properties of chunking_config

mode

(字符串) 有三种可用模式：

auto: 块大小是动态计算的。这是默认值，并且在数据馈送不使用聚合时推荐使用。
manual: 根据指定的time_span应用分块。当数据馈送使用聚合时使用此模式。
off: 不应用分块。

time_span

(时间单位) 每个搜索将查询的时间跨度。此设置仅在模式设置为manual时适用。例如：3h。

delayed_data_check_config

(可选, 对象) 指定数据馈送是否检查缺失数据以及窗口的大小。例如：{"enabled": true, "check_window": "1h"}。

此检查仅在实时数据馈送上运行。

Properties of delayed_data_check_config

check_window: (时间单位) 搜索延迟数据的窗口时间。此窗口时间以最新的最终化桶结束。它默认为null，这会在实时数据馈送运行时计算适当的check_window。特别是，默认的check_window跨度计算基于2h或8 * bucket_span的最大值。
enabled: (布尔值) 指定数据馈送是否定期检查延迟数据。默认为true。

frequency

indices

(可选, 数组) 一个索引名称的数组。支持通配符。例如: ["it_ops_metrics", "server*"]。

如果任何索引位于远程集群中，则机器学习节点需要具有remote_cluster_client角色。

indices_options

(可选, 对象) 指定在搜索期间使用的索引扩展选项。

例如：

{
   "expand_wildcards": ["all"],
   "ignore_unavailable": true,
   "allow_no_indices": "false",
   "ignore_throttled": true
}

有关这些选项的更多信息，请参阅多目标语法。

max_empty_searches

(可选，整数) 如果一个实时数据馈送从未见过任何数据（包括在任何初始训练期间），那么它将在返回无文档的实时搜索达到此数量后自动停止自身并关闭其关联的作业。换句话说，它将在实时操作中停止 frequency 乘以 max_empty_searches 次。如果未设置，则没有结束时间且未见任何数据的数据馈送将保持启动状态，直到明确停止。默认情况下，此设置未设置。

特殊值 -1 取消此设置。

query

(可选, 对象) Elasticsearch 查询领域特定语言 (DSL)。此值对应于 Elasticsearch 搜索 POST 请求体中的 query 对象。所有 Elasticsearch 支持的选项都可以使用，因为这个对象是原样传递给 Elasticsearch 的。默认情况下，此属性具有以下值: {"match_all": {"boost": 1}}。

如果你更改查询，分析的数据也会随之改变。因此，学习所需的时间可能会很长，结果的可理解性也无法预测。如果你想对源数据进行重大修改，我们建议你克隆它并创建一个包含修改内容的第二个作业。让两者并行运行，当你对其中一个作业的结果满意时，再关闭另一个。

query_delay

runtime_mappings

(可选, 对象) 指定数据馈送搜索的运行时字段。

例如：

{
  "day_of_week": {
    "type": "keyword",
    "script": {
      "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ENGLISH))"
    }
  }
}

script_fields

scroll_size

示例

edit

POST _ml/datafeeds/datafeed-test-job/_update
{
  "query": {
    "term": {
      "geo.src": "US"
    }
  }
}

当数据源更新时，您会收到包含更新值的完整数据源配置：

{
  "datafeed_id" : "datafeed-test-job",
  "job_id" : "test-job",
  "authorization" : {
    "roles" : [
      "superuser"
    ]
  },
  "query_delay" : "64489ms",
  "chunking_config" : {
    "mode" : "auto"
  },
  "indices_options" : {
    "expand_wildcards" : [
      "open"
    ],
    "ignore_unavailable" : false,
    "allow_no_indices" : true,
    "ignore_throttled" : true
  },
  "query" : {
    "term" : {
      "geo.src" : "US"
    }
  },
  "indices" : [
    "kibana_sample_data_logs"
  ],
  "scroll_size" : 1000,
  "delayed_data_check_config" : {
    "enabled" : true
  }
}

更新过滤器 API

edit

更新过滤器的描述，添加项目或移除项目。

请求

edit

POST _ml/filters//_update

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

路径参数

edit

<filter_id>: (必需, 字符串) 一个唯一标识过滤器的字符串。

请求体

edit

add_items: （可选，字符串数组）要添加到过滤器中的项目。
description: (可选，字符串) 过滤器的描述。
remove_items: (可选，字符串数组) 要从过滤器中移除的项目。

示例

edit

POST _ml/filters/safe_domains/_update
{
  "description": "Updated list of domains",
  "add_items": ["*.myorg.com"],
  "remove_items": ["wikipedia.org"]
}

API返回以下结果：

{
  "filter_id": "safe_domains",
  "description": "Updated list of domains",
  "items": ["*.google.com", "*.myorg.com"]
}

更新异常检测作业 API

edit

更新异常检测作业的某些属性。

请求

edit

POST _ml/anomaly_detectors//_update

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

路径参数

edit

<job_id>: (必需, 字符串) 异常检测作业的标识符。

请求体

edit

以下属性可以在作业创建后进行更新：

allow_lazy_open

(布尔值) 高级配置选项。指定当没有足够的机器学习节点容量立即将其分配到节点时，此作业是否可以打开。默认值为false；如果找不到具有运行作业容量的机器学习节点，打开异常检测作业 API将返回一个错误。然而，这也受集群范围的xpack.ml.max_lazy_ml_nodes设置的限制；请参阅高级机器学习设置。如果此选项设置为true，打开异常检测作业 API不会返回错误，并且作业会在opening状态下等待，直到有足够的机器学习节点容量可用。

如果您在更新时作业是开放的，您必须停止数据馈送，关闭作业，然后重新打开作业并重新启动数据馈送，以使更改生效。

analysis_limits

您只能在作业关闭时更新analysis_limits。

Properties of analysis_limits

model_memory_limit

从 Elasticsearch 8.10.0 开始，使用了一个新的版本号来跟踪机器学习插件中的配置和状态变化。这个新的版本号与产品版本解耦，并将独立递增。

You cannot decrease the model_memory_limit value below the current usage. To determine the current usage, refer to the model_bytes value in the get job stats API.
If the memory_status property in the model_size_stats object has a value of hard_limit, this means that it was unable to process some data. You might want to re-run the job with an increased model_memory_limit.

background_persist_interval

(时间单位) 高级配置选项。每次定期持久化模型之间的时间间隔。默认值是3到4小时之间的随机值，这样可以避免所有作业在完全相同的时间进行持久化。允许的最小值是1小时。

对于非常大的模型（几个GB），持久化可能需要10-20分钟，因此不要将background_persist_interval值设置得太低。

如果您在更新时作业是开放的，您必须停止数据馈送，关闭作业，然后重新打开作业并重新启动数据馈送，以使更改生效。

custom_settings

(对象) 高级配置选项。包含有关作业的自定义元数据。例如，它可以包含自定义URL信息，如在向机器学习结果添加自定义URL中所示。

daily_model_snapshot_retention_after_days

(长) 高级配置选项，影响此作业的旧模型快照的自动删除。它指定了一个时间段（以天为单位），在此时间段后，每天仅保留第一个快照。此时间段相对于此作业的最新快照的时间戳。有效值范围从 0 到 model_snapshot_retention_days。对于新作业，默认值为 1。对于在版本 7.8.0 之前创建的作业，默认值与 model_snapshot_retention_days 匹配。有关更多信息，请参阅模型快照。

从 Elasticsearch 8.10.0 开始，使用了一个新的版本号来跟踪机器学习插件中的配置和状态变化。这个新的版本号与产品版本解耦，并将独立递增。

description

(字符串) 作业的描述。

detectors

(数组) 一个检测器更新对象的数组。

Properties of detectors

custom_rules

(数组) 一个自定义规则对象的数组，使您能够自定义检测器的工作方式。例如，规则可以指示检测器在何种条件下应跳过结果。Kibana将自定义规则称为作业规则。更多示例，请参见使用自定义规则自定义检测器。

Properties of custom_rules

actions

(数组) 当规则适用时要触发的操作集合。如果指定了多个操作，所有操作的效果将合并。可用的操作包括：

skip_result: 结果将不会被创建。这是默认值。除非您也指定了 skip_model_update，模型将照常更新相应的系列值。
skip_model_update: 该系列的值将不会用于更新模型。除非您也指定了 skip_result，结果将照常创建。此操作适用于某些值预期会持续异常且它们以负面影响其余结果的方式影响模型的情况。
force_time_shift: 此操作将按指定量在异常检测器内移动时间。这很有用，例如，可以快速适应已知提前的夏令时事件。此操作需要在 params 对象中指定 force_time_shift 参数。

params

(对象) 一组参数对象，用于自定义在自定义规则中定义的操作 actions 数组。可用的参数（取决于指定的操作）包括： force_time_shift。

Properties of params

force_time_shift: (object) 将 time_shift_amount 设置为要移动时间的带符号秒数。

conditions

(数组) 一个可选的数值条件数组，当规则适用时。规则必须要么有一个非空的范围，要么至少有一个条件。多个条件通过逻辑AND组合在一起。一个条件具有以下属性：

Properties of conditions

applies_to: (string) 指定条件适用的结果属性。可用的选项是 actual、typical、diff_from_typical、time。如果您的检测器使用 lat_long、metric、rare 或 freq_rare 函数，您只能指定适用于 time 的条件。
operator: (string) 指定条件运算符。可用的选项是 gt（大于）、 gte（大于或等于）、lt（小于）和 lte（小于或等于）。
value: (double) 使用 operator 与 applies_to 字段进行比较的值。

scope

(对象) 规则适用的可选系列范围。规则必须具有非空范围或至少一个条件。默认情况下，范围包括所有系列。范围允许用于在by_field_name、over_field_name或partition_field_name中指定的任何字段。要为字段添加范围，请将字段名称作为键添加到范围对象中，并将其值设置为具有以下属性的对象：

Properties of scope

filter_id: (string) 要使用的过滤器的ID。
filter_type: (string) 可以是 include（规则适用于过滤器中的值）或 exclude（规则适用于过滤器外的值）。默认为 include。

description

(string) 检测器的描述。例如，低事件率。

detector_index

(整数) 检测器的唯一标识符。此标识符基于检测器在 analysis_config 中的顺序，从零开始。

如果您想更新特定检测器，您必须使用此标识符。但是，您不能更改检测器的 detector_index 值。

groups

(字符串数组) 作业组的列表。一个作业可以不属于任何组，也可以属于多个组。

model_plot_config

(对象) 此高级配置选项存储模型信息以及结果。它提供了更详细的异常检测视图。

如果您启用模型绘图，它可能会显著增加系统的性能开销；对于包含许多实体的任务来说，这是不可行的。

模型绘图配置可以在创建作业时或稍后更新时进行配置。如果遇到性能问题，必须禁用它。

Properties of model_plot_config

annotations_enabled: (布尔值) 如果为真，则启用计算和存储正在分析的每个实体的模型变化注释。默认为enabled。
enabled: (布尔值) 如果为真，则启用计算和存储正在分析的每个实体的模型边界。默认情况下，此功能未启用。
terms: [预览] 此功能处于技术预览阶段，可能会在未来的版本中进行更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 (字符串) 将数据收集限制为此逗号分隔的分区或字段值列表。如果未指定术语或为空字符串，则不应用过滤。例如，"CPU,NetworkIn,DiskWrites"。不支持通配符。使用单指标查看器时，只能查看指定的terms。

model_prune_window

(时间单位) 高级配置选项。影响对在给定时间内未更新的模型的修剪。值必须设置为bucket_span的倍数。如果设置过低，可能会从模型中删除重要信息。通常，设置为30d或更长。如果未设置，仅当模型内存状态达到软限制或硬限制时才会进行模型修剪。对于在8.1及以后创建的作业，默认值是30d或20倍bucket_span中的较大者。

model_snapshot_retention_days

(长整型) 高级配置选项，影响此作业的旧模型快照的自动删除。它指定快照保留的最大时间（以天为单位）。此时间段相对于此作业的最新快照的时间戳。默认值为 10，这意味着比最新快照早十天的快照将被删除。有关更多信息，请参阅模型快照。

per_partition_categorization

(对象) 与分区字段交互的分类设置。

Properties of per_partition_categorization

enabled: (布尔值) 要启用此设置，您还必须在每个使用关键字 mlcategory 的检测器中将 partition_field_name 属性设置为相同的值。否则，作业创建将失败。
stop_on_warn: (布尔值) 此设置仅在启用按分区分类时才能设置为 true。如果为 true，则在分类状态变为 warn 的分区中，分类和后续异常检测都将停止。此设置使得在某些分区中分类效果良好而在其他分区中效果不佳的情况下，作业仍然可行；您不会在分类效果不佳的分区中永远付出分类不良的代价。

renormalization_window_days: (长整型) 高级配置选项。调整分数所依据的时间段，因为看到了新数据。默认值是 30 天或 100 bucket_spans 中较长的一个。

如果您在更新时作业是开放的，您必须停止数据馈送，关闭作业，然后重新打开作业并重新启动数据馈送，以使更改生效。

results_retention_days: (长整型) 高级配置选项。结果保留的时间段（以天为单位）。年龄是相对于最新桶结果的时间戳计算的。如果此属性具有非空值，则在每天 00:30（服务器时间），比最新桶结果早指定天数的结果将从 Elasticsearch 中删除。默认值为 null，这意味着所有结果都将保留。系统生成的注释也计为保留目的的结果；它们在结果之后相同天数后删除。用户添加的注释将永久保留。

示例

edit

POST _ml/anomaly_detectors/low_request_rate/_update
{
  "description":"An updated job",
  "detectors": {
    "detector_index": 0,
    "description": "An updated detector description"
  },
  "groups": ["kibana_sample_data","kibana_sample_web_logs"],
  "model_plot_config": {
    "enabled": true
  },
  "renormalization_window_days": 30,
  "background_persist_interval": "2h",
  "model_snapshot_retention_days": 7,
  "results_retention_days": 60
}

当异常检测作业更新时，您会收到作业配置信息的摘要，包括更新的属性值。例如：

{
  "job_id" : "low_request_rate",
  "job_type" : "anomaly_detector",
  "job_version" : "8.4.0",
  "create_time" : 1656105950893,
  "finished_time" : 1656105965744,
  "model_snapshot_id" : "1656105964",
  "custom_settings" : {
    "created_by" : "ml-module-sample",
    "custom_urls" : [
      {
        "url_name" : "Raw data",
        "url_value" : "discover#/?_g=(time:(from:'$earliest$',mode:absolute,to:'$latest$'))&_a=(index:'90943e30-9a47-11e8-b64d-95841ca0b247')"
      },
      {
        "url_name" : "Data dashboard",
        "url_value" : "dashboards#/view/edf84fe0-e1a0-11e7-b6d5-4dc382ef7f5b?_g=(time:(from:'$earliest$',mode:absolute,to:'$latest$'))&_a=(filters:!(),query:(language:kuery,query:''))"
      }
    ]
  },
  "groups" : [
    "kibana_sample_data",
    "kibana_sample_web_logs"
  ],
  "description" : "An updated job",
  "analysis_config" : {
    "bucket_span" : "1h",
    "summary_count_field_name" : "doc_count",
    "detectors" : [
      {
        "detector_description" : "An updated detector description",
        "function" : "low_count",
        "detector_index" : 0
      }
    ],
    "influencers" : [ ],
    "model_prune_window" : "30d"
  },
  "analysis_limits" : {
    "model_memory_limit" : "11mb",
    "categorization_examples_limit" : 4
  },
  "data_description" : {
    "time_field" : "timestamp",
    "time_format" : "epoch_ms"
  },
  "model_plot_config" : {
    "enabled" : true,
    "annotations_enabled" : true
  },
  "renormalization_window_days" : 30,
  "background_persist_interval" : "2h",
  "model_snapshot_retention_days" : 7,
  "daily_model_snapshot_retention_after_days" : 1,
  "results_retention_days" : 60,
  "results_index_name" : "custom-low_request_rate",
  "allow_lazy_open" : false
}

更新模型快照 API

edit

更新快照的某些属性。

请求

edit

POST _ml/anomaly_detectors//model_snapshots//_update

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

路径参数

edit

<job_id>: (必需, 字符串) 异常检测作业的标识符。
<snapshot_id>: (必需，字符串) 模型快照的标识符。

请求体

edit

以下属性可以在模型快照创建后进行更新：

description: (可选，字符串) 模型快照的描述。
retain: (可选, 布尔值) 如果为true，此快照在超过model_snapshot_retention_days的自动清理过程中不会被删除。然而，当作业被删除时，此快照将被删除。默认值为false。

示例

edit

POST
_ml/anomaly_detectors/it_ops_new_logs/model_snapshots/1491852978/_update
{
  "description": "Snapshot 1",
  "retain": true
}

当快照更新时，您会收到以下结果：

{
  "acknowledged": true,
  "model": {
    "job_id": "it_ops_new_logs",
    "timestamp": 1491852978000,
    "description": "Snapshot 1",
...
    "retain": true
  }
}

升级模型快照 API

edit

将异常检测模型快照升级到最新主要版本。

从 Elasticsearch 8.10.0 开始，使用了一个新的版本号来跟踪机器学习插件中的配置和状态变化。这个新的版本号与产品版本解耦，并将独立递增。

请求

edit

POST _ml/anomaly_detectors//model_snapshots//_upgrade

前提条件

edit

需要manage_ml集群权限。此权限包含在machine_learning_admin内置角色中。
升级的快照必须与前一个主版本匹配。
升级的快照不能是当前的异常检测作业快照。

描述

edit

随着时间的推移，旧的快照格式会被弃用并移除。异常检测作业仅支持来自当前或上一个主要版本的快照。

此API提供了一种将快照升级到当前主要版本的方法。这有助于为集群升级到下一个主要版本做准备。

每个异常检测作业一次只能升级一个快照，并且升级的快照不能是当前异常检测作业的快照。

路径参数

edit

<job_id>: (必需, 字符串) 异常检测作业的标识符。
<snapshot_id>: (必需，字符串) 模型快照的标识符。

查询参数

edit

timeout: (可选，时间) 控制等待请求完成的时间。默认值为30分钟。
wait_for_completion: (可选，布尔值) 当为 true 时，API 在升级完成之前不会响应。否则，它会在升级任务分配给节点后立即响应。默认为 false。

响应体

edit

node: (字符串) 如果升级任务仍在运行，则为分配给该任务的节点的ID。
completed: (布尔值) 当为真时，表示任务已完成。当为假时，表示任务仍在运行。

示例

edit

POST _ml/anomaly_detectors/low_request_rate/model_snapshots/1828371/_upgrade?timeout=45m&wait_for_completion=true

当快照升级开始时，您会收到以下结果：

{
  "completed" : false,
  "node" : "node-1"
}

« Machine learning APIs Machine learning data frame analytics APIs »