全体バケットAPIの取得

複数の異常検出ジョブのバケット結果を要約した全体バケット結果を取得します。

リクエスト

GET _ml/anomaly_detectors/<job_id>/results/overall_buckets

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

GET _ml/anomaly_detectors/_all/results/overall_buckets

前提条件

monitor_ml クラスター権限が必要です。この権限は machine_learning_user ビルトインロールに含まれています。

説明

デフォルトでは、全体バケットは指定された異常検出ジョブの最大バケットスパンと同じスパンを持ちます。その動作をオーバーライドするには、オプションの 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 になります。

パスパラメータ

  • <job_id>
  • （必須、文字列）異常検出ジョブの識別子。ジョブ識別子、グループ名、カンマ区切りのジョブまたはグループのリスト、またはワイルドカード式であることができます。
    _all を使用するか、* をジョブ識別子として指定することで、すべての異常検出ジョブのバケット結果を要約できます。

クエリパラメータ

  • allow_no_match
  • （オプション、ブール値）リクエスト時の動作を指定します：
    • ワイルドカード式を含み、一致するジョブがない場合。
    • _all 文字列を含むか、識別子がない場合、一致がありません。
    • ワイルドカード式を含み、一部の一致のみがある場合。
      デフォルト値は true で、一致がない場合は空の jobs 配列を返し、一部の一致がある場合は結果のサブセットを返します。このパラメータが false の場合、一致がないか一部の一致のみがあるときにリクエストは 404 ステータスコードを返します。
  • bucket_span
  • （オプション、文字列）全体バケットのスパン。指定された異常検出ジョブの最大バケットスパン以上である必要があります。これはデフォルト値です。
  • end
  • （オプション、文字列）この時刻よりも早いタイムスタンプを持つ全体バケットを返します。デフォルトは -1 で、これは未設定であり、結果は特定のタイムスタンプに制限されません。
  • exclude_interim
  • （オプション、ブール値）true の場合、出力は中間全体バケットを除外します。全体バケットは、全体バケット間隔内のいずれかのジョブバケットが中間である場合、中間です。デフォルトは false で、中間結果が含まれます。
  • overall_score
  • （オプション、倍精度）この値以上の全体スコアを持つ全体バケットを返します。デフォルトは 0.0 です。
  • start
  • （オプション、文字列）この時刻以降のタイムスタンプを持つ全体バケットを返します。デフォルトは -1 で、これは未設定であり、結果は特定のタイムスタンプに制限されません。
  • top_n
  • （オプション、整数）overall_score 計算に使用される上位異常検出ジョブバケットスコアの数。デフォルトは 1 です。

リクエストボディ

リクエストボディ内でクエリパラメータ（allow_no_match や bucket_span など）を指定することもできます。

レスポンスボディ

APIは、次のプロパティを持つ全体バケットオブジェクトの配列を返します：

  • bucket_span
  • （数値）バケットの長さ（秒）。最も長いジョブの bucket_span に一致します。
  • is_interim
  • （ブール値）true の場合、これは中間結果です。言い換えれば、結果は部分的な入力データに基づいて計算されます。
  • jobs
  • （配列）max_anomaly_score ごとのオブジェクトの配列。
  • overall_score
  • （数値）ジョブごとの最大バケット anomaly_score の top_n 平均。
  • result_type
  • （文字列）内部。これは常に overall_bucket に設定されています。
  • timestamp
  • （日付）これらの結果が計算されたバケットの開始時刻。

例

Python

  1. resp = client.ml.get_overall_buckets(
  2.    job_id="job-*",
  3.    overall_score=80,
  4.    start="1403532000000",
  5. )
  6. print(resp)

Ruby

  1. response = client.ml.get_overall_buckets(
  2.   job_id: 'job-*',
  3.   body: {
  4.    overall_score: 80,
  5.    start: '1403532000000'
  6.   }
  7. )
  8. puts response

Js

  1. const response = await client.ml.getOverallBuckets({
  2.   job_id: "job-*",
  3.   overall_score: 80,
  4.   start: 1403532000000,
  5. });
  6. console.log(response);

コンソール

  1. GET _ml/anomaly_detectors/job-*/results/overall_buckets
  2. {
  3.   "overall_score": 80,
  4.   "start": "1403532000000"
  5. }

この例では、APIは指定されたスコアと時間制約に一致する単一の結果を返します。overall_score は最大ジョブスコアで、top_n は指定されていない場合はデフォルトで1になります：

Js

  1. {
  2.   "count": 1,
  3.   "overall_buckets": [
  4.    {
  5.    "timestamp" : 1403532000000,
  6.    "bucket_span" : 3600,
  7.    "overall_score" : 80.0,
  8.    "jobs" : [
  9.    {
  10.    "job_id" : "job-1",
  11.    "max_anomaly_score" : 30.0
  12.    },
  13.    {
  14.    "job_id" : "job-2",
  15.    "max_anomaly_score" : 10.0
  16.    },
  17.    {
  18.    "job_id" : "job-3",
  19.    "max_anomaly_score" : 80.0
  20.    }
  21.    ],
  22.    "is_interim" : false,
  23.    "result_type" : "overall_bucket"
  24.    }
  25.   ]
  26. }

次の例は似ていますが、今回は top_n が 2 に設定されています：

Python

  1. resp = client.ml.get_overall_buckets(
  2.    job_id="job-*",
  3.    top_n=2,
  4.    overall_score=50,
  5.    start="1403532000000",
  6. )
  7. print(resp)

Ruby

  1. response = client.ml.get_overall_buckets(
  2.   job_id: 'job-*',
  3.   body: {
  4.    top_n: 2,
  5.    overall_score: 50,
  6.    start: '1403532000000'
  7.   }
  8. )
  9. puts response

Js

  1. const response = await client.ml.getOverallBuckets({
  2.   job_id: "job-*",
  3.   top_n: 2,
  4.   overall_score: 50,
  5.   start: 1403532000000,
  6. });
  7. console.log(response);

コンソール

  1. GET _ml/anomaly_detectors/job-*/results/overall_buckets
  2. {
  3.   "top_n": 2,
  4.   "overall_score": 50.0,
  5.   "start": "1403532000000"
  6. }

overall_score が現在、上位2つのジョブスコアの平均であることに注意してください：

Js

  1. {
  2.   "count": 1,
  3.   "overall_buckets": [
  4.    {
  5.    "timestamp" : 1403532000000,
  6.    "bucket_span" : 3600,
  7.    "overall_score" : 55.0,
  8.    "jobs" : [
  9.    {
  10.    "job_id" : "job-1",
  11.    "max_anomaly_score" : 30.0
  12.    },
  13.    {
  14.    "job_id" : "job-2",
  15.    "max_anomaly_score" : 10.0
  16.    },
  17.    {
  18.    "job_id" : "job-3",
  19.    "max_anomaly_score" : 80.0
  20.    }
  21.    ],
  22.    "is_interim" : false,
  23.    "result_type" : "overall_bucket"
  24.    }
  25.   ]
  26. }