DQL 비동기 데이터 쿼리¶

POST /api/v1/df/asynchronous/query_data

개요¶

Body 요청 파라미터¶

파라미터 추가 설명¶

쿼리 설명

이 인터페이스는 POST와 GET을 모두 지원하며, 두 방식 모두 동일한 JSON object 파라미터 구조를 사용합니다. POST는 전체 파라미터를 application/json request body에 넣고, GET은 query string에서 body=<전체 JSON object 문자열>로 전달하며 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는 하나의 쿼리 항목과 한 번의 작업에만 속하며, 세션 ID도 아니고 페이지네이션 커서도 아닙니다. 일괄 쿼리 시 content.data[i]와 queries[i]는 배열 인덱스로 대응되므로, 한 쿼리 항목의 ID를 다른 쿼리 항목에 사용할 수 없습니다. 매핑 오류를 줄이기 위해 비동기 호출은 매번 query를 하나만 제출할 것을 권장합니다.
5. is_running=true인데 async_id가 비어 있으면 폴링할 수 없는 예외 응답으로 간주합니다. 이전 ID를 넣지 말고 traceId를 기록한 후 유한 재시도 정책에 따라 해당 논리 쿼리를 다시 시작하거나 기술 지원에 문의하세요.

증분 백오프(Incremental Backoff)를 사용하고 전체 타임아웃을 설정하여 간격 없는 폴링을 피하는 것이 좋습니다. 작업 완료 후 페이지를 넘길 때는 최종 결과에서 반환된 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"
      }
    }
  ]
}

크로스 사이트 쿼리는 "하나의 요청에서 하나의 targetRegion만 조회"라는 제한을 준수해야 합니다. 대상 워크스페이스와 사이트 코드 획득 및 전체 호출 절차는 OpenAPI 크로스 사이트 데이터 쿼리를 참조하세요.

1. 파라미터 설명

1. queries[*] 멤버 파라미터 구조 설명

동기 쿼리와 비교하여 각 query 항목은 async_id를 추가로 지원합니다. 이는 현재 실행 중인 작업을 폴링하는 데에만 사용됩니다.

1. 응답 포인트 밀도 density 파라미터 값 설명

• 포인트 밀도 파라미터의 우선순위에 유의하세요. 최대 밀도 density[high] * maxPointCount > interval > density > dql 문의 제어 파라미터

• 일반적인 쿼리 설명

• 미복구 이벤트 쿼리

• OpenAPI 크로스 사이트 데이터 쿼리 참고: openapi 인터페이스로 데이터를 조회할 때 기본값은 관리자 역할입니다. 데이터 액세스 규칙의 제한을 받을 수 있으므로 주의하세요.

요청 예시¶

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"
}