異常検出ジョブ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
      • （文字列）利用可能なモードは3つあります：
      • 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
    • （オプション、オブジェクト）検索中に使用されるインデックス拡張オプションを指定します。
      例えば：
      1. {
      2. "expand_wildcards": ["all"],
      3. "ignore_unavailable": true,
      4. "allow_no_indices": "false",
      5. "ignore_throttled": true
      6. }
      これらのオプションの詳細については、マルチターゲット構文を参照してください。
    • job_id
    • （必須、文字列）異常検出ジョブの識別子。
    • max_empty_searches
    • （オプション、整数）リアルタイムデータフィードがデータを一度も見たことがない場合（初期トレーニング期間中を含む）、この数のリアルタイム検索がドキュメントを返さないと、自動的に停止し、関連するジョブを閉じます。言い換えれば、frequency 回のリアルタイム操作の後に停止します。設定されていない場合、データフィードは終了時間がなく、データが見つからない場合は明示的に停止されるまで開始されたままになります。デフォルトでは、この設定は設定されていません。
    • 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
    • （オプション、オブジェクト）データフィード検索のランタイムフィールドを指定します。
      例えば：
      1. {
      2. "day_of_week": {
      3. "type": "keyword",
      4. "script": {
      5. "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ENGLISH))"
      6. }
      7. }
      8. }
    1. -  （オプション、オブジェクト）カスタム式を評価し、スクリプトフィールドをデータフィードに返すスクリプトを指定します。ジョブ内の検出器構成オブジェクトには、これらのスクリプトフィールドを使用する関数が含まれる場合があります。詳細については、[スクリプトフィールドを使用したデータの変換](https://www.elastic.co/guide/en/machine-learning/8.15/ml-configuring-transform.html)および[スクリプトフィールド](1ca72727e8d3ebf9.md#script-fields)を参照してください。  
    2. -   `````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 の場合、このコードはリクエストに一致するリソースがないか、リクエストに対して部分一致のみがあることを示します。

例

Python

  1. resp = client.ml.get_jobs(
  2.    job_id="high_sum_total_sales",
  3. )
  4. print(resp)

Ruby

  1. response = client.ml.get_jobs(
  2.   job_id: 'high_sum_total_sales'
  3. )
  4. puts response

Js

  1. const response = await client.ml.getJobs({
  2.   job_id: "high_sum_total_sales",
  3. });
  4. console.log(response);

コンソール

  1. GET _ml/anomaly_detectors/high_sum_total_sales

APIは次の結果を返します：

Js

  1. {
  2.   "count": 1,
  3.   "jobs": [
  4.    {
  5.    "job_id" : "high_sum_total_sales",
  6.    "job_type" : "anomaly_detector",
  7.    "job_version" : "8.4.0",
  8.    "create_time" : 1655852735889,
  9.    "finished_time" : 1655852745980,
  10.    "model_snapshot_id" : "1575402237",
  11.    "custom_settings" : {
  12.    "created_by" : "ml-module-sample",
  13.    ...
  14.    },
  15.    "datafeed_config" : {
  16.    "datafeed_id" : "datafeed-high_sum_total_sales",
  17.    "job_id" : "high_sum_total_sales",
  18.    "authorization" : {
  19.    "roles" : [
  20.    "superuser"
  21.    ]
  22.    },
  23.    "query_delay" : "93169ms",
  24.    "chunking_config" : {
  25.    "mode" : "auto"
  26.    },
  27.    "indices_options" : {
  28.    "expand_wildcards" : [
  29.    "open"
  30.    ],
  31.    "ignore_unavailable" : false,
  32.    "allow_no_indices" : true,
  33.    "ignore_throttled" : true
  34.    },
  35.    "query" : {
  36.    "bool" : {
  37.    "filter" : [
  38.    {
  39.    "term" : {
  40.    "event.dataset" : "sample_ecommerce"
  41.    }
  42.    }
  43.    ]
  44.    }
  45.    },
  46.    "indices" : [
  47.    "kibana_sample_data_ecommerce"
  48.    ],
  49.    "scroll_size" : 1000,
  50.    "delayed_data_check_config" : {
  51.    "enabled" : true
  52.    }
  53.    },
  54.    "groups" : [
  55.    "kibana_sample_data",
  56.    "kibana_sample_ecommerce"
  57.    ],
  58.    "description" : "Find customers spending an unusually high amount in an hour",
  59.    "analysis_config" : {
  60.    "bucket_span" : "1h",
  61.    "detectors" : [
  62.    {
  63.    "detector_description" : "High total sales",
  64.    "function" : "high_sum",
  65.    "field_name" : "taxful_total_price",
  66.    "over_field_name" : "customer_full_name.keyword",
  67.    "detector_index" : 0
  68.    }
  69.    ],
  70.    "influencers" : [
  71.    "customer_full_name.keyword",
  72.    "category.keyword"
  73.    ],
  74.    "model_prune_window": "30d"
  75.    },
  76.    "analysis_limits" : {
  77.    "model_memory_limit" : "13mb",
  78.    "categorization_examples_limit" : 4
  79.    },
  80.    "data_description" : {
  81.    "time_field" : "order_date",
  82.    "time_format" : "epoch_ms"
  83.    },
  84.    "model_plot_config" : {
  85.    "enabled" : true,
  86.    "annotations_enabled" : true
  87.    },
  88.    "model_snapshot_retention_days" : 10,
  89.    "daily_model_snapshot_retention_after_days" : 1,
  90.    "results_index_name" : "shared",
  91.    "allow_lazy_open" : false
  92.    }
  93.   ]
  94. }