データクエリタスクの作成¶
POST /api/v1/log_backup_cfg/query_task
概要¶
データ転送データの非同期クエリタスクを送信します。
呼び出し前の確認と使用手順¶
クエリをサポートするルールを選択するには、空でない正確な name を必ず渡す必要があります。空文字列を指定すると、ワークスペース内の最初の利用可能なルールが選択される可能性があるため、空文字列でクエリしないでください。ミリ秒単位の時間ウィンドウと任意の正規表現オブジェクトを指定します。まずルールのデータ読み取り権限を検証し、その後ダウンストリーム非同期タスクを送信します。成功時はタスク ID のみを返し、クエリ結果行が存在することやタスクが完了したことを示すものではありません。クライアントは task_id を使用して結果 API を呼び出してポーリングします。task_status=completed の場合のみ完了を表します。1 回の検索で最大 10 ファイルまで検索でき、さらにファイルが必要な場合は返された token を取得し、同じ条件で次のラウンドのタスクを作成します。
クエリ対象はオブジェクトストレージ/プラットフォーム組み込みオブジェクト、Doris、および独立した searchToken を持つ LogBamboo をサポートします。Kafka、Iceberg、レガシー TiDB はこの API を使用しません。リクエストの dataType はルールカテゴリを変更しません。空でない search は conditions 配列構造に従う必要があります。タスクは作成された後に、コンテキスト/キャッシュまたは監査組織が原因で失敗する可能性があるため、エラー発生後はまず task_id を確認してください。完了した結果に対してマスキングを実行するには、Studio にキャッシュされた 12 時間のクエリコンテキストが必要です。期限切れの場合はタスクを再作成してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| search.conditions | array | フィルター配列。これはクエリ検索構造であり、extend.filters ではありません。 例: [{"key": "message", "logic": "match", "value": "error.*"}]取得または入力方法: 各項目を key/value/logic に従って正規表現条件として構成します。 |
|
| search.conditions[*] | json | 単一のクエリ条件オブジェクト。 例: {"key": "message", "logic": "match", "value": "error.*"}取得または入力方法: 実際のデータフィールドまたは全文条件に従って構築します。 |
|
| search.conditions[*].key | string | 任意のフィールドキー。任意のログ表示名をフィールドとして扱わないでください。 例: message取得または入力方法: レコードのフィールド名を取得します。全文の場合はキーを省略できます。 |
|
| search.conditions[*].value | string | 正規表現の検索値であり、DQL 文ではありません。 例: error.*取得または入力方法: 有効な正規表現(例: error.*)。 |
|
| search.conditions[*].logic | string | 大文字と小文字を正確に一致させた論理値を使用します。 例: match取得または入力方法: match は一致、notMatch は一致除外です。実際の検索プロトコルに従ってください。 |
|
| dataType | string | 任意の互換フィールド。コントローラーは最終的に常にルールの dataType で上書きするため、クエリカテゴリは切り替わりません。 空文字列を許可: True null を許可: False 指定可能な値: ['lineage', 'metric', 'llm', 'logging', 'tracing', 'rum', 'keyevent', 'audit_event', 'am'] 例: logging取得または入力方法: ルールの現在のカテゴリを使用します。ルールを優先するため省略を推奨します。 |
|
| endTime | string | Y | 必須。Studio のこのルートは時間順序と利用可能なデータ範囲の完全な検証を行わないため、エラーはダウンストリームから返されます。 null を許可: False 例: 1785430800000取得または入力方法: ウィンドウ終了の Unix ミリ秒文字列。呼び出し元は開始より後であることを保証してください。 |
| name | string | Y | 必須文字列として宣言されています。呼び出し元は空でない正確な名前を送信する必要があります。現在、空文字列では名前フィルターが適用されず、ワークスペース内の最初の利用可能なルールが取得される可能性があるため、対象の指定には使用できません。データ読み取りはルール権限によっても制御されます。 null を許可: False 例: production_archive取得または入力方法: データ転送ルール一覧から uuid ではなく name を取得します。 |
| search | json | 任意の JSON オブジェクト。Front の JSON 文字列や直接の "error.*" は使用できません。空でない場合は conditions 配列を含め、タスク作成後の監査テキスト処理エラーを回避してください。 null を許可: False 例: {"conditions": [{"key": "message", "logic": "match", "value": "error.*"}]}取得または入力方法: 正規表現検索オブジェクトの構造に従って入力するか、省略/{} でフィルターを適用しないでください。 |
|
| startTime | string | Y | 必須のミリ秒文字列(秒ではありません)。実際にサポートされる時間ウィンドウは対象のクエリサービスによって制約されるため、まず小さめのウィンドウでクエリすることを推奨します。 null を許可: False 例: 1785427200000取得または入力方法: 既存の転送データがあるクエリウィンドウの開始 Unix ミリ秒を選択し、文字列に変換します。 |
| token | string | カーソルは透過的な文字列です。同じ name、時間、search 条件を維持し、独自に結合したり、ルールをまたいで再利用したりしないでください。 空文字列を許可: True null を許可: False 例: 取得または入力方法: 初回は省略/空にし、継続時は get_result が返す content.token から取得します。 |
|
| topN | integer | 任意。デフォルトは 20 で、行数を制御します。1 回の検索で最大 10 ファイルというプロトコル範囲を拡大するものではありません。 null を許可: False $maxValue: 1000 $minValue: 1 例: 20取得または入力方法: 1 回に返されることを期待する行数に応じて 1..1000 から選択します。 |
パラメータ補足説明¶
search リクエストパラメータの説明
| パラメータ名 | 型 | 説明 |
|---|---|---|
| conditions | array[json] | クエリ条件。各条件は 1 つの JSON オブジェクトで、key、value、logic フィールドを含みます |
| operator | string | 論理演算子。指定可能な値: and、or |
conditions パラメータの説明
| パラメータ名 | 型 | 説明 |
|---|---|---|
| key | string | フィールド名 |
| value | string | フィールド値 |
| logic | string | 論理演算子。指定可能な値: match、notMatch |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/log_backup_cfg/query_task' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"production_archive","startTime":"1785427200000","endTime":"1785430800000","search":{"conditions":[{"key":"message","logic":"match","value":"error.*"}]},"topN":20}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.task_id | string | ダウンストリーム非同期タスク ID。この元の文字列を使用して get_result を呼び出します。cfg_uuid ではありません。 |
| content.declaration | object | 空でないオブジェクトの共通宣言。 |
{
"code": 200,
"content": {
"task_id": "task_example",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては、共通エラー定義を参照してください。
以下のダウンストリームクエリのビジネスエラーでは、SDK が実際のアップストリーム 4xx ステータスを保持するため、ローカルのデフォルト 406 だけで判断できません。未認識のダウンストリーム error_code がアップストリーム 4xx の場合は ft.BackuplogInternalServerError にマッピングされ、実際の HTTP が保持されます。元のエラーと traceId を記録して調査してください。通常のアップストリーム 5xx、タイムアウトなどは最終的に 500 ft.InternalServerError に統一されます。
| errorCode | 発生条件と対処 |
|---|---|
| ft.BackuplogInvalidAPIArgs | ダウンストリームクエリの時間/フィルター/カーソルなどのパラメータが一致しません。ダウンストリームのメッセージに従ってパラメータを修正し、継続検索では同じ条件を維持してください。 |
| ft.BackuplogBucketNotFound | 対象のオブジェクトストレージが存在しません。ルールの対象とバケットのライフサイクルを確認してください。 |
| ft.BackuplogRuleNameInvalid | ダウンストリームのルール名が無効、または設定が同期されていません。現在のルールとバックエンドの状態を確認してから再試行してください。 |
| ft.BackuplogOSAccessDenied | ダウンストリームにターゲットデータを読み取る権限がありません。対象の認可、ロール、リソースアクセスポリシーを確認してください。 |
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反しています | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトではありません | 一部の JSON ファイルの形式エラー | パラメータ表内の JSON オブジェクトを送信してください。 |
| 404 | ft.LogBackupCfgNoExists | 空でないルール名が、現在のワークスペース内の有効かつ削除されていないルールに一致しない、または deleting 状態です | 指定されたデータ転送設定が存在しません | 一覧内の現在の name でクエリしてください。 |
| 403 | ft.NoLogBackupQueryPermission | そのルールのデータ読み取り権限がありません | データ転送ルール【{}】を表示する権限がありません | 作成者/owner、または許可された readPermissionSet の権限でクエリしてください。 |
| 406 | ft.ParameterValidationFailed | 対象がクエリ不可(Kafka/レガシー TiDB/Iceberg など)、または LogBamboo に独立した searchToken がない | パラメータ解析に失敗しました | オブジェクトクエリをサポートする対象、Doris、または searchToken を持つ LogBamboo ルールを使用してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、フィールド形状、または通常のダウンストリーム 5xx/タイムアウトの処理に失敗しました | 内部エラー | 書き込み後はまずルールの現在の状態を確認し、クエリタスクではまず task_id を確認してください。継続的に失敗する場合は traceId を提供してください。 |