콘텐츠로 이동

RUM 구성 추가



POST /api/v1/rum_cfg/add

개요

RUM 애플리케이션 구성을 생성하고 클라이언트 Token 연관을 설정합니다.

호출 전 및 사용 단계

현재 Key에는 rum.rumCfgManage 권한이 필요하며 현재 워크스페이스에만 적용됩니다. 먼저 애플리케이션 플랫폼, 표시 이름 및 appId를 결정하고, 생성 후 응답의 appId와 clientToken 평문을 클라이언트 SDK에 입력합니다. DF-API-KEY는 이 관리 요청에만 사용되며 브라우저로 전달할 수 없습니다.

customIdentity는 이전 호환 필드이며 appId가 존재할 때 우선합니다(빈 문자열 포함). 최종적으로 비어 있을 때만 자동 생성됩니다. custom 애플리케이션은 읽기 가능한 대시보드/내장 뷰를 선택적으로 바인딩할 수 있으며, 다른 유형은 dashboardUuids를 사용하지 않습니다. 새 Token 이름은 RUM- 접두사와 애플리케이션 이름으로 구성되며, 명시적 Client Token은 현재 워크스페이스의 활성 값을 재사용하거나 독립 값을 새로 생성할 수 있습니다.

주체와 Token을 먼저 제출한 후 RUM 데이터 매핑을 비동기로 동기화합니다. 작업 전달 또는 다운스트림 실패는 일반적으로 보조 상태를 기록하고 이 인터페이스의 성공을 유지합니다. HTTP 200은 데이터 쿼리 복사본이 준비되었음을 보장하지 않습니다. 이 공개 응답은 mapping_status 등 AIAPI 필드를 반환하지 않으며, 새 Token이 모든 수집 노드에서 적용되었음을 보장하지도 않습니다. 실제 SDK 연동으로 검수해야 합니다. 생성에는 멱등 키가 없습니다. 네트워크 실패 시 먼저 appId/이름으로 요약 목록을 조회하여 중복 생성이나 새 자격 증명 분실을 방지합니다.

요청 헤더

매개변수명 유형 필수 설명
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
획득 또는 입력 방법: 호출자의 비즈니스 데이터입니다.
appId string 선택적 문자열이며 최대 48자입니다. 생략 시 customIdentity와 호환되며, 최종 값이 비어 있으면 appid_로 시작하는 값을 자동 생성합니다. 현재 OpenAPI는 AIAPI의 영숫자 및 밑줄 정규식을 강제하지 않습니다. SDK/SourceMap 호환성을 위해 영숫자와 밑줄만 사용하고 경로 기호를 포함하지 않는 것이 좋습니다.
빈 문자열 허용: True
null 허용: False
$maxCharacterLength: 48
예: payment_web
획득 또는 입력 방법: 호출자가 SDK에서 사용할 고유 애플리케이션 식별자를 약정하며, 먼저 요약 목록으로 확인합니다.
clientToken string 선택적 문자열입니다. 생성 시 생략하거나 비어 있으면 Token을 자동 생성합니다. 명시적 값이 전체 사이트에 존재하지 않으면 현재 워크스페이스에 새로 생성하고, 이미 존재하면 활성 상태이며 동일 워크스페이스여야 합니다. 데이터베이스에서 최대 64자이며 32자리 임의 16진수를 권장합니다. 수정 시 생략/빈 문자열은 기존 바인딩을 유지하며 자동 생성하거나 비우지 않습니다. 비어 있지 않은 값은 동일한 규칙으로 해석하거나 새로 생성합니다. 이전 Token의 내부 wctn_ UUID를 평문으로 사용해서는 안 됩니다.
빈 문자열 허용: True
null 허용: False
예: <RUM-CLIENT-TOKEN>
획득 또는 입력 방법: 생성 시에는 생략하여 서버에서 생성하는 것을 권장합니다. 재사용해야 하는 경우 현재 워크스페이스의 클라이언트 Token 관리에서 활성 Token 평문을 가져오며, DF-API-KEY나 수집 Token으로 대체할 수 없습니다.
customIdentity string 선택적 문자열이며 최대 19자입니다. appId 키가 완전히 생략된 경우에만 후보로 사용됩니다. appId에 명시적 빈 문자열이 있으면 이 이전 필드를 덮어쓰고 자동 생성으로 전환합니다. appId를 우선 사용하는 것이 좋습니다.
빈 문자열 허용: True
null 허용: False
$maxCharacterLength: 19
예: payment_web
획득 또는 입력 방법: 생성 시 선택적으로 사용하는 이전 호환 애플리케이션 식별자이며 호출자가 약정합니다.
dashboardUuids array type=custom인 경우에만 사용됩니다. 생성 시 생략하거나 []이면 바인딩이 없습니다. 수정 시 생략하면 유지하고, []이면 바인딩을 비우며, 값이 나타나면 전체를 교체하고 앞뒤 공백을 제거한 후 중복을 제거합니다. dsbd_는 동일 워크스페이스에서 활성 상태이고 읽기 권한이 있어야 합니다. itgr_는 현재 언어 선택에서 유효하고 숨겨지지 않은 내장 뷰여야 합니다. 생성 시 custom이 아니면 이 목록은 무시됩니다. 수정 시 custom이 아닌데 명시적으로 제공하면 400입니다.
null 허용: False
예: ["dsbd_example"]
획득 또는 입력 방법: 대시보드 목록에서 dsbd_ UUID를 가져오거나 내장 뷰 목록에서 itgr_ UUID를 가져오고, 현재 워크스페이스에서 읽을 수 있는지 확인합니다.
jsonContent json Y JSON 객체입니다. 생성 시 필수이며, 수정 시 생략하면 {}로 처리합니다. 내부 name/type/extend는 각각 매개변수 표에 따라 처리합니다. 수정 시 필드 단위로 기존 jsonContent를 병합하지만, extend가 나타나면 전체 객체를 교체하며 재귀적으로 병합하지 않습니다.
null 허용: False
예: {"name": "支付Web", "type": "web", "extend": {}}
획득 또는 입력 방법: 애플리케이션 연동 방식, 표시 이름 및 비즈니스 표시 확장으로 구성합니다.
jsonContent.extend json 선택적 JSON 객체이며 null/배열/문자열은 선언에 의해 거부됩니다. 고정된 필수 하위 키가 없으며 실행 구성이나 인증 자격 증명으로 사용되지 않습니다. 생성 시 생략하면 이 키를 추가하지 않고, 수정 시 생략하면 유지하며, {}는 비우고, 값이 나타나면 전체를 교체합니다.
null 허용: False
예: {"team": "payment"}
획득 또는 입력 방법: 호출자가 애플리케이션 표시/편집 확장을 저장하며, 수정 전에 먼저 읽고 유지해야 할 키를 복사합니다.
jsonContent.name string Y 생성 시 필수 문자열이며 최대 256자이고, 수정 시 생략하면 유지됩니다. 동일 워크스페이스의 활성 애플리케이션 이름은 중복될 수 없습니다. 현재 선언은 비어 있지 않음을 강제하지 않으므로 식별 가능한 비어 있지 않은 이름을 사용하는 것이 좋습니다.
null 허용: False
최대 길이: 256
예: 支付Web
획득 또는 입력 방법: 애플리케이션 유지 관리자가 표시 이름을 입력합니다.
jsonContent.type string Y 생성 시 web/miniapp/android/ios/custom/reactnative/harmonyos 중 하나가 필수입니다. 수정 시 원래 유형을 전달하더라도 406 NotSupportModifyAppType이 발생하므로 완전히 생략해야 합니다. 라우트 열거형에 값이 있다고 해서 수정 가능하다고 판단해서는 안 됩니다.
null 허용: False
선택 가능한 값: ['web', 'miniapp', 'android', 'ios', 'custom', 'reactnative', 'harmonyos']
예: web
획득 또는 입력 방법: SDK/수집 플랫폼에 따라 선택하며, 이 매개변수로 기존 유형을 변경할 수 없습니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/rum_cfg/add' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"appId":"payment_web","jsonContent":{"name":"支付Web","type":"web","extend":{"team":"payment"}}}'

