콘텐츠로 이동

워크스페이스 리소스 작업 상태 조회



GET /api/v1/workspace/resource/query_action_status

개요

현재 워크스페이스에서 본인이 생성한 리소스 가져오기/내보내기 작업의 진행률을 조회합니다.

호출 전 준비 및 사용 단계

이 진입점에서 허용하는 routine.defaultAccess 권한만 있으면 되며, 원래 작업을 생성한 Key와 워크스페이스를 사용합니다. taskId로 폴링합니다. 캐시가 완전히 존재하지 않을 때는 정상적으로 HTTP200, content.status=null을 반환하며 404를 반환하지 않습니다. 긴 작업이 만료된 후 상태 기록은 소유권이 누락된 불완전한 캐시를 재생성하여 403을 반환할 수 있으므로, 이러한 403을 단순히 Key를 잘못 변경한 것으로만 해석해서는 안 됩니다. 권한 없이 존재하는 타인/다른 워크스페이스의 작업에 액세스하면 403을 반환합니다. 긴 작업의 불완전한 캐시도 403을 유발할 수 있으므로 taskId를 보관하고 관리자에게 문의하여 확인하십시오.

status=start/running이면 계속 대기합니다. ok/error/cancel은 단계 상태이지만 error_code와 import_info를 함께 확인해야 합니다. 내보내기 ok는 부분 성공일 수 있으므로 exportInfo.result와 실패 상세를 확인한 후 지체 없이 url을 다운로드해야 합니다. 가져오기 ok도 실패/변환/건너뛰기 또는 noJsonDataError가 있을 수 있으므로 항목별로 검수해야 합니다. recover를 무작정 재실행하지 말고, 이미 성공적으로 저장된 리소스를 먼저 확인하십시오.

일부 비동기 오류는 조회 시 비2xx로 전환됩니다. fileContentError는 JSON 형식 오류로 전환되고, 등록된 ft.*는 해당 비즈니스 상태로 반환됩니다(일반 5xx는 500으로 래핑). 가져오기의 failedItems에 일치하는 error_code가 있을 때 이 라우트는 HTTP400을 강제하고 비즈니스 errorCode/message를 유지하며, 오류 content에는 status/action/error_code/import_info도 포함되어 그 안에 성공 카운트가 함께 있을 수 있습니다. 오류 또는 취소가 전체 롤백을 보장하지는 않습니다. 작업 캐시 코드의 기본값은 600초이며 실제 사이트에서 재정의할 수 있습니다. 캐시 TTL은 생성 시에만 설정되고 이후 상태 갱신 시 연장되지 않습니다. 캐시가 만료되었거나 불완전한 경우 작업 로그와 이미 파악한 결과를 바탕으로 리소스를 확인한 후 재생성 여부를 결정해야 합니다.

요청 헤더

파라미터 이름 유형 필수 설명
DF-API-KEY string Y 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예시: <DF-API-KEY>
획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다.

Query 요청 파라미터

파라미터 이름 유형 필수 설명
taskId string Y 필수이며 비어 있지 않은 작업 ID입니다. 작업을 생성한 동일 워크스페이스, 동일 Key의 리소스 주체를 사용해야 하며 파일 이름이 아닙니다.
null 허용: False
예시: resource_task_example
획득 또는 입력 방법: 리소스 내보내기 작업 또는 리소스 패키지 가져오기 응답의 content.taskId에서 획득합니다.

파라미터 추가 설명

작업 결과는 이 페이지의 status, error_code 및 import_info 필드를 기준으로 합니다. 단기 ZIP 다운로드 주소는 다른 Studio API 주소로 변환할 필요가 없으며, 전체 URL은 민감한 백업 주소로 보관하십시오. 부분 성공은 전체 롤백되지 않으므로, 완료된 리소스는 다시 읽어 검수하십시오.

요청 예시

curl --get 'https://openapi.guance.com/api/v1/workspace/resource/query_action_status' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  --data-urlencode taskId=resource_task_example

응답

HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.

