データフィードを作成（Create datafeeds）

データフィード API の作成

データフィードをインスタンス化します。

リクエスト

PUT _ml/datafeeds/<feed_id>

前提条件

• データフィードを作成する前に、異常検知ジョブを作成する必要があります。
• 次の権限が必要です:
  • クラスター: manage_ml (この権限を付与するのは machine_learning_admin の組み込みロールです)
  • データフィードに設定されたソースインデックス: read

説明

データフィード は、異常検知ジョブによる分析のために Elasticsearch からデータを取得します。各異常検知ジョブには、1 つのデータフィードのみを関連付けることができます。

データフィードには、定義された間隔 (frequency) で実行されるクエリが含まれています。遅延データが懸念される場合は、各間隔に遅延 (query_delay) を追加できます。遅延データの処理 を参照してください。

• Kibana、この API、または 異常検知ジョブ作成 API を使用してデータフィードを作成する必要があります。Elasticsearch インデックス API を使用して .ml-config インデックスに直接データフィードを追加しないでください。Elasticsearch のセキュリティ機能が有効になっている場合、write 権限を .ml-config インデックスにユーザーに与えないでください。
• 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
  • (文字列) 利用可能なモードは 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
• (オプション、オブジェクト) 検索中に使用されるインデックス拡張オプションを指定します。
  例えば:

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

  これらのオプションの詳細については、マルチターゲット構文 を参照してください。
• job_id
• (必須、文字列) 異常検知ジョブの識別子。
• max_empty_searches
• (オプション、整数) リアルタイムデータフィードがデータを一度も見たことがない場合 (初期トレーニング期間中を含む)、この数のリアルタイム検索がドキュメントを返さないと、自動的に停止し、関連するジョブを閉じます。言い換えれば、リアルタイム操作の max_empty_searches 回数の後に停止します。設定されていない場合、データが見えない終了時間のないデータフィードは、明示的に停止されるまで開始されたままになります。デフォルトでは、この設定は設定されていません。
• query
• (オプション、オブジェクト) Elasticsearch クエリドメイン固有言語 (DSL)。この値は、Elasticsearch 検索 POST ボディのクエリオブジェクトに対応します。Elasticsearch によってサポートされるすべてのオプションを使用できます。このオブジェクトは、Elasticsearch にそのまま渡されます。デフォルトでは、このプロパティは次の値を持ちます: {"match_all": {"boost": 1}}。
• query_delay
• (オプション、時間単位) データがクエリされるリアルタイムからの秒数。例えば、午前 10 時 4 分のデータが午前 10 時 6 分まで 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 です。

例

異常検知ジョブのためのデータフィードを作成します (test-job):

Python

resp = client.ml.put_datafeed(
   datafeed_id="datafeed-test-job",
   pretty=True,
   indices=[
   "kibana_sample_data_logs"
   ],
   query={
   "bool": {
   "must": [
   {
   "match_all": {}
   }
   ]
   }
   },
   job_id="test-job",
)
print(resp)

Js

const response = await client.ml.putDatafeed({
  datafeed_id: "datafeed-test-job",
  pretty: "true",
  indices: ["kibana_sample_data_logs"],
  query: {
   bool: {
   must: [
   {
   match_all: {},
   },
   ],
   },
  },
  job_id: "test-job",
});
console.log(response);

コンソール

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
  }
}