コンテンツにスキップ

クエリタスク結果の取得



GET /api/v1/logmine/query_task

概要

パターンタスクのステータスをポーリングし、完了後にマスキングされたパターン結果を読み取ります。

呼び出し前の準備と使用手順

対象ワークスペースの Key を使用し、routine.defaultAccess または anonymous.snapshotShared のいずれかのエントリ権限が必要です。GET Query の taskId を使用してポーリングします。Query のホワイトリストでは taskId のみが許可されています。クロスワークスペース、インデックス、上限、URL body のパラメータを追加しないでください。結果の処理は引き続きデータアクセスとマスキングコンテキストの制約を受けます。

taskId は必ずクエリタスクの送信の実際の戻り値を使用し、同じワークスペースの Key で速やかにポーリングしてください。タスクが未完了の場合、data が空で docCount が 0 であるのはプレースホルダーであり、最終的にデータがないとみなしてはいけません。taskStatus が厳密に ok と等しい場合にのみ結果を読み取ります。その他のステータス文字列と error はタスクサービスからのものであり、実際の進捗/失敗の意味に従って処理し、すべての非 ok を無制限にリトライしないでください。ポーリングのバックオフとクライアント側の期限設定を推奨します。完了した結果は保存してください。

完了した結果は、作成時に保存されたフィールド/データアクセス設定および現在の機密フィールドルールに従ってフォーマットされます。通常の OpenAPI の message は、選択された文字列フィールドを連結したテキストであり、元の JSON オブジェクトではありません。存在しないフィールドは自動的に補完されず、文字列以外の値はスキップされ、一部の内容はマスクされる場合があります。docids はタスクサービスが返す元のドキュメント識別子であり、任意の削除/変更 API にそのまま送信できるリソース UUID ではありません。count/docCount は処理結果を記述するのみで、時間範囲が完全にカバーされていることや、上限に達する前に切り捨てが行われたかどうかを証明するものではありません。

キャッシュコンテキストは20分間のみ保存され、通常のポーリングでは更新されません。タスクサービスにまだ結果があっても、コンテキストが期限切れ/欠落している場合はクエリタイムアウト 406 が返され、マスキングを迂回して直接読み取ることはできません。待機状態ではキャッシュが欠落していても 200 が返る場合があり、完了時にはじめて検証が実行されます。この差異を利用してタスクの帰属が検証済みであると判定しないでください。no_index_list はローカルで直接空の結果を返すセンチネルであり、taskStatus=ok/data=[]/docCount=0 を含みますが、processingLimit/timeRange はなく、クエリが実行されたことを意味するものではありません。

リクエストヘッダー

パラメータ名 型 必須 説明
DF-API-KEY string Y ワークスペースの OpenAPI 認証情報。
例: <DF-API-KEY>
取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。

Query リクエストパラメータ

パラメータ名 型 必須 説明
taskId string Y 必須の文字列です。traceId や自分で生成した ID を使用しないでください。no_index_list はインデックスなしのセンチネルであり、リモートタスクではありません。
例: logmine_task_example
取得または入力方法: 同一ワークスペースのクエリタスクの送信の content.taskId を使用します。

リクエスト例

curl --get 'https://openapi.guance.com/api/v1/logmine/query_task' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  --data-urlencode taskId=logmine_task_example

レスポンス

HTTP 200、application/json。以下の例は、直接読み取れる主要なフィールドを示しています。

フィールド 型 説明
content.taskStatus string タスクサービスの非空ステータスをそのまま返します。ok は結果取得を意味し、その他のステータスは固定の列挙を強制しません。
content.data array 完了時のパターングループのリスト。未完了/インデックスなしの場合は空です。ページネーションではなく、pageInfo は存在しません。
content.data[] object 近似テキストのパターングループの1つ。追加フィールドはタスクサービスの戻り値に依存します。
content.data[].count integer このグループでマッチ/処理されたドキュメント数。タスクサービスから返されます。
content.data[].docids array このグループのドキュメント識別子のリスト。要素は通常 string です。
content.data[].message string フィールド抽出とマスキングを経た連結テキスト。空の場合があります。元のメッセージ JSON ではありません。
content.docCount integer タスクサービスが返す分析ドキュメント数。未完了/インデックスなしの場合はデフォルトで 0 となり、全時間範囲のヒット総数を証明するものではありません。
content.progress JSON 上流が提供する場合にパススルーされる進捗。形式は固定ではなく、省略される場合があります。
content.error JSON 上流が提供する場合にパススルーされるエラー情報。HTTP 200 でもタスクステータスとこのフィールドを確認する必要があります。
content.processingLimit integer または null 作成キャッシュに保存されている場合にのみ返されます。履歴/インデックスなしのセンチネルでは省略される場合があり、現在の設定を作成時の上限として代用することはできません。
content.timeRange array 作成キャッシュに該当キーが存在する場合に返される元のリクエスト範囲。省略される場合があります。
content.declaration object 最外層の共通宣言のみで、data[] に再帰的に付加されません。
{
  "code": 200,
  "content": {
    "taskStatus": "ok",
    "data": [
      {
        "count": 2,
        "docids": [
          "DOC-ID-1",
          "DOC-ID-2"
        ],
        "message": " upstream request * failed"
      }
    ],
    "docCount": 2,
    "processingLimit": 10000,
    "timeRange": [
      1785427200000,
      1785429000000
    ],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

タスク実行中の例(進捗の型とステータステキストは上流の実際の戻り値に従い、固定の列挙を構成しません):

{
  "code": 200,
  "content": {
    "taskStatus": "running",
    "data": [],
    "docCount": 0,
    "progress": 0.5,
    "processingLimit": 10000,
    "timeRange": [
      1785427200000,
      1785429000000
    ],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

エラー応答

認証、レート制限、共通リクエストエラーの詳細は共通エラー定義を参照してください。

タスクサービスでは動的なデータクエリ/権限エラーが発生する可能性があるため、実際の HTTP とエラー本文に従って処理してください。パススルーマークがない 5xx は統一的に HTTP 500 ft.InternalServerError になるため、すべての上流コードがそのまま透過されるとは想定できません。HTTP 200 success=true は今回の送信/ポーリング API が成功したことのみを示し、非同期のパターン処理が完了したことを示すものではありません。

HTTP ステータス errorCode 発生条件 メッセージまたは応答の説明 対応方法
406 ft.ParameterValidationFailed 未宣言の Query パラメータを使用した、またはパラメータがルールに違反している パラメータの解析に失敗 Query パラメータ表と例を確認してください。
406 ft.FrontRequestTimeout タスクが ok だが、作成時のマスキングコンテキストキャッシュが欠落または期限切れ クエリタイムアウト 元のパラメータで小範囲のタスクを再送信し、速やかにポーリングしてください。古い ID を繰り返しポーリングしてもキャッシュが回復するとは期待しないでください。
406 ft.InvalidParameter キャッシュ内のフィールドまたはデータドメインが有効な構造でない パラメータ{}が無効 その古い ID への繰り返しクエリを停止し、管理者に連絡してキャッシュの互換性を確認したうえで再作成してください。
500 ft.InternalServerError タスクステータスが非空文字列でない、タスクサービスの 5xx、または返却されたメッセージ/キャッシュ JSON の形式異常 内部エラー traceId と taskId を保持してください。HTTP 200/タスクの存在のみで結果が完全であると判断しないでください。

フィードバック

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