워크스페이스 리소스 작업 취소¶
POST /api/v1/workspace/resource/cancel
개요¶
현재 워크스페이스에서 본인이 시작한 리소스 처리 작업의 취소를 요청합니다.
호출 전 및 사용 단계¶
현재 Key에는 workspace.setManage 권한이 필요합니다. 작업은 현재 워크스페이스와 생성한 Key의 리소스 UUID에만 속하며, 같은 워크스페이스의 다른 Key는 역할이 동일하더라도 해당 작업을 읽거나 취소할 수 없습니다. 동일 Key를 로테이션해도 리소스 UUID는 유지되며, taskId와 API Key 값을 혼용해서는 안 됩니다.
작업 캐시가 여전히 존재하는 경우에만 status를 cancel로 변경하며, 백그라운드에서는 리소스 모듈 경계에서 협력 검사를 수행합니다. 현재 실행 중인 단일 작업을 강제로 종료하지 않고, 이미 제출된 리소스나 이미 기록된 파일을 되돌리지 않으며, 모든 후속 부작용의 발생을 차단한다고 보장하지도 않습니다. 작업 캐시가 전혀 존재하지 않아도 여전히 status=cancel을 반환하며, 실제 작업 적중 카운트는 없습니다.
이미 완료된 작업도 cancel로 표시될 수 있습니다. 작업 스레드와 취소는 경쟁할 수 있으므로 이후 상태가 ok/error로 바뀔 수 있으며, 이 응답만으로 취소 또는 롤백이 완료되었음을 증명할 수 없습니다. 호출 후에도 동일한 Key로 계속 진행 상황을 조회하고 대상 리소스를 확인해야 하며, 특히 recover 가져오기에서 이미 일부가 저장된 경우에는 더욱 그렇습니다. 이 엔드포인트는 원본 비즈니스 데이터를 삭제하지 않습니다. 내보내기 파일이 이미 게시되었는지는 다시 읽어 확인해야 합니다.
취소 또는 중단 후 이어서 noJsonDataError 또는 빈 성공 카운트가 반환되더라도, 이전 모듈에서 이미 저장이 완료되었을 수 있습니다. 해당 지역화 메시지는 기록이 없음을 증명하지 못합니다.
요청 헤더¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Body 요청 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| taskId | string | Y | 필수이며 비어 있을 수 없는 작업 ID입니다. 작업을 생성한 동일 워크스페이스, 동일 Key 리소스 신원을 사용해야 하며 파일명이 아닙니다. null 허용: False 예시: resource_task_example획득 또는 입력 방법: 리소스 내보내기 작업 또는 리소스 패키지 가져오기 응답의 content.taskId에서 획득합니다. |
파라미터 추가 설명¶
1. 인터페이스 용도
실행 중인 워크스페이스 리소스 가져오기 또는 내보내기 작업을 취소합니다.
2. 사용 설명
가져오기/내보내기 인터페이스를 통해 획득한 taskId를 전달해야 합니다.
취소 요청이 성공적으로 제출되면 인터페이스는 다음을 반환합니다.
설명:
- 해당 반환은 작업이 취소로 표시되었음을 의미합니다
- 구체적인 작업의 최종 상태는 작업 상태 인터페이스를 통해 계속 확인할 수 있습니다
3. 주의 사항
- 이미 실행이 완료된 작업은 되돌릴 수 없습니다
- 일부가 성공적으로 실행된 가져오기 작업은 이미 기록된 데이터를 자동으로 롤백하지 않습니다
- 취소가 적용되었는지 확인해야 하는 경우 작업 상태 인터페이스를 계속 폴링하세요
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/resource/cancel' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"taskId":"resource_task_example"}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content.status | string | 고정 값 cancel이며, 취소 요청 처리가 완료되었음만 의미하고 일치하는 작업이 없을 수 있습니다. |
| content.declaration | object | 현재 워크스페이스의 공통 선언입니다. |
{
"code": 200,
"content": {
"status": "cancel",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하세요.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 타입 및 값을 확인하세요. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 문법이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하세요. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | taskId를 포함한 객체를 제출하세요. |
| 403 | ft.Forbidden | 존재하는 작업이 현재 워크스페이스 또는 현재 생성 Key에 속하지 않거나, 장기 작업의 재구축 상태 캐시에 소유권 정보가 누락됨 | 작업 권한이 없습니다 | 원래 워크스페이스와 원래 생성 Key를 사용하고, 신원을 넘어 취소하지 마세요. 신원이 올바른데도 403이 발생하면 taskId를 보관하고 관리자에게 장기 작업 캐시와 로그를 확인하도록 요청하세요. |
| 500 | ft.InternalServerError | 작업 캐시/큐, 파일 시스템, 데이터베이스 또는 처리되지 않은 작업 상태/JSON 처리 실패 | 내부 오류 | 먼저 동일 워크스페이스의 동일 Key로 작업 및 리소스 현재 상태를 조회하여 대기열 등록/부분 저장 여부를 확인한 후 재시도하고, 가져오기나 덮어쓰기를 무작정 반복하지 마세요. |