콘텐츠로 이동

데이터 쿼리 작업 생성



POST /api/v1/log_backup_cfg/query_task

개요

데이터 전송 데이터에 대한 비동기 쿼리 작업을 제출합니다.

호출 전 및 사용 단계

반드시 비어 있지 않은 정확한 name을 전달하여 쿼리를 지원하는 규칙을 선택해야 합니다. 빈 문자열은 워크스페이스의 첫 번째 사용 가능한 규칙을 선택할 수 있으므로 빈 문자열로 쿼리하지 마십시오. 밀리초 시간 범위와 선택적 정규식 객체를 제공합니다. 먼저 규칙의 데이터 읽기 권한을 검증한 후 다운스트림 비동기 작업을 제출합니다. 성공 시 작업 ID만 반환되며, 이미 쿼리 행이 있거나 작업이 완료되었음을 의미하지 않습니다. 클라이언트는 task_id로 결과 인터페이스를 폴링하며, task_status=completed일 때만 완료를 의미합니다. 매회 최대 10개 파일을 검색하며, 더 많은 파일이 필요하면 반환된 token을 받아 동일한 조건으로 다시 한 라운드 작업을 생성해야 합니다.

쿼리 대상은 객체 스토리지/플랫폼 내장 객체, Doris 및 독립 searchToken이 있는 LogBamboo를 지원합니다. Kafka, Iceberg, 레거시 TiDB는 이 인터페이스를 사용하지 않습니다. 요청 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이고 행 수를 제어하며, 매회 최대 10개 파일을 검색하는 프로토콜 범위를 확장하지 않습니다.
null 허용: False
$maxValue: 1000
$minValue: 1
예: 20
획득 또는 입력 방법: 매회 반환을 기대하는 행 수에 따라 1..1000을 선택합니다.

파라미터 추가 설명

search 요청 파라미터 설명

파라미터명 type 설명
conditions array[json] 쿼리 조건이며, 각 조건은 key, value, logic 필드를 포함하는 json 객체입니다
operator string 논리 연산자이며 선택 값: and, or

conditions 파라미터 설명

파라미터명 type 설명
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를 제공합니다.

문서 평가

이 페이지가 도움이 되었나요?