« 创建日历 API 创建过滤器 API »
Elastic 文档 ›Elasticsearch 指南 [8.14] ›REST API ›机器学习异常检测 API

创建数据馈送 API

编辑

创建数据馈送 API编辑

实例化数据馈送。

请求编辑

PUT _ml/datafeeds/<feed_id>

先决条件编辑

  • 您必须先创建异常检测作业，然后才能创建数据馈送。

  • 需要以下权限

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

描述编辑

数据馈送 从 Elasticsearch 检索数据，供异常检测作业分析。您只能将一个数据馈送关联到每个异常检测作业。

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

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

路径参数编辑

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

查询参数编辑

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。

请求正文编辑

aggregations
（可选，对象）如果设置，数据馈送将执行聚合搜索。对聚合的支持有限，并且应该仅用于低基数数据。有关更多信息，请参阅聚合数据以提高性能。
chunking_config

（可选，对象）数据馈送可能需要在很长一段时间内（几个月或几年）进行搜索。此搜索被拆分为时间块，以确保对 Elasticsearch 的负载得到管理。分块配置控制如何计算这些时间块的大小，并且是一个高级配置选项。

chunking_config 的属性
mode

（字符串）有三种可用模式

  • auto：动态计算块大小。这是数据馈送不使用聚合时的默认值和建议值。
  • manual：根据指定的 time_span 应用分块。当数据馈送使用聚合时，请使用此模式。
  • off：不应用分块。
time_span
（时间单位）每次搜索将查询的时间跨度。此设置仅在模式设置为 manual 时适用。例如：3h。
delayed_data_check_config

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

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

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

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 后停止。如果未设置，则没有结束时间且看不到数据的 datafeed 将保持启动状态，直到显式停止。默认情况下，未设置此设置。
query
（可选，对象）Elasticsearch 查询领域特定语言 (DSL)。此值对应于 Elasticsearch 搜索 POST 正文中的查询对象。支持 Elasticsearch 的所有选项都可以使用，因为此对象会逐字传递给 Elasticsearch。默认情况下，此属性具有以下值：{"match_all": {"boost": 1}}。
query_delay
（可选，时间单位）查询数据落后于实时的时间（以秒为单位）。例如，如果 10:04 AM 的数据在 10:06 AM 之前可能无法在 Elasticsearch 中搜索，请将此属性设置为 120 秒。默认值是在 60s 和 120s 之间随机选择的。当同一节点上有多个作业运行时，这种随机性可以提高查询性能。有关更多信息，请参阅处理延迟数据。
runtime_mappings

（可选，对象）指定数据馈送搜索的运行时字段。

例如

{
  "day_of_week": {
    "type": "keyword",
    "script": {
      "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ROOT))"
    }
  }
}
script_fields
（可选，对象）指定用于评估自定义表达式并将脚本字段返回到数据馈送的脚本。作业中的检测器配置对象可以包含使用这些脚本字段的函数。有关更多信息，请参阅使用脚本字段转换数据和脚本字段。
scroll_size
（可选，无符号整数）当数据馈送不使用聚合时，在 Elasticsearch 搜索中使用的 size 参数。默认值为 1000。最大值为 index.max_result_window 的值，默认情况下为 10,000。

示例编辑

为异常检测作业（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 创建过滤器 API »