목록¶
GET /api/v1/rum_sourcemap/list
개요¶
RUM 애플리케이션의 각 환경 및 버전별 SourceMap 상태 요약을 나열합니다.
호출 전 및 사용 단계¶
Key는 routine.defaultAccess, rum.rumCfgManage, anonymous.shared, anonymous.snapshotShared 중 하나에 해당해야 하며, 실제 OpenAPI Key에 따라 인증이 수행됩니다. 현재 Key가 속한 워크스페이스만 대상으로 합니다. appId는 RUM 애플리케이션 요약 content[].appId에서 가져오며, SDK/오류 기록의 app_id와 동일해야 하고 데이터베이스 내부 UUID로 대체할 수 없습니다. SourceMap은 애플리케이션, 환경 env 및 버전 version으로 정확하게 지정되며, 대소문자/공백은 식별자 자체에 속하므로 수집 기록과 완전히 일치해야 합니다. env/version을 생략하거나 빈 문자열로 지정하면 빈 환경/빈 버전을 의미하며, 전체를 와일드카드로 매칭하는 것이 아닙니다. 현재 관리형 라이프사이클에서는 각각 최대 256자까지 허용됩니다.
OpenAPI는 Query appId만 공개하며 프런트엔드의 pageSize/pageIndex/search/env는 허용하지 않습니다. 애플리케이션 전체에서 표시 가능한 모든 환경/버전 배열을 반환하며 페이지 구분이 없고 capabilities 객체도 없습니다. 최초 읽기 시에는 과거 디렉터리와 배포 인덱스를 안전하게 인계할 수 있으며, 이전 업로드/인덱스 업데이트 충돌이 발생하면 409 안내에 따라 처리합니다.
마지막 성공 업로드 시간 기준 내림차순입니다. processing 상태의 새 세대는 목록의 이전 버전 표시를 덮어쓸 수 있고, failed 대체는 이미 존재하는 정상 현재 세대를 숨기지 않으므로 목록에 failed가 없다고 해서 최근 대체 요청이 성공했음을 증명할 수는 없습니다. state=ready/settling은 일반적으로 읽을 수 있고, processing은 여전히 업로드/압축 해제/배포 중이며, failed는 실패, blocked는 reasonCode와 함께 과거 디렉터리 또는 복구 상황을 확인해야 합니다. 삭제 중/삭제된 세대는 나열되지 않습니다.
createAt은 마지막 성공 업로드 시간이며 작업 생성 시간이 아닙니다. 아직 성공하지 않은 경우 0일 수 있고 lastSuccessfulUploadAt은 null일 수 있습니다. 요약만 반환하며 uploadId, 파일 내용 또는 파싱 결과는 포함하지 않습니다. 업로드 완료 후에는 파일 트리를 조회하고 실제 오류 스택으로 검증해야 합니다.
요청 헤더¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Query 요청 파라미터¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| appId | string | Y | 현재 워크스페이스의 활성 애플리케이션 식별자를 필수로 입력합니다. 내부 RumCfg UUID가 아니며 워크스페이스 간에 사용할 수 없습니다. null 허용: False 예시: payment_web획득 또는 입력 방법: RUM 애플리케이션 요약 content[].appId 또는 오류 기록의 app_id에서 획득합니다. |
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/rum_sourcemap/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode appId=payment_web
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | array<object> |
애플리케이션의 표시 가능한 모든 환경/버전 요약이며, 기록이 없으면 []이고 페이지 구분이 없습니다. |
| content[].env | string | 정확한 환경 식별자이며, 빈 문자열도 독립적인 환경입니다. |
| content[].version | string | 정확한 버전 식별자입니다. |
| content[].createAt | integer | 마지막 성공 업로드 Unix 초이며, 성공하지 않은 경우 0일 수 있습니다. 과거 기록은 기존 업로드 시간을 따릅니다. |
| content[].lastSuccessfulUploadAt | integer 또는 null | 마지막 성공 업로드 Unix 초이며, 아직 성공하지 않은 경우 null입니다. 이전 호환 기록에서는 누락될 수 있습니다. |
| content[].state | string | processing/ready/settling/failed/blocked 등이며, 이전 호환 기록에서는 누락될 수 있습니다. |
| content[].reasonCode | string 또는 null | 최근 실패/격리 원인으로, sourcemap_invalid/archive_too_large/legacy_invalid 등이며 정상인 경우 null일 수 있습니다. 작업마다 독립적인 결과는 아닙니다. |
| 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": [
{
"env": "production",
"version": "1.2.3",
"createAt": 1785427200,
"lastSuccessfulUploadAt": 1785427200,
"state": "settling",
"reasonCode": null,
"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 | 선언되지 않은 Query 파라미터를 사용하거나 파라미터가 규칙을 위반함 | 파라미터 파싱 실패 | Query 파라미터 표와 예시를 확인합니다. |
| 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를 확인합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 파일 읽기/스냅샷, 과거 설정 또는 처리되지 않은 파싱 예외 | 내부 오류 | traceId와 애플리케이션/env/version을 보존하고, 먼저 버전 상태와 파일을 확인한 후 실제 오류에 따라 처리합니다. 읽기는 백오프 재시도가 가능합니다. |