콘텐츠로 이동

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를 보관하여 관리자에게 확인을 요청합니다.

문서 평가

이 페이지가 도움이 되었나요?