데이터 쿼리 작업 결과 가져오기¶
GET /api/v1/log_backup_query/get_result
개요¶
비동기 쿼리 작업의 상태 및 마스킹된 결과를 가져옵니다.
호출 전 및 사용 단계¶
query_task가 반환한 task_id를 Query.taskId로 사용하여 폴링합니다. 상태와 결과 필드는 다운스트림에서 반환되며, task_status=completed인 경우에만 완료로 처리합니다. 그 외 상태는 계속 대기하거나 응답 정보에 따라 실패를 처리해야 하며, HTTP 200으로 완료를 판단하지 않습니다. 완료 시 Studio는 규칙의 dataType, syncExtensionField 및 현재 자격을 기준으로 마스킹을 수행한 뒤 완료 쿼리 감사를 기록합니다(작업별 중복 제거).
message는 텍스트 또는 JSON 문자열일 수 있으므로 데이터 유형과 실제 결과에 따라 파싱하고, 고정된 객체 구조를 가정하지 않습니다. is_truncated/token은 후속 배치 쿼리에 사용되며, 원래 쿼리 조건을 유지한 채 token을 query_task에 전달합니다. 쿼리 컨텍스트 캐시는 12시간 동안 보존되며, 완료 시 컨텍스트가 유실되면 410을 반환하므로 쿼리를 다시 생성해야 합니다. 이 시간은 다운스트림 작업 자체의 보존 약속이 아닙니다. 이 결과 라우트는 규칙의 readPermissionSet을 다시 조회하지 않지만, 여전히 현재 인터페이스의 인증 및 데이터 마스킹을 거치며, 작업 ID를 권한이 없는 자격에 공유하지 않습니다.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Query 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| taskId | string | Y | 필수 원본 작업 ID이며, 콜론 등의 문자가 포함된 경우 URL 인코딩을 사용하고 token과 혼용하지 않습니다. null 허용: False 예시: task_example획득 또는 입력 방법: query_task 응답의 content.task_id에서 가져옵니다. |
파라미터 추가 설명¶
응답 결과의 필드 설명입니다.
| 파라미터명 | type | 설명 |
|---|---|---|
| token | string | 쿼리 커서. 페이징 쿼리를 하려면 요청 결과의 token을 함께 전달해야 합니다 |
| row | string | 검색된 행 정보 |
| task_status | string | 작업 상태(created,running,completed,failed) |
| total_files | integer | 총 파일 수 |
참고: 작업 상태가 created 및 running이면 아직 검색 중임을 의미합니다. completed, failed는 검색이 종료되었음을 의미합니다.¶
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/log_backup_query/get_result' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode taskId=task_example
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.task_status | string | 다운스트림 작업 상태이며, completed는 완료를 의미하고 그 외 값은 그대로 반환됩니다. |
| content.row | array<object> |
완료 후의 쿼리 행으로, 비어 있을 수 있으며 아직 완료되지 않은 경우 생략될 수 있습니다. |
| content.row[].message | string 또는 JSON | 마스킹된 데이터 페이로드로, 대개 원본 텍스트 또는 직렬화된 JSON이며 객체로 고정되지 않습니다. |
| content.row[].date | integer | 업스트림 레코드 시간으로, 기존 프로토콜 예시는 Unix 밀리초이며 규칙 createAt의 Unix 초가 아닙니다. |
| content.row[].기타 열 | JSON | 데이터 유형에 따라 업스트림 레코드 열이 추가로 포함될 수 있습니다. |
| content.token | string | 조건을 유지하여 다음 라운드 작업을 생성할 때 사용하는 투명 커서이며, 비어 있거나 생략될 수 있습니다. |
| content.is_truncated | boolean | 현재 결과의 잘림 여부로, token과 함께 다음 배치를 준비하며 생략될 수 있습니다. |
| content.total_files | integer | 업스트림이 반환한 검색 파일 통계이며 생략될 수 있습니다. |
| content.search_completed | number | 업스트림 검색 완료 통계 값으로, Studio는 이를 정규화하지 않으며 완료 불리언이나 백분율로 간주하지 마십시오. 완료 여부는 task_status로 판단합니다. |
| content.declaration | object | 비어 있지 않은 객체의 공통 선언입니다. |
{
"code": 200,
"content": {
"token": "CURSOR-EXAMPLE",
"row": [
{
"message": "{\"message\":\"error: example\",\"service\":\"checkout-api\"}",
"date": 1785427200000
}
],
"is_truncated": true,
"total_files": 2,
"search_completed": 0,
"task_status": "completed",
"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 | 선언되지 않은 Query 파라미터를 사용했거나 파라미터가 규칙을 위반한 경우 | 파라미터 파싱 실패 | Query 파라미터 표 및 예시를 확인합니다. |
| 410 | ft.BackuplogQueryContextExpired | 완료 결과에 마스킹이 필요하지만 쿼리 컨텍스트가 유실되었거나 12시간을 초과한 경우 | 전달된 데이터 쿼리 컨텍스트가 만료되었으므로 쿼리 작업을 다시 생성하십시오 | 원래 조건으로 작업을 다시 생성한 후 결과를 가져오며, 마스킹을 우회할 수 없습니다. |
| 500 | ft.InternalServerError | 다운스트림 일반 5xx, 결과 마스킹, 캐시 또는 완료 감사 처리 실패 | 내부 오류 | taskId/traceId를 보관하고 쿼리 현재 상태를 확인한 후 다시 시도하며, 계속 실패하면 관리자에게 문의합니다. |