단일 청크 업로드¶
POST /api/v1/rum_sourcemap/upload_part
개요¶
SourceMap ZIP의 바이트 청크 하나를 업로드합니다.
호출 전 및 사용 단계¶
현재 Key에는 rum.rumCfgManage 권한이 필요합니다. 현재 Key가 속한 워크스페이스만 대상으로 합니다. appId는 RUM 애플리케이션 요약 목록의 content[].appId에서 가져오며, SDK/오류 기록의 app_id와 일치해야 합니다. 데이터베이스 내부 UUID로 대체할 수 없습니다. SourceMap은 애플리케이션, 환경 env 및 버전 version으로 정확하게 식별됩니다. 대소문자/공백은 식별자 자체에 속하므로 수집 기록과 완전히 일치해야 합니다. env/version을 생략하거나 빈 문자열로 두면 빈 환경/빈 버전을 의미하며, 전체를 와일드카드로 지정하는 것이 아닙니다. 현재 호스팅 수명 주기에서는 각각 최대 256자여야 합니다.
프로세스는 SourceMap 청크 업로드 관련 인터페이스 사용 설명을 참조하고, 청크 업로드 작업 문서도 참고할 수 있습니다. 초기화 → 원본 ZIP의 모든 슬라이스 업로드 → 청크 목록 확인 → 병합 → 버전 상태 및 파일 트리 조회 순서로 진행합니다. 초기화/병합 성공이 ZIP이 검증되었거나 파싱 가능함을 의미하지는 않습니다. processing/failed/blocked 등의 상태는 계속 확인해야 합니다.
multipart/form-data를 사용하며, 일반 Form 필드는 uploadId/chunkIndex이고 파일 필드는 files입니다. JSON을 전송하지 않습니다. files는 원본 ZIP의 연속된 바이트 한 조각이며, 단일 청크는 최대 10MiB입니다. .zip 파일 이름을 사용하여 선언을 충족하며, 이때 서버는 각 청크 자체가 독립적으로 압축 해제 가능한 ZIP일 것을 요구하지 않습니다. 원본 ZIP 순서대로 번호를 지정하며, 0부터 연속으로 번호를 지정하는 것이 좋습니다. 여러 개의 독립 ZIP을 하나의 청크로 사용해서는 안 됩니다.
동일한 uploadId+정수 chunkIndex는 해당 청크를 대체하므로, 재시도 시에는 완전히 동일한 바이트만 전송하여 동시에 같은 번호를 덮어쓰는 것을 피하십시오. 숫자 문자열은 정수로 변환되며, 00과 0은 동일한 인덱스입니다. 선행 0으로 구분하는 것에 의존하지 마십시오. 이미 병합 게시 단계에 들어간 경우 추가 청크 쓰기가 금지되며 409가 발생할 수 있습니다. 세션이 만료되었거나 대체되었거나 대상 세대에 쓸 수 없으면 406입니다. 성공은 해당 청크가 저장되었음만 증명하며, 모든 청크, 전체 ZIP 또는 SourceMap 내용이 유효함을 증명하지는 않습니다.
요청 헤더¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Form 매개변수¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| chunkIndex | digitsString | Y | 클라이언트는 음수가 아닌 10진수 숫자 문자열을 사용해야 합니다. 현재 digitsString 유형 인식에는 호환성 갭이 있어 숫자가 아닌 값을 강제로 차단하지 않습니다. abc/1.2 등은 int 변환 시 500이 발생할 수 있습니다. 음수는 호스팅 로직에서 406입니다. 명시적 빈 문자열은 현재 0으로 호환 처리됩니다. 이러한 예외 값 동작에 의존하지 마십시오. 원본 파일 이름/UUID를 인덱스 대신 사용할 수 없습니다. 빈 문자열 허용: False null 허용: False 예: 0가져오기 또는 입력 방법: 호출자의 슬라이스 목록에서 생성하며, 원본 ZIP 순서에 따라 0부터 증가합니다. |
| uploadId | string | Y | 필수 업로드 세션 ID입니다. 직접 조합하지 말고 taskId로 대체하지 마십시오. 동일 워크스페이스에서 관리 권한이 있는 Key는 계속 사용할 수 있으며, 생성한 Key 기준으로 격리되지 않습니다. 세션 기본값은 3600초이며, 청크 업로드 시 자동으로 갱신되지 않습니다. 만료되었거나 새 세션으로 대체된 경우 확인 후 다시 초기화해야 합니다. null 허용: False 예: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb가져오기 또는 입력 방법: 청크 업로드 초기화 성공 응답의 content.uploadId를 그대로 저장합니다. |
파일 매개변수(multipart/form-data)¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| files | file | Y | 파일 1개가 필수이며 .zip 확장자입니다(빈 파일 이름을 허용하는 호환성 선언). 동일 청크에는 독립적인 ZIP 구조가 필요하지 않으며, 업로드 시 바이트를 변경해서는 안 됩니다. 빈 파일 이름 허용: True 허용 파일 확장자: ['zip'] 단일 파일 최대 크기: 10M 최대 파일 수: 1 예: part-000.zip가져오기 또는 입력 방법: 로컬의 전체 ZIP을 원본 바이트 순서대로 분할하며, 각 청크는 10MiB를 초과하지 않아야 합니다. |
매개변수 추가 설명¶
프로세스는 SourceMap 청크 업로드 관련 인터페이스 사용 설명을 참조하고, 청크 업로드 작업 문서도 참고할 수 있습니다. 초기화 → 원본 ZIP의 모든 슬라이스 업로드 → 청크 목록 확인 → 병합 → 버전 상태 및 파일 트리 조회 순서로 진행합니다. 초기화/병합 성공이 ZIP이 검증되었거나 파싱 가능함을 의미하지는 않습니다. processing/failed/blocked 등의 상태는 계속 확인해야 합니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/rum_sourcemap/upload_part' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-F 'uploadId=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb' \
-F 'chunkIndex=0' \
-F 'files=@./part-000.zip'
응답¶
HTTP 200, application/json입니다. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.uploadId | string | 현재 세션 ID입니다. |
| content.chunkIndex | integer | 실제 저장된 정수 청크 번호입니다. |
| content.declaration | object | 현재 워크스페이스 공통 선언입니다. |
| 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": {
"uploadId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"chunkIndex": 0,
"declaration": {}
},
"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 | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 매개변수 파싱 실패 | 매개변수 위치, 필드 이름, 유형 및 값을 확인하십시오. |
| 404 | ft.NotFoundRumSet | 애플리케이션이 현재 워크스페이스에 없거나 삭제되었거나 존재하지 않음 | 지정한 RUM 설정을 찾을 수 없습니다. | RUM 애플리케이션 요약 목록을 새로 고치고 현재 워크스페이스의 실제 appId를 사용하십시오. |
| 406 | ft.InvalidUploadId | 세션 캐시가 없거나 만료되었거나 대체되었거나, 대상 세대 상태/작업 ID가 일치하지 않거나 쓰기 단계가 취소되었습니다. 호스팅 음수 인덱스도 거부합니다. | 유효하지 않은 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 | 숫자가 아닌 chunkIndex(예: abc/1.2)가 현재 유형 인식을 통과한 후 int 변환에 실패했거나, 처리되지 않은 파일/캐시/데이터베이스 예외가 있음 | 내부 오류 | 음수가 아닌 10진수 번호만 전달하십시오. 저장 예외가 발생하면 먼저 part_list를 조회하여 해당 청크가 저장되었는지 확인한 후 동일한 바이트로 재시도하십시오. |