콘텐츠로 이동

데이터 쿼리 작업 결과 가져오기



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를 보관하고 쿼리 현재 상태를 확인한 후 다시 시도하며, 계속 실패하면 관리자에게 문의합니다.

문서 평가

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