콘텐츠로 이동

생성



POST /api/v1/viewer/add

개요

탐색기를 생성하며, 빈 화면, 템플릿 또는 기존 뷰 복사를 지원합니다.

호출 전 및 사용 단계

최소 요청은 name만 입력합니다. 원본 뷰 복사를 사용할 때는 먼저 탐색기 목록 또는 대시보드 목록에서 원본 UUID를 확인합니다. 선택 순서는 비어 있지 않은 sourceDashboardUUID, 비어 있지 않은 templateInfos, templateUUID입니다. 원본 뷰를 찾지 못하면 빈 탐색기가 생성될 수 있으므로, 복사 후 레이아웃과 내용을 확인하세요. 이름이 충돌하면 HTTP 200으로 repeatInfo가 반환되며, 클라이언트는 새 uuid가 있는지 확인해야 합니다.

요청 헤더

매개변수명 유형 필수 설명
DF-API-KEY string Y 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예: <DF-API-KEY>
획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다.

Body 요청 매개변수

매개변수명 유형 필수 설명
ownerType string 호환 필드입니다. 현재 생성 라우트에서는 viewer로 고정됩니다.
null 허용: False
예: viewer
획득 또는 입력 방법: 신규 연동 시 생략할 수 있으며, 실제 리소스는 이 탐색기 진입점에서 생성됩니다.
templateUUID string 통합 템플릿 UUID로, 기존 원본 뷰 및 템플릿 객체보다 우선순위가 낮습니다.
null 허용: False
빈 문자열 허용: True
최대 길이: 128
예: tmpl_example
획득 또는 입력 방법: 통합 템플릿 UUID를 이미 확보한 경우 입력할 수 있습니다. 템플릿 이름만 있는 경우 먼저 기존 뷰를 내보내고, 반환된 객체를 사용해 templateInfos를 입력할 수 있습니다.
sourceDashboardUUID string 복사할 원본 뷰 UUID입니다. 비어 있지 않으면 우선 적용됩니다.
null 허용: False
빈 문자열 허용: True
최대 길이: 128
예: dsbd_source_example
획득 또는 입력 방법: 탐색기 목록 또는 대시보드 목록에서 현재 워크스페이스에 이미 존재하는 원본 뷰를 선택합니다.
name string Y 탐색기 이름이며 최대 64자입니다.
null 허용: False
최대 길이: 64
예: 主机巡检查看器
획득 또는 입력 방법: 이 워크스페이스에서 다른 탐색기에서 사용되지 않는 이름을 선택합니다.
desc string 탐색기 설명입니다.
null 허용: False
빈 문자열 허용: True
최대 길이: 2048
예: 主机巡检与状态核对
획득 또는 입력 방법: 새 탐색기의 용도를 입력합니다. 생략하거나 비어 있으면 템플릿 summary를 그대로 사용할 수 있습니다.
type string 빈 탐색기를 생성할 때 이 유형을 사용하며 기본값은 CUSTOM입니다. 템플릿을 사용할 때는 해당 dashboardType을 사용합니다.
null 허용: False
최대 길이: 32
예: CUSTOM
획득 또는 입력 방법: 일반적으로 CUSTOM을 사용합니다. 수정 시 상세의 content.type에서 가져와 그대로 사용할 수 있습니다.
extend json 빈 생성에 사용되는 확장 정보입니다. 템플릿을 사용할 때는 템플릿의 dashboardExtend를 사용합니다.
null 허용: False
예: {}
획득 또는 입력 방법: 탐색기 상세의 content.extend 또는 템플릿의 dashboardExtend에서 가져옵니다.
templateInfos json 탐색기 템플릿 JSON 객체이며, main에서 차트, 변수 및 그룹을 선언합니다.
null 허용: False
빈 문자열 허용: False
예: {"title": "主机巡检查看器", "summary": "主机巡检与状态核对", "identifier": "", "dashboardType": "CUSTOM", "dashboardExtend": {}, "dashboardMapping": [], "dashboardBindSet": [], "iconSet": {}, "main": {"type": "template", "charts": [], "vars": [], "groups": [], "chartGroupPos": []}}
획득 또는 입력 방법: 먼저 탐색기 내보내기를 호출하여 content 객체를 가져옵니다. 그대로 사용하거나 조정이 필요한 템플릿 필드를 수정하도록 선택합니다.
isImport boolean 가져오기 출처로 표시하며, 목록의 filter=import에 사용됩니다. 선택 내용은 여전히 템플릿 관련 필드에 의해 결정됩니다.
null 허용: False
예: false
획득 또는 입력 방법: 생성 출처에 따라 가져오기로 표시할지 결정합니다. 일반 생성에서는 생략하거나 false로 둡니다.
tagNames array 태그 이름을 입력합니다. 비어 있으면 템플릿 tagInfo를 그대로 사용할 수 있습니다.
null 허용: False
예: ["team:ops"]
획득 또는 입력 방법: 기존 탐색기 상세의 content.tagInfo[].name에서 복사하거나, 연결할 시나리오 태그를 입력합니다.
tagNames[*] string 개별 태그 이름이며 최대 128자입니다.
null 허용: False
최대 길이: 128
예: team:ops
획득 또는 입력 방법: 기존 탐색기 상세의 content.tagInfo[].name에서 복사하거나, 연결할 시나리오 태그를 입력합니다.