필드 유형 설명
content.status string 또는 null start는 대기 중, running은 실행 중, ok는 종료, error는 이상, cancel은 취소 요청입니다. 캐시가 완전히 존재하지 않으면 null이며, 만료 후 불완전한 상태 기록은 403이 될 수 있습니다. ok일 때도 오류와 부분 성공 요약을 확인해야 합니다.
content.action string export 또는 import이며, 캐시가 있을 때 반환됩니다.
content.error_code string 또는 null 비동기 비즈니스 오류 코드로, ft.* 또는 fileContentError/noJsonDataError일 수 있습니다. 일부 등록된 오류는 이번 응답에서 비2xx로 전환되며, 오류 설명을 참고하십시오.
content.import_info object 기존에 사용해 온 필드 이름으로, 내보내기/가져오기 모두 이 필드로 작업 요약을 전달합니다.
content.url string export이고 status=ok일 때만 ZIP 다운로드 URL을 반환합니다. 다운로드 가능하다고 해서 모든 리소스가 내보내졌다는 의미는 아니며, 영구 백업 주소가 아닙니다.
content.noJsonDataImported string error_code=noJsonDataError일 때의 현지화된 설명(현지화 안내)입니다. 취소/중단으로 외부에서 실제 완료 카운트를 얻지 못한 경우에도 나타날 수 있으며, 쓰기가 없었음을 증명하지 않으므로 리소스를 확인해야 합니다.
content.declaration object 현재 워크스페이스의 공통 선언입니다.
content.import_info.successCount integer 가져오기 도구가 집계한 성공 리소스 수이며 생략될 수 있습니다. 다운스트림 동기화가 모두 성공했음을 증명하지 않습니다.
content.import_info.failCount integer 집계된 실패 항목 수입니다. 부분 실패의 집계 범위는 리소스 유형에 따라 다르며 생략될 수 있습니다.
content.import_info.skippedCount integer 명시적으로 건너뛴 수이며 생략될 수 있습니다.
content.import_info.failedItems array<object> 비즈니스 실패 상세(예: 로그 인덱스 마이그레이션)이며 생략될 수 있습니다.
content.import_info.failedItems[].resourceType string 리소스 유형입니다.
content.import_info.failedItems[].fileName string 원본 설정 파일 이름입니다.
content.import_info.failedItems[].name string 리소스 이름입니다.
content.import_info.failedItems[].errorCode string 안전하게 정규화된 비즈니스 코드이며, 이번 HTTP의 기본 등록 상태와 반드시 같지는 않습니다.
content.import_info.failedItems[].message string 안전하게 처리된 비즈니스 오류 메시지입니다.
content.import_info.convertedItems array<object> 스토리지/스키마 마이그레이션 변환 기록이며 생략될 수 있습니다.
content.import_info.convertedItems[] object 리소스 마이그레이션 변환 요약이며 유형에 따라 달라집니다.
content.import_info.skippedItems array<object> 지원하지 않는 스키마 등의 건너뛰기 기록이며 생략될 수 있습니다.
content.import_info.skippedItems[].resourceType string 리소스 유형입니다.
content.import_info.skippedItems[].fileName string 원본 파일 이름입니다.
content.import_info.skippedItems[].name string 건너뛴 리소스 이름입니다.
content.import_info.skippedItems[].reason string 건너뛰기 사유(예: unsupportedIndexMode)입니다.
content.import_info.skippedItems[].errorCode string 대응하는 비즈니스 코드이며 생략될 수 있습니다.
content.import_info.skippedItems[].message string 건너뛰기 비즈니스 설명이며 생략될 수 있습니다.
content.import_info.authFailedCrossWsInfo array<object> 크로스 워크스페이스 리소스 권한 부여 실패 정보이며 생략될 수 있고, 작업은 부분 성공할 수 있습니다.
content.import_info.authFailedCrossWsInfo[] object 실패와 연관된 객체 정보입니다.
content.import_info.skippedTags array<object> 가져오기 시 태그 범위 등으로 인해 건너뛴 요약이며 생략될 수 있습니다.
content.import_info.skippedTags[] object 건너뛴 태그 정보이며 태그 가져오기 요약 구조를 따릅니다.
content.import_info.exportFailedInfo object 내보내기 모듈 오류 매핑이며 부분 성공일 수 있습니다. 값은 해당 리소스 유형의 오류 문자열 배열입니다.
content.import_info.exportFailedInfo.리소스 유형 array<string> 특정 유형의 내보내기 오류 목록입니다.
content.import_info.exportFailedInfo.리소스 유형[] string 모듈 오류 메시지입니다.
content.import_info.exportInfo object 내보내기 완전성 요약이며 생략될 수 있습니다.
content.import_info.exportInfo.result string complete/partial이며 SLO 공유 조회에서는 empty일 수도 있습니다. ok만으로 complete를 추론해서는 안 됩니다.
content.import_info.exportInfo.requestedSloCount integer SLO 전용 요청 수이며 전체 워크스페이스 진입점에서는 보통 0입니다.
content.import_info.exportInfo.exportedSloCount integer 전용 SLO의 실제 내보내기 수이며 전체 워크스페이스에서는 보통 0입니다.
content.import_info.exportInfo.skippedSloCount integer 전용 SLO 건너뛰기 수입니다.
content.import_info.exportInfo.candidateResourceCount integer 집계된 후보 리소스 수입니다.
content.import_info.exportInfo.exportedResourceCount integer 집계된 내보내기 리소스 수입니다.
content.import_info.exportInfo.permissionDeniedResourceCount integer 권한이 거부된 리소스 수입니다.
content.import_info.exportInfo.permissionDeniedByType object 리소스 유형별 거부 수입니다.
content.import_info.exportInfo.permissionDeniedByType.리소스 유형 integer 해당 유형의 거부 수량입니다.
content.import_info.exportInfo.affectedSloCount integer 의존성 실패의 영향을 받은 SLO 수입니다.
content.import_info.exportInfo.otherSkippedResourceCount integer 기타 건너뛰기 수량입니다.
content.import_info.exportInfo.resourceFailureInfo object 전체 리소스 실패 사유 그룹입니다.
content.import_info.exportInfo.resourceFailureInfo.schemaVersion integer 현재 1입니다.
content.import_info.exportInfo.resourceFailureInfo.totalCount integer 실패 상세 수입니다.
content.import_info.exportInfo.resourceFailureInfo.permissionDeniedCount integer 권한 유형 실패 수입니다.
content.import_info.exportInfo.resourceFailureInfo.otherCount integer 기타 실패 수입니다.
content.import_info.exportInfo.resourceFailureInfo.byReason object 사유 코드→수량입니다.
content.import_info.exportInfo.resourceFailureInfo.byReason.사유 코드 integer 해당 사유의 수량입니다.
content.import_info.exportInfo.resourceFailureInfo.items array<object> 리소스별 실패 상세입니다.
content.import_info.exportInfo.resourceFailureInfo.items[].resourceType string 리소스 유형입니다.
content.import_info.exportInfo.resourceFailureInfo.items[].resourceUUID string 또는 null 원본 리소스 UUID이며 비어 있을 수 있습니다.
content.import_info.exportInfo.resourceFailureInfo.items[].resourceName string 또는 null 표시 이름이며 비어 있을 수 있습니다.
content.import_info.exportInfo.resourceFailureInfo.items[].reasonCategory string permission 또는 other입니다.
content.import_info.exportInfo.resourceFailureInfo.items[].reasonCode string permission_denied/serialize_failed 등의 사유 코드입니다.
content.import_info.exportInfo.resourceFailureInfo.items[].affectedSloList array<object> 영향을 받은 SLO 목록입니다.
content.import_info.exportInfo.resourceFailureInfo.items[].affectedSloList[].sloUUID string SLO UUID입니다.
content.import_info.exportInfo.resourceFailureInfo.items[].affectedSloList[].sloName string 또는 null SLO 이름이며 비어 있을 수 있습니다.
content.import_info.convertedItems[].resourceType string 변환된 리소스 유형입니다.
content.import_info.convertedItems[].fileName string 변환 원본 설정 파일입니다.
content.import_info.convertedItems[].name string 변환된 인덱스 이름입니다.
content.import_info.convertedItems[].field string 변환 필드이며 현재 isFullLineIndex입니다.
content.import_info.convertedItems[].from JSON 원본 스키마 값, 예시 0입니다.
content.import_info.convertedItems[].to JSON 새 스키마 값, 예시 1입니다.
content.import_info.skippedItems[].indexName string 지원하지 않는 스키마의 원본/복제 인덱스 이름입니다.
content.import_info.skippedTags[].name string 건너뛴 태그 이름입니다.
content.import_info.skippedTags[].scope array 태그의 실제 scope 배열입니다.
content.import_info.skippedTags[].scope[] string 단일 범위 all/scene/monitor/dialing/security/infrastructure/catalog입니다.
content.import_info.authFailedCrossWsInfo[].name string 조회/참조된 원본 워크스페이스 이름입니다.
content.import_info.authFailedCrossWsInfo[].uuid string 원본 워크스페이스 UUID입니다.
content.import_info.authFailedCrossWsInfo[].checkerName string 크로스 워크스페이스 조회와 관련된 모니터 이름입니다.
content.import_info.skippedTags[].expectedScope string 이번 리소스에 필요한 태그 범위입니다.
content.import_info.skippedTags[].reason string 건너뛰기 사유 scope_mismatch입니다.
content.import_info.skippedTags[].resourceUUID string 연관 리소스 UUID이며 생략될 수 있습니다.
{
  "code": 200,
  "content": {
    "status": "ok",
    "action": "import",
    "error_code": null,
    "import_info": {
      "successCount": 3,
      "failCount": 0
    },
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}
{
  "code": 200,
  "content": {
    "status": null,
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.

작업 오류는 동적으로 반환됩니다. failedItems 매칭 분기에서 HTTP400의 errorCode는 error_code와 같습니다(ft.InternalServerError도 400으로 반환될 수 있음). 그 밖의 등록된 ft.*는 해당 비즈니스 상태를 사용하며, 일반 >=500은 ft.InternalServerError로 통일됩니다. 실제 HTTP, errorCode 및 오류 content.import_info를 기준으로 판단하고, 모든 작업 오류를 하나의 상태로 고정하지 마십시오.

HTTP 상태 errorCode 트리거 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 선언되지 않은 Query 파라미터를 사용했거나 파라미터가 규칙을 위반함 파라미터 파싱 실패 Query 파라미터 표와 예시를 확인하십시오.
406 ft.ParameterValidationFailed taskId가 비어 있음 파라미터 파싱 실패 유효한 원본 taskId를 입력하십시오.
403 ft.Forbidden 작업은 존재하지만 wksp_uuid 또는 creator가 현재 호출과 일치하지 않음(긴 작업 재생성 시 소유권이 누락된 캐시 포함) 작업 권한이 없습니다 원본 워크스페이스와 원본 Key의 리소스 주체를 사용하십시오. 주체가 올바른데도 403이면 taskId를 보관하고 관리자에게 만료/작업 로그 확인을 요청하십시오. 다른 관리 Key로 액세스해서는 안 됩니다.
400 ft.JsonFormatError 비동기 작업에 fileContentError 기록됨 일부 json 파일 형식 오류 리소스 패키지 내 해당 JSON을 수정하고, 이미 가져온 리소스를 확인한 후 다시 업로드하십시오.
500 ft.InternalServerError 작업 캐시/큐, 파일 시스템, 데이터베이스 또는 처리되지 않은 작업 상태/JSON 처리 실패 내부 오류 동일 워크스페이스, 동일 Key로 작업 및 리소스 현재 상태를 먼저 조회하여 대기열에 등록되었는지/부분 저장되었는지 확인한 후 재시도하고, 무작정 가져오기를 반복하거나 덮어쓰지 마십시오.

문서 평가

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