RUM 설정 수정¶
POST /api/v1/rum_cfg/{appid}/modify
개요¶
RUM 애플리케이션의 표시 설정, 식별자 또는 Client Token 바인딩을 수정합니다.
호출 전 및 사용 단계¶
현재 Key에는 rum.rumCfgManage 권한이 필요합니다. 경로의 appid는 간략 목록의 appId/uuid에서 가져옵니다. 반드시 먼저 존재 여부를 확인해야 하며, 수정 API로 존재 여부를 탐지해서는 안 됩니다.
jsonContent는 name/extend 기준으로 병합됩니다. type은 반드시 완전히 생략해야 하며, 원래 값을 전달해도 406이 반환됩니다. extend가 나타나면 전체가 교체되고, {}는 비우며, 생략하면 유지됩니다. jsonContent={} 또는 Body 전체={}인 경우에도 업데이트 시간이 갱신되고 매핑 동기화가 수행됩니다. newAppId는 생략하거나 빈 값이면 변경되지 않으며, 비어 있지 않으면 이름이 변경되므로 SDK/SourceMap/외부 링크 변경을 함께 계획해야 합니다. 기존 이력 데이터는 이 API에서 일괄 재작성되지 않습니다. custom 애플리케이션의 dashboardUuids는 전량 교체되고, []는 비우며, 생략하면 유지됩니다. 이름만 변경하는 경우 기존 바인딩을 유지하고 이전합니다.
clientToken을 생략하거나 빈 값으로 두면 기존 연결이 유지되며, 이때 응답의 content.clientToken은 이전 내부 연결 UUID(wctn_)이므로 SDK에 직접 넣을 수 없습니다. 명시적으로 비어 있지 않은 값이 검증을 통과한 경우에만 응답에 해당 평문이 반환됩니다. 바인딩을 교체해도 이전 Token은 폐기되지 않으며, 다른 애플리케이션에서 사용 중일 수 있습니다. 애플리케이션 연결 교체를 자격 증명 폐기와 동일하게 보아서는 안 됩니다.
로컬 커밋이 완료된 후 mapping 동기화가 이루어지며, 다운스트림 또는 큐 실패는 허용되어 성공으로 반환될 수 있고, mapping_ready 등 AIAPI 부가 정보는 반환하지 않습니다. 실패/타임아웃 시 먼저 간략 목록으로 신규/기존 appId와 jsonContent를 확인한 다음, 관리자에게 Token/매핑 확인을 요청하세요. 무작정 반복 교체하지 마십시오. 대상이 없고 dashboardUuids를 전달하지 않은 경우 현재 빈 객체를 읽어 500이 발생할 수 있습니다. dashboardUuids를 명시한 분기에서는 먼저 NotFoundRumSet을 반환하므로, 두 경우 모두 먼저 목록을 새로 고쳐야 합니다.
라우트 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| appid | string | Y | 현재 워크스페이스의 공개 애플리케이션 식별자이며, 데이터베이스의 실제 RumCfg UUID가 아닙니다. SDK 설정 및 SourceMap 요청에 사용됩니다. 예시: payment_web획득 또는 입력 방법: RUM 애플리케이션 간략 목록에서 content[].appId를 가져오거나(uuid도 동일한 값), 현재 워크스페이스의 RUM 애플리케이션 설정에서 가져옵니다. |
요청 헤더¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| dashboardUuids[*] | string | 단일 dsbd_ 또는 itgr_ 식별자 문자열입니다. 예시: dsbd_example획득 또는 입력 방법: 대시보드 목록에서 dsbd_ UUID를 가져오거나, 내장 뷰 목록에서 itgr_ UUID를 가져오며, 현재 워크스페이스에서 읽을 수 있는지 확인합니다. |
|
| jsonContent.extend.사용자 정의 키 | any | 동적 JSON 값으로 객체/배열/문자열/숫자/불리언/null이 가능하며 문자열로 제한되지 않습니다. 공개된 고정 기능 의미가 없으므로 민감한 자격 증명을 저장하지 마십시오. 예시: payment획득 또는 입력 방법: 호출자의 비즈니스 자료입니다. |
|
| clientToken | string | 선택적 문자열입니다. 생성 시 생략하거나 빈 값이면 Token이 자동 생성되며, 명시적 값이 전체 사이트에 존재하지 않으면 현재 워크스페이스에 새로 생성되고, 이미 존재하면 활성 상태이며 동일 워크스페이스여야 합니다. 데이터베이스에서는 최대 64자이며, 32자리 랜덤 16진수를 권장합니다. 수정 시 생략하거나 빈 문자열이면 기존 바인딩을 유지하며 자동 생성하거나 비우지 않습니다. 비어 있지 않은 값은 동일한 규칙으로 해석/신규 생성됩니다. 이전 Token의 내부 wctn_ UUID를 평문으로 사용해서는 안 됩니다. 빈 문자열 허용: True null 허용: False 예시: <RUM-CLIENT-TOKEN>획득 또는 입력 방법: 생성 시에는 생략하여 서버에서 생성하도록 권장합니다. 재사용해야 하는 경우 현재 워크스페이스의 클라이언트 Token 관리에서 활성 Token 평문을 가져오며, DF-API-KEY나 수집 Token으로 대체할 수 없습니다. |
|
| dashboardUuids | array | type=custom인 경우에만 사용됩니다. 생성 시 생략하거나 []이면 바인딩이 없으며, 수정 시 생략하면 유지, []이면 바인딩 비우기, 값이 나타나면 전량 교체되고 앞뒤 공백을 제거한 뒤 중복이 제거됩니다. dsbd_는 동일 워크스페이스에서 활성 상태이고 읽기 권한이 있어야 하며, itgr_는 현재 언어 선택에서 유효하고 숨겨지지 않은 내장 뷰여야 합니다. 생성 시 custom이 아니면 이 목록은 무시되며, 수정 시 custom이 아닌데 명시적으로 제공하면 400이 반환됩니다. null 허용: False 예시: ["dsbd_example"]획득 또는 입력 방법: 대시보드 목록에서 dsbd_ UUID를 가져오거나, 내장 뷰 목록에서 itgr_ UUID를 가져오며, 현재 워크스페이스에서 읽을 수 있는지 확인합니다. |
|
| jsonContent | json | JSON 객체입니다. 생성 시 필수이며, 수정 시 생략하면 {}로 처리됩니다. 내부의 name/type/extend는 각각 파라미터 표에 따라 처리됩니다. 수정 시 필드 단위로 기존 jsonContent를 병합하지만, extend가 나타나면 전체 객체가 교체되며 재귀적으로 병합되지 않습니다. 예시: {"name": "支付Web", "type": "web", "extend": {}}획득 또는 입력 방법: 애플리케이션 연동 방식, 표시 이름 및 비즈니스 표시 확장으로 구성합니다. |
|
| jsonContent.extend | json | 선택적 JSON 객체이며, null/배열/문자열은 선언에 의해 거부됩니다. 고정된 필수 하위 키가 없고, 실행 설정이나 인증 자격 증명으로 사용되지 않습니다. 생성 시 생략하면 이 키를 채우지 않고, 수정 시 생략하면 유지, {}이면 비우기, 값이 나타나면 전체 교체됩니다. null 허용: False 예시: {"team": "payment"}획득 또는 입력 방법: 호출자가 애플리케이션 표시/편집 확장을 저장하며, 수정 전에 먼저 읽고 유지해야 할 키를 복사합니다. |
|
| jsonContent.name | string | 생성 시 필수 문자열이며 최대 256자이고, 수정 시 생략하면 유지됩니다. 동일 워크스페이스의 활성 애플리케이션 이름은 중복될 수 없습니다. 현재 선언에서는 비어 있지 않음을 강제하지 않으므로, 식별 가능한 비어 있지 않은 이름을 권장합니다. null 허용: False 최대 길이: 256 예시: 支付Web획득 또는 입력 방법: 애플리케이션 관리자가 표시 이름을 입력합니다. |
|
| jsonContent.type | string | 생성 시 필수이며 web/miniapp/android/ios/custom/reactnative/harmonyos 중 하나입니다. 수정 시 원래 타입을 전달해도 406 NotSupportModifyAppType이 반환되므로 반드시 완전히 생략해야 합니다. 라우트에 열거되어 있다고 해서 수정 가능하다고 판단해서는 안 됩니다. null 허용: False 선택 가능한 값: ['web', 'miniapp', 'android', 'ios', 'custom', 'reactnative', 'harmonyos'] 예시: web획득 또는 입력 방법: SDK/수집 플랫폼에 따라 선택하며, 이 파라미터로 기존 타입을 변경할 수 없습니다. |
|
| newAppId | string | 선택 사항으로 최대 48자이며, 생략하거나 빈 문자열이면 유지되고, 비어 있지 않으면 공개 식별자를 교체합니다. SDK, SourceMap 등 참조를 함께 업데이트해야 하며, 내부 실제 UUID는 유지되고 컨트롤러가 RUM Trace 설정과 custom 바인딩을 이전합니다. 이름 변경을 이력 텔레메트리 데이터 재작성으로 간주하지 않습니다. 빈 문자열 허용: True null 허용: False $maxCharacterLength: 48 예시: payment_web_v2획득 또는 입력 방법: 애플리케이션 연동 이전 계획에 따라 선택하며, 먼저 동일 워크스페이스에서 식별자가 사용 중인지 확인합니다. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/rum_cfg/payment_web/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"jsonContent":{"name":"支付Web新名称"}}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content.id | integer 또는 null | 데이터베이스 행 ID입니다. 생성 시 제출 전 스냅샷이 반환되어 null일 수 있으며, 공개 식별자로 사용되지 않습니다. |
| content.uuid | string | 공개 호환 별칭으로 항상 appId와 같으며, 내부 실제 RumCfg UUID가 아닙니다. |
| content.appId | string | SDK/쿼리에서 사용하는 애플리케이션 식별자입니다. |
| content.workspaceUUID | string | 소속 워크스페이스 UUID입니다. |
| content.status | integer | 데이터베이스 상태로, 활성은 보통 0이며 삭제됨 3은 간략 목록에 없습니다. |
| content.creator | string | 생성 주체이며, OpenAPI에서는 일반적으로 Key 리소스 UUID입니다. |
| content.updator | string | 최근 업데이트 주체이며, 생성 후 업데이트가 없으면 비어 있을 수 있습니다. |
| content.createAt | integer | Unix 초 단위 생성 시간입니다. |
| content.updateAt | integer | Unix 초 단위 업데이트 시간이며, 생성 후 업데이트가 없으면 -1일 수 있습니다. |
| content.deleteAt | integer | Unix 초 단위 삭제 시간이며, 정상이면 -1입니다. |
| content.jsonContent | object | 애플리케이션 콘텐츠 객체입니다. |
| content.jsonContent.name | string | 애플리케이션 표시 이름입니다. |
| content.jsonContent.type | string | web/miniapp/android/ios/custom/reactnative/harmonyos입니다. |
| content.jsonContent.extend | object | 선택적으로 저장되는 동적 확장이며, 없으면 이 키가 생략될 수 있습니다. |
| content.jsonContent.extend.사용자 정의 키 | JSON | 호출자가 저장한 확장 키-값이며, 서버가 추가 실행 파라미터를 지원한다는 의미는 아닙니다. |
| content.clientToken | string | 명시적으로 비어 있지 않은 clientToken이 검증을 통과한 경우 평문이며, 생략/빈 값으로 유지된 경우 내부 Token UUID(wctn_)이므로 SDK 자격 증명으로 사용할 수 없습니다. |
| content.declaration | object | 현재 워크스페이스의 공통 선언입니다. |
{
"code": 200,
"content": {
"id": 123,
"uuid": "payment_web",
"appId": "payment_web",
"workspaceUUID": "wksp_example",
"status": 0,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427260,
"deleteAt": -1,
"jsonContent": {
"name": "支付Web新名称",
"type": "web",
"extend": {
"team": "payment"
}
},
"clientToken": "wctn_example",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하세요.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 타입 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 객체를 제출합니다. |
| 406 | ft.NotSupportModifyAppType | jsonContent에 type 키가 나타남(원래 타입이어도 동일) | 기존 애플리케이션의 애플리케이션 타입 수정은 아직 지원되지 않음 | type을 완전히 생략합니다. 다른 플랫폼이 필요하면 애플리케이션을 새로 생성합니다. |
| 404 | ft.NotFoundRumSet | dashboardUuids를 명시적으로 제공했을 때 대상 애플리케이션이 없음/삭제됨/워크스페이스가 다름 | 지정한 RUM 설정을 찾을 수 없음 | 현재 워크스페이스의 간략 목록에서 존재하는 appId를 가져옵니다. |
| 400 | ft.SignNameRepeat | 사용자 정의 appId/newAppId가 현재 워크스페이스의 활성 설정에서 이미 사용 중임 | 현재 워크스페이스에 동일한 이름의 식별자 payment_web이 이미 존재함 |
간략 목록으로 확인하고, 수정 시에는 원래 appId를 지정해야 합니다. 사용되지 않은 식별자를 선택합니다. |
| 400 | ft.RumSetNameRepeat | 동일 워크스페이스의 활성 애플리케이션이 이미 해당 이름을 사용 중임 | 현재 워크스페이스에 동일한 이름의 RUM 설정 이름 支付Web이 이미 존재함 |
사용되지 않은 애플리케이션 이름을 선택합니다. 결과를 알 수 없으면 먼저 조회하고 반복 생성하지 않습니다. |
| 400 | ft.InvalidRumDashboardID | custom이 아닌 애플리케이션에 dashboardUuids를 전달했거나, custom 뷰 식별자가 유효하지 않음/접근 권한 없음 | 사용자 정의 RUM 애플리케이션에 연결된 대시보드가 유효하지 않거나 접근 권한이 없음 | custom 애플리케이션만 바인딩을 업데이트할 수 있습니다. 읽을 수 있는 UUID를 확인합니다. |
| 400 | ft.RumClientTokenUnavailable | 명시적으로 제공한 Client Token이 이미 존재하지만 상태가 활성이 아님 | 해당 Client Token은 더 이상 사용할 수 없으므로 교체하거나 다시 생성하세요 | 현재 워크스페이스의 활성 Token을 선택하거나 생성 시 생략하여 자동 생성합니다. 폐기된 값을 재사용할 수 없습니다. |
| 400 | ft.RumClientTokenWorkspaceMismatch | 명시한 Token이 이미 다른 워크스페이스에서 사용 중임 | 해당 Client Token은 이미 다른 워크스페이스에서 사용 중이므로 교체하거나 다시 생성하세요 | 현재 워크스페이스 전용 Token을 사용하고, 다른 워크스페이스의 수집 자격 증명을 복사하지 않습니다. |
| 429 | ft.OperationTooFrequently | 현재 워크스페이스의 다른 RUM 생성/수정/삭제/Token 작업이 쓰기 잠금을 보유 중이며 5초 내에 획득하지 못함 | 작업이 너무频繁합니다. 잠시 후 다시 시도하세요 | 다른 작업이 끝날 때까지 기다리며 백오프합니다. 먼저 현재 상태를 다시 읽은 후 재시도하고, 동시에 수정하지 않습니다. |
| 500 | ft.InternalServerError | 데이터베이스/잠금 서비스, 이력 설정 형식 또는 처리되지 않은 시스템 예외. 애플리케이션이 없는데 dashboardUuids를 전달하지 않은 수정 시에도 빈 객체에 먼저 접근하여 500이 발생할 수 있음 | 내부 오류 | 먼저 현재 워크스페이스의 애플리케이션 간략 목록으로 실제 설정을 확인합니다. 쓰기가 이미 커밋되었을 수 있으므로 중복 생성이나 반복적인 Token 교체를 피하고, traceId를 보관하여 관리자에게 확인을 요청합니다. |