단일 파일 콘텐츠 업로드¶
POST /api/v1/rum_sourcemap/upload_file_content
개요¶
지정된 환경 및 버전 아래의 SourceMap 관련 텍스트 파일 하나를 기록합니다.
호출 전 및 사용 단계¶
현재 Key에는 rum.rumCfgManage 권한이 필요합니다. 현재 Key가 속한 워크스페이스에서만 사용할 수 있습니다. appId는 RUM 애플리케이션 요약 목록의 content[].appId에서 가져오며, SDK/오류 기록의 app_id와 일치해야 하고 데이터베이스 내부 UUID로 대체할 수 없습니다. SourceMap은 애플리케이션, 환경 env 및 버전 version으로 정확히 특정됩니다. 대소문자/공백은 식별자 자체에 속하므로 수집 기록과 완전히 일치해야 합니다. env/version을 생략하거나 빈 문자열로 두면 빈 환경/빈 버전을 의미하며, 모든 환경/버전을 나타내는 와일드카드가 아닙니다. 현재 호스팅 수명 주기에서는 각각 최대 256자여야 합니다.
이 엔드포인트는 JSON 텍스트 콘텐츠를 받으며, multipart ZIP도 아니고 Base64 바이너리도 아닙니다. filename은 패키지 내 상대 경로입니다(예: static/js/app.js.map). 선행 /는 호환을 위해 제거할 수 있지만 .., 백슬래시 및 안전하지 않은 링크는 금지되므로 항상 정규화된 상대 경로를 전달하는 것이 좋습니다. content는 UTF-8 원문 그대로 인코딩되며, 현재 호스팅 경로에서는 앞뒤 공백/줄바꿈을 유지하고 JSON 문자열을 다시 파일 객체로 디코딩하지 않습니다. content를 생략하면 빈 문자열이 기록되며, 성공했다고 해서 파일을 파싱할 수 있음이 증명되지는 않습니다.
같은 이름의 파일이 이미 존재하면 해당 파일을 대체하고 나머지 파일은 유지됩니다. 여러 파일을 하나씩 업로드할 수 있지만 이는 원자적인 전체 패키지 게시가 아니므로, 업로드 중 읽기 작업에서 이미 게시된 일부 파일만 보일 수 있습니다. 단일 파일 및 해당 버전에서 집계된 총용량은 사이트 제한(기본 2GiB)을 받습니다. 빌드 산출물의 일관성을 유지하려면 ZIP 일괄 업로드를 권장합니다. Web/RN의 경우 실제 빌드에서 생성된 .map 및 필요한 소스/JS를 업로드해야 하며, Android/iOS 네이티브 바이너리 심볼은 ZIP 흐름이 더 적합합니다.
성공 시 true는 이번 파일 쓰기가 확인되었음을 나타내며, 이후 인덱싱/안정화 기간/정리 복구는 비동기로 완료될 수 있습니다. 작업이 실패해도 uploadCommitted=true가 포함될 수 있으므로, 게시가 확인된 쓰기를 재전송하지 마십시오. 409 소유권/복구가 확인되지 않은 경우 traceId를 보존하고 관리자에게 처리를 요청하며, 점유 상태를 삭제하거나 무작정 재전송하지 마십시오. 완료 후 파일 트리로 확인하고 스택 파싱으로 실제 일치 여부를 검증하십시오. 목록에 레코드가 있다고 해서 map 내용이 올바른 것은 아닙니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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에서 가져옵니다. |
| content | string | 선택적 문자열이며 생략하면 빈 문자열이고 원본 UTF8 텍스트를 유지합니다. Base64 디코딩을 수행하지 않으며 빈 map 업로드는 권장하지 않습니다. 빈 문자열 허용: True null 허용: False 예: {"version":3,"sources":["app.ts"],"names":[],"mappings":"AAAA","sourcesContent":["console.log(1);"]}가져오기 또는 입력 방법: 해당 버전 빌드에서 생성된 텍스트 SourceMap 내용을 읽어 JSON 문자열로 직렬화합니다. |
|
| env | string | 선택적 문자열이며 기본값은 빈 환경이고 최대 256자입니다. 모든 환경을 의미하지 않으며 null은 허용되지 않습니다. 빈 문자열 허용: True null 허용: False 예: production가져오기 또는 입력 방법: 클라이언트 게시 환경/오류 기록의 env에서 가져오며 업로드 시와 글자 단위로 일치해야 합니다. |
|
| filename | string | Y | 필수이며 비어 있지 않은 유효한 상대 파일 경로입니다. POSIX / 구분자를 권장합니다. 선행 /는 호환을 위해 제거되며 경로 내 .., 백슬래시/링크 등은 거부됩니다. 클라이언트의 절대 디스크 경로를 전달할 수 없습니다. 빈 문자열 허용: True null 허용: False 예: static/js/app.js.map가져오기 또는 입력 방법: 빌드 산출물의 상대 경로 및 오류 스택의 소스 URL 경로에서 결정합니다. |
| version | string | 선택적 문자열이며 기본값은 빈 버전이고 최대 256자입니다. 최신/모든 버전을 의미하지 않으며 null은 허용되지 않습니다. 빈 문자열 허용: True null 허용: False 예: 1.2.3가져오기 또는 입력 방법: 클라이언트의 실제 게시 버전/오류 기록의 version에서 가져오며 빌드 산출물과 대응해야 합니다. |
파라미터 추가 설명¶
참고: 동일한 애플리케이션 아래에는 동일한 version, env의 sourcemap이 하나만 존재할 수 있습니다. 업로드한 파일 내용은 대상 파일을 직접 덮어씁니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/rum_sourcemap/upload_file_content' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"appId":"payment_web","env":"production","version":"1.2.3","filename":"static/js/app.js.map","content":"{\"version\":3,\"sources\":[\"app.ts\"],\"names\":[],\"mappings\":\"AAAA\",\"sourcesContent\":[\"console.log(1);\"]}"}'
응답¶
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 파일 형식 오류 | appId/filename을 포함한 객체를 제출합니다. |
| 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자인지 확인합니다. |
| 406 | ft.InvalidFileName | 파일 상대 경로, 심볼릭 링크 또는 이전 게시 경로가 안전하지 않음 | SourceMap 파일 경로가 요구 사항을 충족하지 않거나 지원되지 않는 링크를 포함합니다. 업로드 파일의 상대 경로와 디렉터리 구조를 확인하십시오. | 패키지 내 유효한 상대 경로를 사용하고 .., 백슬래시, 절대 경로/심볼릭 링크를 포함하지 마십시오. reasonCode=invalid_path를 확인합니다. |
| 413 | ft.SourceMapUploadTooLarge | 단일 파일 또는 집계된 버전 총용량이 사이트 제한(기본 2147483648바이트)을 초과함 | SourceMap의 이번 업로드 또는 집계된 버전 용량이 제한을 초과합니다(구체적인 바이트 수는 content 참조). | 해당 환경/버전 파일 총량을 줄이고 content.actualBytes/maxBytes를 읽거나 관리자에게 제한 확인을 요청합니다. |
| 500 | ft.InternalServerError | 데이터베이스, Redis, 스토리지 읽기/쓰기, 큐 또는 처리되지 않은 시스템 예외 | 내부 오류 | traceId, 애플리케이션/env/version/uploadId를 보존하고 먼저 목록/파일 트리를 확인합니다. 실패 시 이미 파일이 게시되었거나 처리 표시가 있을 수 있으므로 무작정 다시 덮어쓰거나 삭제하지 마십시오. |