DQL データ非同期クエリ¶

POST /api/v1/df/asynchronous/query_data

概要¶

Body リクエストパラメータ¶

パラメータ補足説明¶

クエリ説明

このインターフェースは POST と GET の両方をサポートし、両方式とも同じ JSON オブジェクトのパラメータ構造を使用します。POST は完全なパラメータを application/json リクエストボディに格納し、GET はクエリ文字列内で body=<完全な JSON オブジェクト文字列> として渡し、URL エンコードします。トップレベルでは string、array、null、number、boolean は受け付けません。

非同期クエリの最終レスポンスの content.data[i].warnings[] には DQLDataAccessScopeRestricted が含まれる場合があります。details[0].metadata.namespace は現リリースでは固定で logging です。restriction=partial は権限のあるインデックスのデータのみが返されることを示し、restriction=all は関連するログインデックスにすべて権限がなく、空の結果が返されることを示します。HTTP ステータスコードとリクエストパラメータは変わりません。

async_id のライフサイクル（重要）

1. 新しい論理クエリを開始するときは、queries[i].async_id を省略する必要があります。サーバーが非同期実行に切り替えた場合、同じ位置に content.data[i].is_running=true と空でない content.data[i].async_id を返します。
2. is_running が厳密に true で、かつ async_id が空でない場合にのみ、その ID を使用して同じタスクをポーリングします。ポーリングリクエストでは、その項目の qtype、query、対象ワークスペース、および targetRegion を変更せず、ID を対応する queries[i].async_id に戻してください。
3. is_running=false の場合、今回のタスクは終了しています。レスポンス構造に async_id フィールドがまだ含まれていても、呼び出し側は次の新しいクエリで古い ID を引き続き使用してはいけません。新しいクエリ、およびクエリ文/時間範囲を変更したクエリでは、いずれの場合も async_id を再度省略する必要があります。
4. async_id は 1 つのクエリ項目と 1 回のタスクにのみ属し、セッション ID でもページネーションカーソルでもありません。バッチクエリでは、content.data[i] と queries[i] は配列のインデックスで対応します。あるクエリ項目の ID を別のクエリ項目に使用することは禁止されています。マッピングエラーを減らすため、非同期呼び出しでは一度に 1 つの query のみを送信することを推奨します。
5. is_running=true であるのに async_id が空の場合、ポーリング不可の異常レスポンスとみなします。過去の ID を入れないでください。traceId を記録し、有限回数のリトライ戦略に従ってその論理クエリを再発行するか、テクニカルサポートに連絡してください。

増分バックオフを採用し、合計タイムアウトを設定して、間隔なしのポーリングを避けることを推奨します。タスク完了後にページングが必要な場合は、最終結果で返された search_after、next_cursor_time、または next_cursor_token を使用し、async_id をページネーションパラメータの代わりに使用しないでください。

初回リクエスト（async_id を渡さない）

{
  "queries": [
    {
      "qtype": "dql",
      "query": {
        "q": "L::re(`.*`):(`message`)",
        "timeRange": [1772516130000, 1772519730000],
        "limit": 100,
        "workspaceUUIDs": ["wksp_target"],
        "targetRegion": "region_code"
      }
    }
  ]
}

実行中の場合のみ同じタスクをポーリング

{
  "queries": [
    {
      "async_id": "async_task_id_from_content_data_0",
      "qtype": "dql",
      "query": {
        "q": "L::re(`.*`):(`message`)",
        "timeRange": [1772516130000, 1772519730000],
        "limit": 100,
        "workspaceUUIDs": ["wksp_target"],
        "targetRegion": "region_code"
      }
    }
  ]
}

クロスサイトクエリでは、「1 つのリクエストで 1 つの targetRegion のみをクエリする」という制限も守る必要があります。対象ワークスペースとサイトコードの取得方法、および完全な呼び出しフローについては、OpenAPI クロスサイトデータクエリ を参照してください。

1、パラメータ説明

2、queries[*] メンバーパラメータの構造説明

同期クエリと比較して、各 query 項目は追加で async_id をサポートします。これは現在も実行中のタスクをポーリングするためだけに使用されます。

3、レスポンス点密度の density パラメータ値の説明

• 点密度パラメータの優先度に注意してください。最大密度は density[high] です。* maxPointCount > interval > density > dql 文内の制御パラメータ

4、よくあるクエリの説明

• 未復旧イベントクエリ
• OpenAPI クロスサイトデータクエリ 注: openapi インターフェースでデータクエリを実行する場合、デフォルトで管理者（admin）ロールになります。データアクセスルールの制限を受ける可能性があることに注意してください。

リクエスト例¶

curl 'https://openapi.guance.com/api/v1/df/asynchronous/query_data' \
-H 'Content-Type: application/json' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-raw '{"queries":[{"qtype":"dql","query":{"q":"L::re(`.*`):(`message`)","timeRange":[1772516130000,1772519730000],"limit":100}}]}' \
--compressed

レスポンス¶

{
    "code": 200,
    "content": {
        "data": [
            {
                "async_id": "async_task_id",
                "is_running": true
            }
        ]
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-XXXX"
}