멀티파트 업로드 이벤트 취소¶
POST /api/v1/rum_sourcemap/upload_cancel
개요¶
아직 병합 및 게시 단계에 진입하지 않은 SourceMap 멀티파트 세션을 취소합니다.
호출 전 준비 및 사용 단계¶
현재 Key에는 rum.rumCfgManage 권한이 필요합니다. 현재 Key가 속한 워크스페이스에서만 가능합니다. appId는 RUM 애플리케이션 목록 content[].appId에서 가져오며, SDK/오류 기록의 app_id와 일치해야 하고 데이터베이스 내부 UUID로 대체할 수 없습니다. SourceMap은 애플리케이션, 환경 env, 버전 version으로 정확히 지정되며, 대소문자/공백은 식별자 자체에 속하므로 수집 기록과 완전히 일치해야 합니다. env/version을 생략하거나 빈 문자열로 두면 빈 환경/빈 버전을 의미하며, 전체 와일드카드가 아닙니다. 현재 호스팅 수명 주기는 각각 최대 256자까지 허용합니다.
절차는 SourceMap 멀티파트 업로드 관련 API 사용 설명을 참고하고, 멀티파트 업로드 작업 문서도 참고할 수 있습니다. 초기화 → 원본 ZIP 파트 전체 업로드 → 파트 목록 확인 → 병합 → 버전 상태 및 파일 트리 조회 순서로 진행합니다. 초기화/병합 성공이 ZIP이 검증되었거나 파싱 가능함을 의미하지는 않습니다. processing/failed/blocked 등의 상태는 계속 확인해야 합니다.
취소는 해당 uploadId가 속한 업로드 세대에만 적용되며, 이전에 게시된 동일 환경/버전을 삭제하지 않고 게시된 파일도 회수하지 않습니다. 병합되지 않은 세션은 업로드 실패로 표시되고 임시 파트 정리가 예약되며, 쓰기 중인 파트는 자연스럽게 종료되어야 하고 디렉터리는 나중에 회수될 수 있습니다. 병합 표시가 이미 생성된 경우 409가 발생할 수 있으며, 취소 API로 게시를 강제 중단할 수 없습니다.
캐시가 없거나 만료되었거나 더 이상 현재 작업과 일치하지 않는 경우에도 true를 반환할 수 있으며, 일치 건수가 없으므로 true만으로 실제 작업이 취소되었다고 판단할 수 없습니다. 이전 취소를 반복해도 이후 생성된 새 세션의 캐시를 지울 수 없습니다. 취소 후 먼저 버전 목록과 파트/파일 상태를 확인한 뒤 재초기화 여부를 결정합니다. 응답은 모든 파일/공간 해제가 완료되었음을 보장하지 않습니다.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>취득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| uploadId | string | Y | 필수 업로드 세션 ID로, 직접 조합하거나 taskId로 대체하지 않습니다. 동일 워크스페이스에서 관리 권한이 있는 Key는 계속 사용할 수 있으며, Key 생성 기준으로 격리되지 않습니다. 세션 기본값은 3600초이고 멀티파트 업로드는 자동 갱신되지 않습니다. 만료되었거나 새 세션으로 덮어쓰인 경우 확인 후 다시 초기화해야 합니다. null 허용: False 예: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb취득 또는 입력 방법: 멀티파트 업로드 초기화 성공 응답의 content.uploadId를 그대로 저장합니다. |
파라미터 추가 설명¶
절차는 SourceMap 멀티파트 업로드 관련 API 사용 설명을 참고하고, 멀티파트 업로드 작업 문서도 참고할 수 있습니다. 초기화 → 원본 ZIP 파트 전체 업로드 → 파트 목록 확인 → 병합 → 버전 상태 및 파일 트리 조회 순서로 진행합니다. 초기화/병합 성공이 ZIP이 검증되었거나 파싱 가능함을 의미하지는 않습니다. processing/failed/blocked 등의 상태는 계속 확인해야 합니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/rum_sourcemap/upload_cancel' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"uploadId":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | boolean | 항상 true이며, 이 취소 요청이 처리되었음만 의미합니다. 실제로 일치하는 세션이 없을 수 있습니다. |
| content.reasonCode | string | 오류 응답에만 해당: 기계가 판독할 수 있는 사유입니다. 예: active_operation/invalid_scope/registry_missing. |
| content.action | string | 오류 응답에만 해당: 권장 조치입니다. 예: retry_after_operation/verify_ownership/check_scope_and_upload. |
| content.retryable | boolean | 오류 응답에만 해당: 서버가 제안하는 재시도 가능 플래그로, 이것만으로 이미 게시된 쓰기를 재생할 수 없습니다. |
| content.uploadCommitted | boolean | 일부 단일 파일 오류 진단에만 해당: true는 해당 쓰기가 게시 확인되었음을 의미합니다. 생략은 false 또는 미기록 확인을 뜻하지 않습니다. |
| content.actualBytes | integer | 일부 용량 오류에만 해당: 집계된 바이트 수입니다. |
| content.maxBytes | integer | 용량/읽기 제한 바이트 수입니다. |
| content.workspaceUUID | string | 일부 오류의 제한적 진단: 현재 워크스페이스 UUID입니다. |
| content.appId | string | 일부 오류의 제한적 진단: 공개 애플리케이션 식별자입니다. |
| content.rumCfgUUID | string | 일부 오류의 제한적 진단: 내부 애플리케이션 식별자로, 지원 문제 해결에만 사용되며 요청의 appId를 대체하지 않습니다. |
| content.env | string | 일부 오류 진단: 환경입니다. |
| content.version | string | 일부 오류 진단: 버전입니다. |
| content.bundleUUID | string | 일부 오류 진단: 이번 세대의 기록 ID이며 uploadId가 아닙니다. |
| content.state | string | 일부 오류 진단: 세대 상태입니다. |
| content.resource | string | 일부 점유 진단: 리소스 유형입니다. 예: application/bundle. |
| content.shared | boolean | 일부 점유 진단: 공유 액세스 여부입니다. |
| content.waitedSeconds | number | 일부 점유 진단: 대기한 초 수입니다. |
| content.waitSeconds | number | 일부 점유 진단: 허용된 대기 초 수입니다. |
| content.waitExhausted | boolean | 일부 점유 진단: 이번 대기가 소진되었는지 여부입니다. |
| content.elapsedSeconds | number | 일부 단일 파일 오류 진단: 작업 소요 초입니다. |
| content.phase | string | 일부 오류 진단: 실패 단계입니다. |
| content.phaseElapsedSeconds | number | 일부 오류 진단: 단계 소요 초입니다. |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.
스토리지 수명 주기는 호환 오류 코드를 유지합니다. 409는 일반적으로 여전히 ft.InvalidAction이며, 로컬라이즈된 message와 content.reasonCode가 원인을 추가로 구분합니다. message 이름인 SourceMapOperationBusy 등을 반드시 errorCode로 간주하지 않습니다. 읽기 시 패키지 누락/처리 중/사용 불가인 경우 흔히 404 ft.SourceMapPackageNotFound이며, 구체적인 원인은 reasonCode를 확인합니다. retryable=true가 명확히 반환되고 현재 상태가 허용할 때만 백오프 후 재시도합니다. uploadCommitted=true인 경우 게시가 확인된 쓰기를 재생할 수 없습니다.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 유형 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | uploadId 객체를 제출합니다. |
| 404 | ft.NotFoundRumSet | 애플리케이션이 현재 워크스페이스에 없거나 삭제되었거나 존재하지 않음 | 지정한 RUM 설정을 찾을 수 없음 | RUM 애플리케이션 목록을 새로 고치고 현재 워크스페이스의 실제 appId를 사용합니다. |
| 406 | ft.InvalidUploadId | 캐시가 여전히 일치하는 상태에서 연관 세대가 더 이상 취소를 허용하지 않거나 대체되었거나, 이전 세션이 이미 호스팅된 애플리케이션 상태와 충돌함. 캐시가 전혀 일치하지 않으면 true일 수 있음 | 유효하지 않은 UploadId 값 또는 작업이 이미 덮어쓰임 | 원본 uploadId와 업로드된 파트를 확인하고, 이전 세션과 게시 상태를 확인한 뒤 재초기화하며 무작정 덮어쓰지 않습니다. |
| 409 | ft.InvalidAction | 업로드/읽기/정리 충돌, 이전 디렉터리 인수 미완료, 소유권/복구 확인 대기 또는 환경 버전이 수명 주기 허용 범위를 초과함 | reasonCode에 따라 구체적인 로컬라이즈 메시지를 반환합니다. 예: SourceMap이 다른 업로드, 읽기 또는 정리 작업에서 사용 중 | content.reasonCode/action/retryable을 확인합니다. active_operation/active_upload 등은 안내에 따라 백오프하고, owner_recovery_required/ownership_verification_required/legacy_invalid 등은 먼저 관리자에게 확인을 요청하며 점유 기록을 임의로 삭제하거나 강제로 덮어쓰지 않습니다. invalid_scope인 경우 env/version이 최대 256자인지 확인합니다. |
| 406 | ft.InvalidFileName | 파일 상대 경로, 심볼릭 링크 또는 과거 게시 경로가 안전하지 않음 | SourceMap 파일 경로가 요구 사항을 충족하지 않거나 지원되지 않는 링크를 포함합니다. 업로드 파일의 상대 경로와 디렉터리 구조를 확인하십시오. | 패키지 내의 유효한 상대 경로를 사용하고 .., 백슬래시, 절대 경로/심볼릭 링크를 포함하지 않도록 합니다. reasonCode=invalid_path를 확인합니다. |
| 500 | ft.InternalServerError | 데이터베이스, Redis, 스토리지 읽기/쓰기, 큐 또는 처리되지 않은 시스템 예외 | 내부 오류 | traceId, 애플리케이션/env/version/uploadId를 보관하고 먼저 목록/파일 트리를 확인합니다. 실패 시 이미 파일이 게시되었거나 처리 표시가 있을 수 있으므로 무작정 다시 덮어쓰거나 삭제하지 않습니다. |