파트 병합으로 파일 생성¶
POST /api/v1/rum_sourcemap/part_merge
개요¶
업로드된 번호 순서대로 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 등의 상태는 계속 확인해야 합니다.
chunkIndexs는 호환성 선언이며 현재 병합 컨트롤러는 이 배열을 읽지 않습니다. 실제로는 해당 세션 디렉터리의 모든 숫자 번호를 스캔하여 정수 기준으로 정렬해 병합하며, 이를 사용해 일부 파트를 선택하거나 순서를 조정하거나 전체 파트 수를 선언할 수 없습니다. 호스팅 경로에는 파트가 최소 하나 있어야 하고 번호는 연속되어야 하지만, 시작 값이 0일 필요는 없습니다. 호출자는 여전히 기대하는 모든 파트가 업로드되었는지 확인해야 하며, 연속성만으로 마지막 파트 누락이 없다는 것이 증명되지는 않습니다.
정상적인 새 세션은 content.state=processing을 반환하며 작업 ID나 완료된 진행률은 반환하지 않습니다. 이전 호환 세션은 {}를 반환할 수 있습니다. 백그라운드에서 안전한 압축 해제, 용량 및 Web .map 콘텐츠 검증을 수행한 후에만 새 세대를 게시합니다. 실패 시 이전에 게시된 버전을 유지하고 failed/reasonCode를 기록할 수 있습니다. ZIP에는 경로 트래버설/링크/디바이스 파일이 포함되어서는 안 되며, 기본 압축 해제 파일 총량은 최대 2GiB입니다(사이트에서 변경 가능). Web은 실제로 유효한 version=3 SourceMap이어야 하며, 임의의 JSON의 이름만 .map으로 변경해서는 안 됩니다.
큐 전달에 실패하면 디스크에 기록된 병합 마커를 유지하여 주기적으로 복구할 수 있으며, 인터페이스는 여전히 성공을 반환할 수 있습니다. 일시적으로 processing이라는 이유만으로 초기화를 반복해 덮어쓰지 마십시오. 병합 마커가 설정된 후에는 파트 쓰기/취소가 보호됩니다. 버전 목록과 파일 트리를 읽어 게시를 확인하고 실제 파싱으로 검수하십시오. 이 요청은 범용 멱등 작업이 아닙니다. 중복 병합은 거부되거나 중복 대기열에 추가될 수 있으므로, 네트워크 결과를 알 수 없으면 먼저 현재 상태를 조회하십시오.
요청 헤더¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Body 요청 파라미터¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| chunkIndexs[*] | integer | 호환 번호 요소이며 정수를 권장합니다. 이 파라미터는 실제 스캔 및 병합에 참여하지 않습니다. 예: 0획득 또는 입력 방법: 업로드된 파트 목록과 동일합니다. |
|
| chunkIndexs | array | 선택적 배열이며 현재 구현에서는 무시합니다. 병합 범위를 제어하거나 클라이언트의 무결성 검사를 대체할 수 없으므로 생략을 권장합니다. 빈 문자열 허용: False null 허용: False 예: [0, 1, 2]획득 또는 입력 방법: part_list에서 저장된 번호를 가져올 수 있지만 현재는 이 호환 필드를 제출할 필요가 없습니다. |
|
| uploadId | string | Y | 필수 업로드 세션 ID입니다. 직접 연결하거나 taskId로 대체하지 마십시오. 동일 워크스페이스에서 관리 권한이 있는 Key는 계속 사용할 수 있으며 생성한 Key 기준으로 격리되지 않습니다. 세션 기본값은 3600초이며 파트 업로드는 자동으로 갱신되지 않습니다. 만료되었거나 새 세션으로 덮어쓰인 경우 확인 후 다시 초기화해야 합니다. null 허용: False 예: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb획득 또는 입력 방법: 초기화 파트 업로드 성공 응답의 content.uploadId를 그대로 저장합니다. |
파라미터 추가 설명¶
흐름은 SourceMap 파트 업로드 관련 인터페이스 사용 설명을 참고하고, 파트 업로드 작업 문서도 참고할 수 있습니다. 초기화 → 원본 ZIP의 모든 파트 업로드 → 파트 목록 확인 → 병합 → 버전 상태와 파일 트리 조회 순서로 진행합니다. 초기화/병합 성공이 ZIP이 검증되었거나 파싱 가능함을 의미하지는 않습니다. processing/failed/blocked 등의 상태는 계속 확인해야 합니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/rum_sourcemap/part_merge' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"uploadId":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}'
응답¶
HTTP 200, application/json입니다. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.state | string | 성공적인 호스팅 응답은 processing으로 고정되며 비동기 처리가 예약되었음을 나타냅니다. 일부 오류 진단에서도 state로 당시 세대 상태를 나타낼 수 있습니다. |
| 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.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": {
"state": "processing",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
{
"code": 200,
"content": {},
"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 | 세션 캐시가 만료되었거나 대체됨, 대상 세대 상태가 병합을 허용하지 않음, 또는 파트가 없거나 숫자 인덱스가 연속되지 않음 | 유효하지 않은 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를 보존하고 먼저 목록/파일 트리를 확인하십시오. 실패했더라도 파일이 이미 게시되었거나 처리 마커가 있을 수 있으므로 무작정 다시 덮어쓰거나 삭제하지 마십시오. |