파일 트리 나열¶
POST /api/v1/rum_sourcemap/file_tree
개요¶
지정한 SourceMap 버전의 상대 파일 및 디렉터리 이름을 나열합니다.
호출 전 및 사용 단계¶
Key는 routine.defaultAccess 또는 rum.rumCfgManage 중 하나에 일치해야 합니다. 현재 Key가 속한 워크스페이스에만 해당합니다. appId는 RUM 애플리케이션 요약 목록 content[].appId에서 가져오며, SDK/오류 기록 app_id와 일치해야 하고 데이터베이스 내부 UUID로 대체할 수 없습니다. SourceMap은 애플리케이션, 환경 env 및 버전 version으로 정확히 위치를 지정합니다. 대소문자/공백은 식별자 자체의 일부이므로 수집 기록과 완전히 일치해야 합니다. env/version을 생략하거나 빈 문자열로 지정하면 빈 환경/빈 버전을 의미하며, 전체를 와일드카드로 지정하는 것이 아닙니다. 현재 관리형 수명 주기에서는 각각 최대 256자여야 합니다.
POST JSON은 정확한 환경/버전을 지정합니다. 보호된 로컬 스냅샷을 읽으며, ready/settling 및 일부 과거 시간이 비정상이지만 읽을 수 있는 blocked 버전은 반환될 수 있습니다. 그 외 준비되지 않았거나 파일이 누락된 경우는 404 및 reasonCode로 설명합니다. 새 업로드가 아직 processing 상태일 때는 이전 병합 성공을 근거로 읽을 수 없습니다.
사전순으로 정렬된 상대 경로 문자열을 반환하며, 디렉터리는 /로 끝나고 중첩 트리가 아닙니다. 파일 내용, 크기, 다운로드 URL 또는 MD5는 반환하지 않습니다. ZIP 루트 디렉터리 계층과 스택 URL 경로가 일치하는지 확인하는 데 사용합니다. []는 현재 반환된 항목이 없음을 나타낼 뿐이며 전체 파싱 검수를 대신할 수 없고, 과거 디렉터리 나열 이상도 빈 값으로 허용될 수 있습니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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에서 가져오며 업로드 시와 문자 단위로 일치해야 합니다. |
|
| version | string | 선택적 문자열이며 기본값은 빈 버전이고 최대 256자입니다. 최신/모든 버전을 의미하지 않으며 null은 허용되지 않습니다. 빈 문자열 허용: True null 허용: False 예: 1.2.3획득 또는 입력 방법: 클라이언트 실제 배포 버전/오류 기록 version에서 가져오며 빌드 산출물과 대응합니다. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/rum_sourcemap/file_tree' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"appId":"payment_web","env":"production","version":"1.2.3"}'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | array<string> |
사전순으로 정렬된 상대 경로 목록이며, 빈 결과는 []입니다. |
| content[] | string | 파일 상대 경로 또는 /로 끝나는 디렉터리 상대 경로입니다. |
| 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": [
"static/",
"static/js/",
"static/js/app.js.map"
],
"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/env/version 객체를 제출하십시오. |
| 404 | ft.NotFoundRumSet | 애플리케이션이 현재 워크스페이스에 없거나 삭제되었거나 존재하지 않습니다 | 지정한 RUM 설정을 찾을 수 없습니다 | RUM 애플리케이션 요약 목록을 새로 고치고 현재 워크스페이스의 실제 appId를 사용하십시오. |
| 404 | ft.SourceMapPackageNotFound | 선택한 환경/버전에 기록이 없거나, 아직 처리 중이거나, 읽을 수 없거나, 필요한 소스 파일이 누락되었습니다 | reasonCode에 따라 기록 없음/처리 중/읽을 수 없음/소스 파일 없음 등의 현지화된 메시지를 반환합니다 | 정확한 appId/env/version을 확인하십시오. registry_missing은 업로드 여부를 확인하고, bundle_processing은 대기하며, bundle_unavailable/source_files_missing은 상태와 파일을 확인하십시오. 모든 404를 업로드되지 않은 것으로 간주하지 마십시오. |
| 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.SourceMapSnapshotTooLarge | 읽기에 필요한 파일 스냅샷 크기가 사이트 제한(기본값 2GiB)을 초과했습니다 | 이번 SourceMap 읽기에 필요한 파일 총 크기가 제한을 초과했습니다 | 해당 버전의 파일 수를 줄이거나 관리자에게 제한 확인을 요청하십시오. 반복 읽기로 제한을 우회하지 마십시오. |
| 500 | ft.InternalServerError | 데이터베이스, 파일 읽기/스냅샷, 과거 구성 또는 처리되지 않은 파싱 예외 | 내부 오류 | traceId와 애플리케이션/env/version을 보존하고, 먼저 버전 상태와 파일을 확인한 후 실제 오류에 따라 처리하십시오. 읽기는 백오프 재시도할 수 있습니다. |