데이터 쿼리 작업 생성¶
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를 제공합니다. |