コンテンツにスキップ

データクエリタスクの作成



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 を提供してください。

フィードバック

このページは役に立ちましたか?