쿼리 작업 전송¶
POST /api/v1/logmine/send_task
개요¶
현재 워크스페이스에서 비동기 로그 또는 기타 지원되는 데이터 도메인의 텍스트 클러스터링 작업을 제출합니다.
호출 전 및 사용 단계¶
대상 워크스페이스의 Key를 사용하며, routine.defaultAccess 또는 anonymous.snapshotShared 중 하나의 진입 권한이 필요합니다. 실제 데이터 쿼리는 여전히 데이터 도메인 권한, 인덱스 및 데이터 액세스 규칙에 의해 제한되며, 기본 액세스 권한이 모든 데이터를 쿼리할 수 있다는 의미는 아닙니다. 이 페이지는 공개 Body 선언에 따라 호출 계약을 제공하며, JSON에서 targetWorkspaceUUID/targetWorkspaceUUIDs/targetRegion/indexes/docLimit 등의 제어 파라미터는 공개되지 않으므로 선언되지 않은 추가 파라미터에 의존하지 않는 것이 좋습니다. 제출 인터페이스에는 레거시 URL 호환 파라미터 처리 방식이 존재합니다. URL의 비즈니스 필드가 동일한 이름의 JSON 값을 덮어쓰거나 선언되지 않은 필드를 보충할 수 있으며, 모든 추가 URL 파라미터가 거부되는 것은 아닙니다. 이는 안정적인 확장 계약을 구성하지 않습니다. 클라이언트는 이 페이지의 JSON 파라미터만 사용하고 URL 비즈니스 파라미터를 혼용해서는 안 됩니다.
비동기 클러스터링 작업을 제출하며, 원본 데이터를 다시 쓰거나 수정하지 않습니다. 호출 전에 필터 문과 실제 필드를 검증하고 가능한 한 작은 시간 범위를 선택합니다. 먼저 제출하여 taskId를 저장한 후, 쿼리 작업 결과 가져오기를 사용하여 동일한 워크스페이스에서 폴링합니다. 동일한 요청을 연속으로 반복 제출할 필요가 없습니다. 제출 후 캐시 쓰기 실패 시 이미 원격 작업이 생성되었을 수 있으므로, 인터페이스 실패가 원격에서 전혀 실행되지 않았음을 의미하지는 않습니다.
매번 최대 사이트 LogmineSet.docLimit 설정의 문서 수(코드 기본값 10000)까지 처리하며, time 내림차순으로 서비스에 전달됩니다. 이 인터페이스로는 해당 상한을 변경할 수 없습니다. 반환되는 processingLimit은 이번 제출 시 저장된 설정 상한이며, 이미 분석된 수량이 아니고 이를 근거로 전체 시간 범위를 커버했음을 증명할 수도 없습니다. 쿼리 가능한 인덱스가 없으면 센티널 taskId=no_index_list, processingLimit=null을 반환하며, 실제로 전체 스캔이 수행되었음을 의미하지 않습니다. 컨텍스트 캐시는 20분이며, 적시에 폴링하여 결과를 저장해야 합니다. 업스트림에 taskId가 없을 때 현재 서비스는 재검증하지 않으므로 HTTP 200이지만 taskId가 null 또는 빈 값일 수 있습니다. 이 경우 제출 결과 이상으로 판단하여 폴링과 반복 재생성을 중단하고, traceId를 보존하여 관리자가 원격 작업 발생 여부를 확인하도록 해야 합니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| analysisField | string | Y | 필수 문자열이며, 분할 후 각 항목의 양쪽 공백을 제거합니다. 반환되는 message는 이 필드들의 값으로 처리됩니다. lineage는 추가로 빈 필드/중복 필드/백틱 또는 제어 문자를 금지합니다. 다른 도메인도 중복 제거를 권장하며, 취약한 레거시 검증에 의존하지 마십시오. null 허용: False 예시: message획득 또는 입력 방법: 실제 데이터 스키마에서 분석할 텍스트 필드(예: message)를 선택하며, 최대 3개를 영문 쉼표로 연결합니다. |
| conditions | string | 선택적 문자열이며 기본값은 비어 있습니다. 비어 있지 않은 query가 제공되지 않은 경우에만 적용되며, 외부 중괄호가 있어도 없어도 됩니다. 빈 문자열 허용: True null 허용: False 예시: `source` IN ["nginx"]획득 또는 입력 방법: 실제 수집 Tag/필드에서 필터 조건을 선택하며, 쿼리 문 전체를 입력하지 않습니다. |
|
| highlight | boolean | 선택적 불리언 값입니다. 클러스터링 쿼리 서비스가 하이라이트 정보를 생성하도록 맡기며, 응답에 항상 하이라이트 필드가 포함된다고 가정할 수 없습니다. 표시할 때 데이터를 실행 가능한 HTML로 취급하지 않도록 해야 합니다. 예시: false획득 또는 입력 방법: 클라이언트가 하이라이트 텍스트를 표시할 수 있는지에 따라 선택하며, 기본값은 false입니다. |
|
| namespace | string | 생략하면 기본값은 logging이며, 명시적 빈 문자열은 공개 열거형 검증에서 406으로 거부됩니다. 값은 열거형과 일치해야 합니다. query를 제공하더라도 여전히 마스킹과 lineage 검증에 사용되므로, logging을 선언하고 실제로 lineage를 쿼리할 수는 없습니다. null 허용: False 선택 가능한 값: ['lineage', 'object', 'object_history', 'custom_object', 'logging', 'keyevent', 'unrecovered_event', 'tracing', 'rum', 'network', 'security', 'backup_log', 'profiling', 'billing'] 예시: logging획득 또는 입력 방법: 클러스터링 데이터 소스에 따라 공개 열거형을 선택하며, 로그는 logging, 카탈로그는 lineage를 사용합니다. |
|
| query | string | 선택 사항입니다. 비어 있지 않으면 전체 문장으로 우선 사용되며 conditions는 더 이상 결합되지 않습니다. namespace는 여전히 결과 마스킹/도메인 검증을 제어하고 analysisField는 여전히 필수입니다. 문장에 명시적 시간 범위가 포함된 경우, 각 계층은 timeRange와 완전히 일치하는 절대 시간 표현이어야 하며 상대 범위로 우회할 수 없습니다. null 허용: False 예시: L::`*`:(`__docid`, `message`)획득 또는 입력 방법: 쿼리 도구에서 __docid와 analysisField에 나열된 필드를 포함하는 DQL을 검증합니다. 전달하지 않으면 시스템이 생성합니다. |
|
| timeRange | array | 선택적 배열이며, 항상 두 개의 유효한 정수 밀리초를 제출할 것을 권장합니다. 공개 선언은 요소 유형/길이를 제한하지 않습니다. 기본값은 빈 배열이며, 이후 전처리나 쿼리 서비스가 이를 수용한다고 보장되지 않고 모든 이력을 자동으로 쿼리한다고 이해해서는 안 됩니다. null 허용: False 예시: [1785427200000, 1785429000000]획득 또는 입력 방법: 데이터가 있는 시작 및 종료 시간을 선택하며, Unix 밀리초 단위이고 시작이 먼저, 종료가 나중입니다. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/logmine/send_task' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"namespace":"logging","analysisField":"message","conditions":"`source` IN [\"nginx\"]","highlight":false,"timeRange":[1785427200000,1785429000000]}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.taskId | string 또는 null | 이후 폴링 식별자입니다. no_index_list는 쿼리 가능한 인덱스가 없음을 나타내는 로컬 센티널입니다. 업스트림에 해당 키가 없으면 null이 그대로 반환될 수 있으며, 빈 값/null은 폴링 가능한 작업이 아닙니다. |
| content.processingLimit | integer 또는 null | 이번 생성 시의 최대 처리 문서 수입니다. 인덱스가 없으면 null이며, 총 히트 문서 수와 같지 않습니다. |
| content.timeRange | array | 생성 시 전달된 밀리초 시간 범위이며, 서버가 자동으로 덮어쓴 범위가 아닙니다. |
| content.declaration | object | 공용 워크스페이스 선언입니다. |
{
"code": 200,
"content": {
"taskId": "logmine_task_example",
"processingLimit": 10000,
"timeRange": [
1785427200000,
1785429000000
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공용 요청 오류는 공용 오류 정의를 참조하십시오.
작업 서비스에는 동적 데이터 쿼리/권한 오류가 있을 수 있으므로 실제 HTTP와 오류 본문에 따라 처리합니다. 패스스루 표시가 없는 5xx는 일괄적으로 HTTP 500 ft.InternalServerError가 되며, 모든 업스트림 코드가 그대로 노출된다고 가정할 수 없습니다. HTTP 200 success=true는 이번 제출/폴링 인터페이스가 성공했음만 의미하며, 비동기 클러스터링이 완료되었음을 의미하지 않습니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방식 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | POST 본문이 JSON 객체가 아님 | 일부 json 파일 형식 오류 | 파라미터 표에 해당하는 객체를 제출합니다. |
| 406 | ft.InvalidParameter | namespace/analysisField가 유효하지 않음, 비어 있지 않은 query의 범위 사전 검증 파서가 ParserError를 보고, 범위가 timeRange와 일치하지 않거나 lineage 문장에 도메인 혼합/중첩이 지원되지 않음 | 파라미터 {}가 유효하지 않음 |
명확한 데이터 도메인, 1~3개의 필드 및 두 요소의 밀리초 시간 범위를 확인하고, 순수 lineage 쿼리 또는 해당 실제 도메인을 사용합니다. |
| 400 | ft.LogmineCountExceedsLimit | analysisField를 쉼표로 분할한 항목이 3개 초과 | 클러스터링 필드 수가 제한을 초과했습니다. 최대 3개까지 지원합니다 | 클러스터링이 필요한 1~3개의 필드만 제출하며, 끝에 쉼표를 남기지 마십시오. |
| 406 | ft.DqlParseError | DQL 파싱 또는 쿼리 전처리 실패 | dql parser 파싱 실패: {} | 먼저 DQL 구문과 실제 데이터 도메인을 검증한 후 문장을 수정합니다. |
| 500 | ft.InternalServerError | 작업 쿼리 서비스의 5xx가 패스스루되지 않고 일괄 래핑됨, 캐시/데이터베이스 오류 또는 업스트림 구조를 파싱할 수 없음 | 내부 오류 | traceId를 보존하고, 이미 제출한 요청의 결과가 알 수 없을 때 즉시 반복 재생성하지 말고 먼저 작업 상태를 조회하거나 잠시 후 범위를 좁혀 재시도합니다. |
| 403 | ft.ForbiddenQuery | Key에 문장에 필요한 데이터 도메인에 대한 쿼리 권한이 없음 | {} 권한이 없습니다 | 현재 Key에 해당 데이터 도메인 쿼리 권한을 구성하고 데이터 액세스 및 인덱스 제한을 확인합니다. |