쿼리 작업 결과 가져오기¶
GET /api/v1/logmine/query_task
개요¶
패턴 작업 상태를 폴링하고, 완료되면 마스킹된 패턴 결과를 읽습니다.
호출 전 준비 및 사용 단계¶
대상 워크스페이스의 Key를 사용하며, routine.defaultAccess 또는 anonymous.snapshotShared 중 하나의 진입 권한이 필요합니다. GET Query의 taskId로 폴링하며, Query 화이트리스트에는 taskId만 허용됩니다. 워크스페이스 간, 인덱스, 한도 또는 URL body 파라미터를 추가하지 마세요. 결과 처리는 여전히 데이터 액세스 및 마스킹 컨텍스트의 제약을 받습니다.
taskId는 반드시 쿼리 작업 전송의 실제 반환값을 사용해야 하며, 동일한 워크스페이스의 Key로 적시에 폴링해야 합니다. 작업이 아직 완료되지 않았을 때 data가 비어 있고 docCount가 0인 것은 자리 표시자이며, 최종적으로 데이터가 없다고 간주해서는 안 됩니다. taskStatus가 엄격히 ok와 같을 때만 결과를 읽습니다. 그 외 상태 문자열과 error는 작업 서비스에서 온 것이므로 실제 진행/실패 의미에 따라 처리해야 하며, 모든 비 ok 상태를 무한 재시도해서는 안 됩니다. 폴링 백오프를 적용하고 클라이언트 마감 시간을 설정하며, 완료된 결과를 저장할 것을 권장합니다.
완료된 결과는 생성 시 저장된 필드/데이터 액세스 구성과 현재 민감 필드 규칙에 따라 포맷됩니다. 정상 OpenAPI의 message는 선택된 문자열 필드를 이어 붙인 텍스트이며 원본 JSON 객체가 아닙니다. 존재하지 않는 필드는 자동으로 보완되지 않고, 문자열이 아닌 값은 건너뛰며, 일부 내용은 마스킹될 수 있습니다. docids는 작업 서비스가 반환한 원본 문서 식별자이며, 임의의 삭제/수정 API에 직접 제출할 수 있는 리소스 UUID가 아닙니다. count/docCount는 처리 결과만 설명하며, 시간 범위가 완전히 커버되었는지 또는 한도에 도달하기 전에 잘렸는지를 증명하지 않습니다.
캐시 컨텍스트는 20분 동안만 보관되며, 정상 폴링으로는 갱신되지 않습니다. 작업 서비스에 결과가 남아 있더라도 컨텍스트가 만료되었거나 없으면 쿼리 시간 초과 406이 반환되며, 마스킹을 우회해 직접 읽을 수 없습니다. 대기 상태에서는 캐시가 없어도 200이 반환될 수 있고, 완료 시에만 검증이 트리거됩니다. 이 차이를 이용해 작업 소유권이 검증되었다고 판단해서는 안 됩니다. no_index_list는 로컬에서 직접 빈 결과를 반환하는 센티널로, taskStatus=ok/data=[]/docCount=0을 포함하지만 processingLimit/timeRange가 없으며, 쿼리가 수행되었음을 의미하지 않습니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Query 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| taskId | string | Y | 필수 문자열이며, traceId를 사용하거나 임의로 ID를 만들지 마세요. no_index_list는 인덱스 없음 센티널이며 원격 작업이 아닙니다. 예: logmine_task_example획득 또는 입력 방법: 동일한 워크스페이스의 쿼리 작업 전송에서 content.taskId를 가져옵니다. |
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/logmine/query_task' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode taskId=logmine_task_example
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.taskStatus | string | 작업 서비스의 비어 있지 않은 상태를 그대로 반환합니다. ok는 결과 조회를 의미하며, 나머지 상태는 고정 열거형으로 강제되지 않습니다. |
| content.data | array | 완료 시의 패턴 그룹 목록이며, 미완료/인덱스 없음이면 비어 있습니다. 페이지네이션이 아니며 pageInfo는 존재하지 않습니다. |
| content.data[] | object | 유사 텍스트 패턴 그룹 하나이며, 추가 필드는 작업 서비스 반환에 따릅니다. |
| content.data[].count | integer | 해당 그룹에서 매칭/처리된 문서 수이며, 작업 서비스가 반환합니다. |
| content.data[].docids | array | 해당 그룹의 문서 식별자 목록이며, 요소는 일반적으로 string입니다. |
| content.data[].message | string | 필드 추출과 마스킹을 거친 연결 텍스트로, 비어 있을 수 있습니다. 더 이상 원본 메시지 JSON이 아닙니다. |
| content.docCount | integer | 작업 서비스가 반환한 분석 문서 수이며, 미완료/인덱스 없음일 때 기본값 0입니다. 전체 시간 범위의 매칭 총계를 증명하지 않습니다. |
| content.progress | JSON | 업스트림에서 제공되는 경우 그대로 전달되는 진행률로, 형태가 고정되지 않으며 누락될 수 있습니다. |
| content.error | JSON | 업스트림에서 제공되는 경우 그대로 전달되는 오류 정보입니다. HTTP200이더라도 작업 상태와 이 필드를 확인해야 합니다. |
| content.processingLimit | integer 또는 null | 생성 캐시에 저장되어 있는 경우에만 반환됩니다. 이전 작업/인덱스 없음 센티널에서는 누락될 수 있으며, 현재 구성을 생성 시 상한으로 대체할 수 없습니다. |
| content.timeRange | array | 생성 캐시에 해당 키가 존재할 때 반환되는 원래 요청 범위이며, 누락될 수 있습니다. |
| content.declaration | object | 최상위 공통 선언만 해당하며, data[]에 재귀적으로 추가되지 않습니다. |
{
"code": 200,
"content": {
"taskStatus": "ok",
"data": [
{
"count": 2,
"docids": [
"DOC-ID-1",
"DOC-ID-2"
],
"message": " upstream request * failed"
}
],
"docCount": 2,
"processingLimit": 10000,
"timeRange": [
1785427200000,
1785429000000
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
작업 진행 중 예시(진행 유형과 상태 텍스트는 업스트림 실제 반환에 따르며, 고정 열거형을 구성하지 않습니다):
{
"code": 200,
"content": {
"taskStatus": "running",
"data": [],
"docCount": 0,
"progress": 0.5,
"processingLimit": 10000,
"timeRange": [
1785427200000,
1785429000000
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하세요.
작업 서비스에서 동적 데이터 쿼리/권한 오류가 발생할 수 있으므로 실제 HTTP와 오류 본문에 따라 처리해야 합니다. 패스스루 표시가 없는 5xx는 HTTP500 ft.InternalServerError로 통일되며, 모든 업스트림 코드가 그대로 노출된다고 가정할 수 없습니다. HTTP200 success=true는 이번 제출/폴링 API 호출이 성공했음을 의미할 뿐, 비동기 패턴 작업이 완료되었음을 의미하지 않습니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방식 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 선언되지 않은 Query 파라미터를 사용했거나 파라미터가 규칙을 위반함 | 파라미터 파싱 실패 | Query 파라미터 표 및 예시를 확인합니다. |
| 406 | ft.FrontRequestTimeout | 작업이 ok이지만 생성 시의 마스킹 컨텍스트 캐시가 없거나 만료됨 | 쿼리 시간 초과 | 원래 파라미터로 범위가 작은 작업을 다시 제출하고 적시에 폴링하세요. 이전 ID를 반복 폴링해도 캐시가 복구되리라 기대하지 마세요. |
| 406 | ft.InvalidParameter | 캐시의 필드 또는 데이터 영역이 유효한 구조가 아님 | 파라미터 {} 가 유효하지 않음 |
해당 이전 ID에 대한 반복 쿼리를 중지하고, 관리자에게 캐시 호환성을 확인한 후 다시 생성하세요. |
| 500 | ft.InternalServerError | 작업 상태가 비어 있지 않은 문자열이 아니거나, 작업 서비스 5xx 또는 반환된 메시지/캐시 JSON 형식이 비정상임 | 내부 오류 | traceId와 taskId를 보존하세요. HTTP200/작업 존재만으로 결과가 완전하다고 판단하지 마세요. |