콘텐츠로 이동

멀티파트 업로드 초기화



POST /api/v1/rum_sourcemap/multipart_upload_init

개요

지정된 RUM 환경 및 버전의 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 등의 상태는 계속 확인해야 합니다.

먼저 로컬에서 전체 ZIP을 생성한 다음, 바이트 순서대로 각 파트가 10MiB를 초과하지 않도록 분할합니다. needCover=false이면 기본적으로 덮어쓰지 않습니다. 현재 환경/버전에 이미 레코드가 있으면 HTTP 200과 함께 uploadId="", existsSameFile=true가 반환되므로, 호출자는 먼저 기존 버전을 확인한 후 needCover=true로 다시 초기화할지 결정해야 하며, 빈 ID로 계속 업로드해서는 안 됩니다. 덮어쓰기는 새 세대를 사용하며, 업로드/압축 해제 검증이 완료된 후에만 게시된 콘텐츠를 교체합니다. needCover를 기존 디렉터리를 즉시 비우는 것으로 간주해서는 안 됩니다.

existsOldTask는 동일 범위에 이미 캐시가 있음을 감지한 것일 뿐, 해당 기존 작업을 계속할 수 있거나 이번에 쓰기 가능한 세션을 획득했음을 보장하지 않습니다. 동시 업로드/복구/정리 작업에서는 여전히 409가 발생할 수 있으므로 동시에 여러 번 초기화하지 마세요. 비어 있지 않은 uploadId가 반환되면 원래 값을 저장하세요. 세션은 기본 1시간이며 파트 요청으로 연장되지 않습니다. 최초 접근 시 기존 디렉터리/인덱스를 안전하게 인계하며, 기존 업로드/인덱스가 아직 완료되지 않은 경우 409 안내에 따라 대기하거나 관리자에게 확인을 요청하세요.

요청 헤더

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

Body 요청 파라미터

파라미터 이름 유형 필수 설명
appId string Y 현재 워크스페이스의 활성 애플리케이션 식별자를 필수로 입력합니다. 내부 RumCfg UUID가 아니며 워크스페이스 간에 사용할 수 없습니다.
null 허용: False
예: payment_web
가져오기 또는 입력 방법: RUM 애플리케이션 요약 목록의 content[].appId 또는 오류 레코드의 app_id에서 가져옵니다.
env string 선택적 문자열이며 기본값은 빈 환경이고 최대 256자입니다. 모든 환경을 의미하지 않으며 null은 허용되지 않습니다.
빈 문자열 허용: True
null 허용: False
예: production
가져오기 또는 입력 방법: 클라이언트가 배포한 환경/오류 레코드의 env에서 가져오며, 업로드 시와 문자 단위로 일치해야 합니다.
needCover boolean 선택적 boolean이며 기본값은 false입니다. false인 경우 이미 게시된 레코드를 만나면 확인용으로 빈 uploadId를 반환합니다. true이면 교체 세대를 준비할 수 있지만 동시성/소유권/이력 안전 제한이 계속 적용되며 다른 환경/버전을 덮어쓰지 않습니다.
null 허용: False
예: false
가져오기 또는 입력 방법: 먼저 버전 목록을 조회하여 해당 환경/버전 교체가 허용되는지 확인합니다.
version string 선택적 문자열이며 기본값은 빈 버전이고 최대 256자입니다. 최신/모든 버전을 의미하지 않으며 null은 허용되지 않습니다.
빈 문자열 허용: True
null 허용: False
예: 1.2.3
가져오기 또는 입력 방법: 클라이언트가 실제 배포한 버전/오류 레코드의 version에서 가져오며 빌드 산출물과 대응해야 합니다.

파라미터 추가 설명

흐름은 SourceMap 멀티파트 업로드 관련 인터페이스 사용 설명을 참조하고, 멀티파트 업로드 작업 문서도 참고할 수 있습니다. 초기화 → 원본 ZIP의 모든 파트 업로드 → 파트 목록 확인 → 병합 → 버전 상태 및 파일 트리 조회 순으로 진행합니다. 초기화/병합 성공이 ZIP이 검증되었거나 파싱 가능함을 의미하지는 않습니다. processing/failed/blocked 등의 상태는 계속 확인해야 합니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/rum_sourcemap/multipart_upload_init' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"appId":"payment_web","env":"production","version":"1.2.3","needCover":false}'

응답

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

필드 유형 설명
content.uploadId string 비어 있지 않은 경우에만 파트 업로드를 계속할 수 있습니다. 기존 버전이 있고 덮어쓰지 않는 경우에는 빈 문자열입니다.
content.existsOldTask boolean 동일 범위에 기존 작업 캐시가 있음을 알리는 표시이며, 세션 유효성/성공적인 덮어쓰기를 보장하지 않습니다.
content.existsSameFile boolean 현재 이미 버전 레코드가 있음을 알리는 표시이며, 모든 원본 파일이 검증되었음을 의미하지는 않습니다.
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",
    "existsOldTask": false,
    "existsSameFile": false,
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}
{
  "code": 200,
  "content": {
    "uploadId": "",
    "existsOldTask": false,
    "existsSameFile": true,
    "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 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다 파라미터 파싱 실패 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않습니다 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정합니다.
400 ft.JsonFormatError JSON 최상위가 객체가 아닙니다 일부 json 파일 형식 오류 객체를 제출합니다.
404 ft.NotFoundRumSet 애플리케이션이 현재 워크스페이스에 없거나 삭제되었거나 존재하지 않습니다 지정된 RUM 설정을 찾을 수 없습니다 RUM 애플리케이션 요약 목록을 새로 고치고 현재 워크스페이스의 실제 appId를 사용합니다.
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자인지 확인합니다.
500 ft.InternalServerError 데이터베이스, Redis, 스토리지 읽기/쓰기, 큐 또는 처리되지 않은 시스템 예외 내부 오류 traceId, 애플리케이션/env/version/uploadId를 보존하고 먼저 목록/파일 트리를 확인합니다. 실패 시 이미 파일이 게시되었거나 처리 표시가 있을 수 있으므로 무작정 다시 덮어쓰거나 삭제하지 마세요.

문서 평가

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