응답

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 생성 시 유효한 Client Token 평문을 반환하므로 안전하게 보관해야 합니다. 수정 응답에는 호환 분기가 있으므로 해당 페이지를 참조하세요.
content.declaration object 현재 워크스페이스의 공통 선언입니다.
{
  "code": 200,
  "content": {
    "id": null,
    "uuid": "payment_web",
    "appId": "payment_web",
    "workspaceUUID": "wksp_example",
    "status": 0,
    "creator": "wsak_example",
    "updator": "",
    "createAt": 1785427200,
    "updateAt": -1,
    "deleteAt": -1,
    "jsonContent": {
      "name": "支付Web",
      "type": "web",
      "extend": {
        "team": "payment"
      }
    },
    "clientToken": "<RUM-CLIENT-TOKEN>",
    "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 파일 형식 오류 jsonContent 객체를 포함하여 제출하세요.
400 ft.SignNameRepeat 사용자 정의 appId/newAppId가 현재 워크스페이스의 활성 구성에서 이미 사용 중입니다. 현재 워크스페이스에 동일한 이름의 식별자 payment_web이 이미 존재합니다. 요약 목록으로 확인하고, 수정 시 원래 appId를 찾아야 합니다. 사용하지 않은 식별자를 선택하세요.
400 ft.RumSetNameRepeat 동일 워크스페이스의 활성 애플리케이션에서 이미 이 이름을 사용 중입니다. 현재 워크스페이스에 동일한 이름의 RUM 구성 이름 支付Web이 이미 존재합니다. 사용하지 않은 애플리케이션 이름을 선택하세요. 결과를 알 수 없으면 먼저 조회하고 중복 생성하지 마세요.
400 ft.InvalidRumDashboardID custom의 dashboardUuids 항목이 유효하지 않거나, 누락되었거나, 숨겨졌거나, 읽기 권한이 없습니다. 사용자 정의 RUM 애플리케이션에 연결된 대시보드가 유효하지 않거나 액세스 권한이 없습니다. 현재 읽을 수 있는 대시보드/내장 뷰 목록에서 유효한 UUID를 가져오며, 다른 리소스 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 데이터베이스/Token 생성, 잠금 서비스 또는 처리되지 않은 구성 예외입니다. 내부 오류 먼저 appId/이름으로 요약 목록을 조회하여 애플리케이션이 생성되었는지 확인하고, 관리자가 Token 및 비동기 매핑을 확인하도록 하세요. 중복 생성이나 자격 증명 분실을 방지하세요.

문서 평가

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