› › ›

获取异常检测作业 API

编辑

获取异常检测作业 API编辑

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

请求编辑

GET _ml/anomaly_detectors/<job_id>

GET _ml/anomaly_detectors/<job_id>,<job_id>

GET _ml/anomaly_detectors/

GET _ml/anomaly_detectors/_all

先决条件编辑

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

描述编辑

此 API 最多返回 10,000 个作业。

路径参数编辑

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

查询参数编辑

allow_no_match

(可选，布尔值) 指定当请求时该怎么做

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

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

exclude_generated

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

响应主体编辑

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

blocked

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

blocked 的属性

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

create_time

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

datafeed_config

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

datafeed_config 的属性

authorization

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

authorization 的属性

api_key

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

api_key 的属性

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

roles

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

service_account

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

datafeed_id

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

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 的数据可能要到上午 10:06 才能在 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。

finished_time

(字符串) 如果作业已关闭或失败，则为作业完成的时间，否则为 null。此属性仅供参考；您无法更改其值。

job_type

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

job_version

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

从 Elasticsearch 8.10.0 开始，使用新的版本号来跟踪机器学习插件中的配置和状态更改。这个新的版本号与产品版本无关，并且会独立递增。 job_version 值表示新的版本号。

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

响应代码编辑

404 (缺少资源): 如果 allow_no_match 为 false，则此代码表示没有与请求匹配的资源，或者请求仅部分匹配。

示例编辑

response = client.ml.get_jobs(
  job_id: 'high_sum_total_sales'
)
puts response

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 获取异常检测作业统计信息 API »