クエリタスクの送信¶
POST /api/v1/logmine/send_task
概要¶
現在のワークスペースの非同期ログ、またはその他のサポート対象データドメインのテキストクラスタリングタスクを送信します。
呼び出し前の確認と使用手順¶
対象ワークスペースの Key を使用します。routine.defaultAccess または anonymous.snapshotShared のいずれかのエントリ権限が必要です。実際のデータクエリは引き続きデータドメインの権限、インデックス、データアクセスルールによって制限されるため、基本アクセス権限があってもすべてのデータをクエリできるわけではありません。本ページは公開 Body 宣言に基づく呼び出し契約を提供するもので、JSON では targetWorkspaceUUID/targetWorkspaceUUIDs/targetRegion/indexes/docLimit などの制御パラメータは公開されていません。宣言されていない追加パラメータへの依存は推奨しません。送信インターフェースには歴史的な URL 互換のパラメータ取得があり、URL の業務フィールドが同名の JSON 値を上書きしたり、宣言されていないフィールドを補完したりする可能性があります。すべての追加 URL パラメータが拒否されるわけではありませんが、これは安定した拡張契約にはなりません。クライアントは本ページの JSON パラメータのみを使用し、URL の業務パラメータを混在させないでください。
非同期クラスタリングタスクを送信します。元データの書き戻しや変更は行いません。呼び出し前にフィルタ文と実際のフィールドを検証し、できるだけ小さい時間範囲を選択してください。まず送信して taskId を保存し、その後クエリタスク結果の取得を使用して同一ワークスペースでポーリングします。同一リクエストを連続して繰り返し送信する必要はありません。送信後にキャッシュ書き込みが失敗しても、すでにリモートタスクが生成されている可能性があるため、インターフェースの失敗はリモート側がまったく実行されていないことを意味しません。
1 回あたり最大で、サイトの LogmineSet.docLimit 設定(コードのデフォルトは 10000)で指定されたドキュメントを処理し、time の降順でサービスに投入します。本インターフェースではこの上限を変更できません。返却される processingLimit は今回の送信時に保存された設定上限であり、すでに分析された件数ではないため、これによって時間ウィンドウ全体を網羅したことを証明することはできません。クエリ可能なインデックスがない場合はセンチネルの taskId=no_index_list、processingLimit=null を返しますが、実際に完全なスキャンが実行されたことを意味しません。コンテキストキャッシュは 20 分間であるため、速やかにポーリングして結果を保存してください。上流に taskId がない場合、現在のサービスでは再検証されず、HTTP200 でも taskId が null または空値になる可能性があります。これは送信結果の異常と判断し、ポーリングとループ再作成を停止し、traceId を保持して管理者がリモートタスクが生成されたかを照合できるようにしてください。
リクエストヘッダー¶
| パラメータ名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得・入力方法: 対象ワークスペースの API Key 管理から、该当の操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| analysisField | string | Y | 必須文字列。分割後に各項目の両側の空白を除去します。返却される message はこれらのフィールドの値を処理したものになります。lineage ではさらに空フィールド/重複フィールド/バッククォートや制御文字を禁止します。その他のドメインでも重複排除を推奨し、弱い従来の検証に依存しないでください。 null 許可: False 例: message取得・入力方法: 実際のデータスキーマから分析対象のテキストフィールド(例: message)を選択します。最大 3 個まで、半角カンマで連結します。 |
| conditions | string | オプション文字列。デフォルトは空です。非空の query が提供されていない場合にのみ有効で、外側の波括弧は有無どちらでも構いません。 空文字列許可: True null 許可: False 例: `source` IN ["nginx"]取得・入力方法: 実際に収集した Tag/フィールドからフィルタ条件を選択し、クエリ文全体は入力しないでください。 |
|
| highlight | boolean | オプションのブール値。ハイライト情報の生成はクラスタリングクエリサービスに委ねられます。レスポンスにハイライトフィールドが必ず含まれると仮定することはできません。表示時はデータを実行可能な HTML として扱わないよう注意してください。 例: false取得・入力方法: クライアントがハイライトテキストを表示できるかどうかで選択します。デフォルトは false です。 |
|
| namespace | string | 省略時はデフォルトで logging になります。明示的な空文字列はまず公開列挙の検証により 406 で拒否されるため、値は列挙に一致する必要があります。query を提供した場合でもマスキングと lineage 検証に使用されるため、logging と宣言して実際に lineage をクエリすることはできません。 null 許可: False 選択可能な値: ['lineage', 'object', 'object_history', 'custom_object', 'logging', 'keyevent', 'unrecovered_event', 'tracing', 'rum', 'network', 'security', 'backup_log', 'profiling', 'billing'] 例: logging取得・入力方法: クラスタリングのデータソースに応じて公開列挙から選択します。ログは logging、カタログは lineage を使用します。 |
|
| query | string | オプション。非空の場合は完全な文として優先され、conditions は組み込まれません。namespace は引き続き結果のマスキング/ドメイン検証を制御し、analysisField も必須です。文に明示的な時間ウィンドウが含まれる場合、各階層は timeRange と完全に一致する絶対時間式でなければならず、相対ウィンドウで回避することはできません。 null 許可: False 例: L::`*`:(`__docid`, `message`)取得・入力方法: クエリツールで __docid と analysisField に列挙したフィールドを含む DQL を検証します。送信しない場合はシステムが生成します。 |
|
| timeRange | array | オプション配列。常に 2 つの有効な整数ミリ秒を送信することを推奨します。公開宣言では要素の型/長さを制限していません。省略時は空配列となり、後続の前処理やクエリサービスが受け入れる保証はなく、すべての履歴を自動的にクエリするものと解釈しないでください。 null 許可: False 例: [1785427200000, 1785429000000]取得・入力方法: データが存在する開始・終了時刻を Unix ミリ秒で選択します。開始が先、終了が後です。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/logmine/send_task' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"namespace":"logging","analysisField":"message","conditions":"`source` IN [\"nginx\"]","highlight":false,"timeRange":[1785427200000,1785429000000]}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示しています。
| フィールド | タイプ | 説明 |
|---|---|---|
| content.taskId | string または null | 後続のポーリング用識別子。no_index_list はクエリ可能なインデックスが存在しないことを示すローカルセンチネルです。上流にこのキーがない場合は null がそのまま返る可能性があります。空/null はポーリング可能なタスクではありません。 |
| content.processingLimit | integer または null | 今回の作成時の最大処理ドキュメント数。インデックスがない場合は null で、総ヒットドキュメント数とは異なります。 |
| content.timeRange | array | 作成時に渡されたミリ秒の時間範囲であり、サーバー側が自動的に上書きした範囲ではありません。 |
| content.declaration | object | パブリックワークスペース宣言。 |
{
"code": 200,
"content": {
"taskId": "logmine_task_example",
"processingLimit": 10000,
"timeRange": [
1785427200000,
1785429000000
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
タスクサービスでは動的なデータクエリ/権限エラーが発生する可能性があるため、実際の HTTP とエラー本文に従って処理してください。透過マーカーのない 5xx は一律 HTTP500 ft.InternalServerError になるため、すべての上流コードがそのまま透過するとは仮定できません。HTTP200 success=true は今回の送信/ポーリングインターフェースが成功したことのみを示し、非同期クラスタリングが完了したことを示すものではありません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータの解析に失敗しました | パラメータの位置、フィールド名、タイプ、値を確認します。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正します。 |
| 400 | ft.JsonFormatError | POST 本文が JSON オブジェクトではない | 一部の json ファイルの形式エラー | パラメータ表に対応するオブジェクトを送信します。 |
| 406 | ft.InvalidParameter | namespace/analysisField が無効、非空 query のウィンドウ事前検証パーサーが ParserError を報告、ウィンドウが timeRange と一致しない、または lineage 文の混在ドメイン/ネストがサポートされていない | パラメータ {} が無効です |
明確なデータドメイン、1~3 個のフィールド、2 要素のミリ秒時間範囲を確認し、純粋な lineage クエリまたは対応する実際のドメインを使用します。 |
| 400 | ft.LogmineCountExceedsLimit | analysisField をカンマで分割した結果が 3 項目を超える | クラスタリングフィールド数が制限を超えています。最大 3 個までサポートします | クラスタリング対象の 1~3 個のフィールドのみを送信します。末尾のカンマは付けないでください。 |
| 406 | ft.DqlParseError | DQL の解析またはクエリ前処理に失敗 | dql parser の解析に失敗しました: {} | まず DQL の構文と実際のデータドメインを検証してから、文を修正します。 |
| 500 | ft.InternalServerError | タスククエリサービスの 5xx が透過されず一律にラップされた、キャッシュ/データベースのエラー、または上流の構造を解析できない | 内部エラー | traceId を保持します。送信済みリクエストの結果が不明な場合は、直ちにループで重複作成せず、まずタスク状態を確認するか、後で範囲を縮小して再試行します。 |
| 403 | ft.ForbiddenQuery | Key に文が必要とするデータドメインのクエリ権限がない | 您无{}权限 | 現在の Key に対応するデータドメインのクエリ権限を設定し、データアクセスとインデックスの制限を確認します。 |