매개변수 추가 설명

템플릿은 대시보드 템플릿 필드 설명과 구조를 공유합니다. 이 API는 templateInfos를 사용하며, 최상위 name이 이름을 결정합니다. 대시보드 API의 최상위 identifier, isPublic, mapping 매개변수는 탐색기 생성에 적용되지 않습니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/viewer/add' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"name":"主机巡检查看器","desc":"主机巡检与状态核对","type":"CUSTOM"}'

응답

HTTP 200, application/json입니다. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여 줍니다.

필드 유형 설명
content.id integer 탐색기 레코드 번호입니다.
content.uuid string 탐색기 UUID입니다.
content.workspaceUUID string 소속 워크스페이스입니다.
content.name string 탐색기 이름입니다.
content.desc string 탐색기 설명입니다.
content.identifier string 사용자 지정 식별자이며 비어 있을 수 있습니다.
content.ownerType string 탐색기 리소스 소속이며 일반적으로 viewer입니다.
content.type string 탐색기 유형이며 예: CUSTOM입니다.
content.isPublic integer 현재 리소스의 공개 범위입니다. 1은 공개, 0은 생성한 주체에게만 표시됩니다.
content.chartPos array<object> 차트 레이아웃 배열이며 chartUUID와 레이아웃 객체 pos를 포함합니다.
content.chartPos[].chartUUID string 참조된 차트 UUID입니다.
content.chartPos[].pos object 레이아웃의 위치 및 크기입니다(예: x, y, w, h).
content.chartGroupPos array<string> 차트 그룹 정렬 순서입니다.
content.iconSet object 아이콘 구성입니다.
content.extend object 탐색기 확장 정보입니다.
content.mapping array<object> 변수 필드 매핑 정보입니다.
content.dashboardBindSet array 뷰 바인딩 구성입니다.
content.createdWay string 리소스 생성 출처입니다.
content.openPermissionSet boolean 엔터티 레코드의 권한 구성 스위치입니다.
content.permissionSet array<string> 레코드의 작업 권한 주체 UUID입니다.
content.readPermissionSet array<string> 레코드의 읽기 권한 주체 UUID입니다.
content.tagInfo array<object> 연결된 태그 정보입니다.
content.tagInfo[].id string 태그 UUID와 동일한 식별자입니다.
content.tagInfo[].uuid string 태그 UUID입니다.
content.tagInfo[].name string 태그 이름입니다.
content.tagInfo[].description string 태그 설명입니다.
content.tagInfo[].colour string 태그 색상입니다.
content.tagInfo[].scope array<string> 태그가 적용되는 범위입니다.
content.tagInfo[].tagPermissionInfo object 존재하는 경우 읽기/쓰기 권한 부여 정보입니다.
content.status integer 레코드 상태입니다.
content.creator string 생성자 ID입니다.
content.updator string 최근 업데이트한 주체 ID이며 비어 있을 수 있습니다.
content.createAt number 생성 시간(Unix 초)입니다.
content.updateAt number 업데이트 시간(Unix 초)입니다. 업데이트되지 않은 경우 -1일 수 있습니다.
content.deleteAt number 삭제 시간(Unix 초)입니다. 삭제되지 않은 경우 -1입니다.
content.declaration object 또는 null 워크스페이스의 공용 선언입니다.
content.repeatInfo object 이름 충돌 시 반환되며 생성이 완료되지 않습니다. name 등의 키로 그룹화됩니다.
content.repeatInfo.name array<object> 이름 충돌 레코드입니다.
content.repeatInfo.name[].name string 요청의 이름입니다.
content.repeatInfo.name[].importName string 요청의 이름입니다.
content.repeatInfo.name[].existName string 기존 탐색기 이름입니다.
content.repeatInfo.name[].nameConflictUUID string 동일 이름이 일치한 탐색기 UUID입니다.
content.repeatInfo.name[].conflictUUIDs array<string> 이번 충돌에 관련된 기존 탐색기 UUID입니다.
content.repeatInfo.name[].existNameIdentifier string 기존 탐색기의 식별자이며 비어 있을 수 있습니다.
content.repeatInfo.name[].existIdentifier string 기존 충돌 항목 식별자이며 비어 있을 수 있습니다.
content.repeatInfo.name[].isCrossConflict boolean 단순 이름 중복인 경우 false입니다.
content.repeatInfo.name[].identifier string 탐색기 생성의 충돌 매칭에서는 식별자를 전달하지 않으므로 이 값은 비어 있습니다.
content.repeatInfo.name[].importIdentifier string 요청 매칭 항목의 식별자이며 이 값은 비어 있습니다.
content.repeatInfo.name[].fileName string 연결된 템플릿 파일 이름이며, 직접 호출하여 파일이 없으면 비어 있습니다.
{
  "code": 200,
  "content": {
    "id": 25,
    "uuid": "dsbd_view_example",
    "name": "主机巡检查看器",
    "desc": "主机巡检与状态核对",
    "workspaceUUID": "wksp_example",
    "identifier": "",
    "ownerType": "viewer",
    "type": "CUSTOM",
    "isPublic": 1,
    "chartPos": [],
    "chartGroupPos": [],
    "iconSet": {},
    "extend": {},
    "mapping": [],
    "dashboardBindSet": [],
    "createdWay": "manual",
    "openPermissionSet": false,
    "permissionSet": [],
    "readPermissionSet": [],
    "tagInfo": [],
    "status": 0,
    "creator": "wsak_example",
    "updator": "",
    "createAt": 1785427200,
    "updateAt": -1,
    "deleteAt": -1,
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

이름 중복 시 HTTP 200 응답

{
  "code": 200,
  "content": {
    "repeatInfo": {
      "name": [
        {
          "name": "主机巡检查看器",
          "identifier": "",
          "fileName": "",
          "importName": "主机巡检查看器",
          "importIdentifier": "",
          "existName": "主机巡检查看器",
          "existIdentifier": "",
          "nameConflictUUID": "dsbd_view_example",
          "existNameIdentifier": "",
          "isCrossConflict": false,
          "conflictUUIDs": [
            "dsbd_view_example"
          ]
        }
      ],
      "identifier": [],
      "name_and_identifier": []
    },
    "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 파일 형식 오류 매개변수를 JSON 객체로 전달하세요.
403 ft.ForbiddenFreeEditionLimit 워크스페이스에 수량 제한이 활성화되어 있고 상한에 도달했습니다 무료 플랜 워크스페이스 {}가 상한({}개)에 도달하여 생성할 수 없습니다. 상용 플랜을 활성화하면 제한이 해제됩니다 현재 버전과 탐색기 수를 확인하세요.
400 ft.TagScopeMismatch 동일 이름의 태그가 이미 존재하지만 범위가 시나리오와 호환되지 않습니다 메시지에 태그 이름과 기존 및 대상 범위가 포함됩니다. 시나리오 또는 공통 태그로 변경하세요.
406 ft.ExceedMaxCharacterLimit 템플릿의 차트 또는 그룹 이름이 256자를 초과했거나 태그 이름이 128자를 초과했습니다 {} 값이 최대 문자 길이 제한을 초과했습니다 필드 길이 제한에 맞게 템플릿을 수정하세요.
404 ft.ObjectNotExists 전달한 통합 템플릿 UUID가 존재하지 않습니다 지정된 객체가 존재하지 않습니다 템플릿 UUID를 확인하거나, 내보낼 수 있는 기존 뷰 또는 전체 템플릿 객체를 사용하세요.
406 ft.InvalidParameter 템플릿 구조가 유효하지 않습니다. 예를 들어 main이 객체가 아니거나 charts, vars 또는 groups가 배열이 아니거나 차트 쿼리 구조가 유효하지 않습니다 매개변수 {}이(가) 유효하지 않습니다 오류에 표시된 필드 경로에 따라 템플릿을 수정하세요. 이 버전의 내보내기 API에서 반환된 전체 템플릿을 우선 사용하세요.

문서 평가

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