콘텐츠로 이동

생성



POST /api/v1/dashboard/add

개요

사용자 내장 뷰를 생성하며, 빈 템플릿, 원본 뷰 복사 또는 사용자 정의 템플릿 제출을 지원합니다.

호출 전 및 사용 단계

최소 요청에는 name만 필요합니다. 복사할 때는 내장 뷰 목록에서 동일 워크스페이스 내의 유효한 원본 뷰를 선택합니다. sourceDashboardUUID가 비어 있지 않으면 우선 적용됩니다. 유효하지 않은 원본을 사용하면 빈 뷰가 생성될 수 있습니다. 이름 또는 식별자가 충돌하면 기본적으로 HTTP 200으로 repeatInfo를 반환하며 생성하지 않습니다. recoverIdentifier=true이면 일치하는 모든 뷰를 삭제하고 다시 생성하며, 삭제와 재생성은 동일한 트랜잭션에서 처리됩니다. 이름과 식별자가 서로 다른 뷰와 일치하면 두 뷰 모두 삭제될 수 있습니다. 먼저 백업하고 충돌 UUID를 확인해야 합니다. 실패한 후에는 먼저 현재 상태를 확인하고 백업에 따라 복구합니다.

요청 헤더

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

Body 요청 파라미터

파라미터 이름 유형 필수 설명
dashboardBidding.* array 속성 값은 해당 필드의 일치 조건 배열입니다.
예: [{"op": "in", "value": ["web-01"]}]
가져오기 또는 입력 방법: 내장 뷰 상세로 현재 바인딩을 읽거나, 뷰로 이동해야 하는 로그, 객체 등의 데이터에서 필드 값을 확인합니다.
dashboardBidding.*[].op string in은 주어진 값 중 하나와 일치시키고, wildcard는 와일드카드 패턴으로 일치시킵니다. 원본 필드 값이 비어 있지 않을 때 단독 *는 모든 값을 일치시킬 수 있습니다. 여러 조건 중 하나라도 일치하면 매칭되는 것으로 처리됩니다.
예: in
가져오기 또는 입력 방법: 상세에서 해당 필드의 일치 방식을 우선 그대로 사용합니다.
dashboardBidding.*[].value array 문자열 배열입니다. 워크스페이스에서 왼쪽 와일드카드를 제한하는 경우 *example 형식을 사용하지 않아야 합니다.
예: ["web-01"]
가져오기 또는 입력 방법: 원본 데이터의 해당 필드에서 실제 값을 선택합니다. 태그를 매칭하려면 label을 사용할 수 있고, 원본 데이터는 df_label로 매칭합니다.
sourceDashboardUUID string 원본 뷰 UUID입니다. 비어 있지 않으면 templateInfos보다 우선합니다.
null 허용: False
빈 문자열 허용: True
최대 길이: 128
예: dsbd_inner_example
가져오기 또는 입력 방법: 내장 뷰 목록에서 복사할 원본 UUID를 가져오고 먼저 상세를 확인합니다.
name string Y 내장 뷰 이름이며 최대 256자입니다.
null 허용: False
최대 길이: 256
예: 主机详情内置视图
가져오기 또는 입력 방법: 현재 워크스페이스에서 다른 내장 뷰가 사용하지 않는 이름을 입력합니다.
desc string 내장 뷰 설명이며 최대 2048자입니다.
null 허용: False
최대 길이: 2048
예: 根据主机查看运行状态
가져오기 또는 입력 방법: 해당 뷰의 용도를 입력합니다.
recoverIdentifier boolean 일치하는 기존 뷰를 삭제하고 계속 생성할지 여부이며 기본값은 false입니다.
null 허용: False
예: false
가져오기 또는 입력 방법: 최초 요청에서는 false로 유지합니다. 백업하고 각 충돌 객체를 교체할 것을 확인한 경우에만 true로 설정합니다.
identifier string 동일 워크스페이스 내 내장 뷰 식별자는 고유해야 하며 최대 128자이고 비어 있을 수 있습니다.
null 허용: False
빈 문자열 허용: True
최대 길이: 128
예: host-overview
가져오기 또는 입력 방법: 안정적인 사용자 정의 식별자이며, 수정 전에 상세를 통해 현재 identifier를 가져올 수 있습니다.
templateInfos json 생성에 사용할 JSON 템플릿 객체입니다.
null 허용: False
빈 문자열 허용: False
예: {"title": "主机详情内置视图", "summary": "根据主机查看运行状态", "identifier": "", "dashboardType": "CUSTOM", "dashboardExtend": {}, "dashboardMapping": [], "dashboardBindSet": [], "iconSet": {}, "main": {"type": "template", "charts": [], "vars": [], "groups": [], "chartGroupPos": []}}
가져오기 또는 입력 방법: 내장 뷰 내보내기의 content에서 가져오며 main을 완전하게 유지합니다.
dashboardBidding json 선택적 바인딩 조건 객체입니다. 바인딩이 없으면 생략하거나 빈 객체를 사용합니다.
null 허용: False
예: {"host": [{"op": "in", "value": ["web-01"]}]}
가져오기 또는 입력 방법: 내장 뷰 상세로 현재 바인딩을 읽거나, 뷰로 이동해야 하는 로그, 객체 등의 데이터에서 필드 값을 확인합니다.
specifyDashboardUUID string 새 뷰의 UUID이며 dsbd_custom_으로 시작해야 하고 전역에서 사용되지 않아야 하며, 삭제된 UUID도 재사용할 수 없습니다.
null 허용: False
빈 문자열 허용: False
$matchRegExp: ^dsbd_custom_[a-z0-9]{32}$
예: dsbd_custom_0123456789abcdef0123456789abcdef
가져오기 또는 입력 방법: 32자리 소문자 또는 숫자를 접미사로 직접 생성합니다. 일반적으로 생략하며 서비스에서 할당합니다.

파라미터 추가 설명

템플릿을 사용할 때도 최상위 name은 필수이며, identifier를 생략하면 빈 값이 되고 템플릿의 동일 이름 필드가 최상위 필드를 대체하지 않습니다. 최상위 desc가 비어 있거나 생략된 경우 템플릿의 summary로 보완됩니다. 비어 있지 않은 바인딩이 있을 때만 생성 응답에 dashboardBidding이 포함됩니다. 워크스페이스 간 마이그레이션 시에는 바인딩을 별도로 구성해야 합니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/dashboard/add' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"name":"主机详情内置视图","desc":"根据主机查看运行状态","identifier":"host-overview","dashboardBidding":{"host":[{"op":"in","value":["web-01"]}]}}'

응답

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 내장 뷰 리소스 소유 유형이며 내장 뷰는 inner입니다.
content.type string 내장 뷰 유형입니다(예: CUSTOM).
content.isPublic integer 상세 접근 범위입니다. 1은 공개, 0은 생성한 ID만 접근할 수 있습니다.
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.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.dashboardBidding object 비어 있지 않은 바인딩인 경우에만 반환됩니다.
content.dashboardBidding.* array<object> 실제 원본 필드 기준으로 구성된 일치 조건 배열입니다.
content.dashboardBidding.*[].op string 일치 연산자입니다.
content.dashboardBidding.*[].value array<string> 일치 값 배열입니다.
content.declaration object 또는 null 워크스페이스의 공통 선언입니다.
content.repeatInfo object 이름 또는 식별자가 충돌할 때 반환되며 응답에는 새 UUID가 포함되지 않습니다.
content.repeatInfo.name array<object> 이름과 일치한 충돌 레코드입니다.
content.repeatInfo.identifier array<object> 식별자와 일치한 충돌 레코드입니다.
content.repeatInfo.name_and_identifier array<object> 이름과 식별자 모두 일치한 충돌 레코드입니다.
content.repeatInfo.*[].name string 생성할 뷰 이름입니다.
content.repeatInfo.*[].identifier string 생성할 뷰의 식별자입니다.
content.repeatInfo.*[].importName string 생성할 뷰 이름입니다.
content.repeatInfo.*[].importIdentifier string 생성할 뷰의 식별자입니다.
content.repeatInfo.*[].fileName string 연결된 템플릿 파일 이름이며 직접 호출 시 일반적으로 비어 있습니다.
content.repeatInfo.*[].existName string 일치한 기존 뷰 이름입니다.
content.repeatInfo.*[].existIdentifier string 일치한 기존 뷰 식별자입니다.
content.repeatInfo.*[].nameConflictUUID string 이름 충돌이 있는 경우 해당 기존 뷰 UUID입니다.
content.repeatInfo.*[].identifierConflictUUID string 식별자 충돌이 있는 경우 해당 기존 뷰 UUID입니다.
content.repeatInfo.*[].existNameIdentifier string 이름 충돌 객체의 식별자입니다.
content.repeatInfo.*[].existIdentifierName string 식별자 충돌 객체의 이름입니다.
content.repeatInfo.*[].isCrossConflict boolean 이름과 식별자가 각각 서로 다른 두 객체와 일치했는지 여부입니다.
content.repeatInfo.*[].conflictUUIDs array<string> 충돌에 관련된 모든 기존 뷰 UUID입니다.
{
  "code": 200,
  "content": {
    "id": 72,
    "uuid": "dsbd_inner_example",
    "name": "主机详情内置视图",
    "desc": "根据主机查看运行状态",
    "workspaceUUID": "wksp_example",
    "identifier": "host-overview",
    "ownerType": "inner",
    "type": "CUSTOM",
    "isPublic": 1,
    "chartPos": [],
    "chartGroupPos": [],
    "iconSet": {},
    "extend": {},
    "mapping": [],
    "dashboardBindSet": [],
    "createdWay": "manual",
    "openPermissionSet": false,
    "permissionSet": [],
    "readPermissionSet": [],
    "status": 0,
    "creator": "wsak_example",
    "updator": "",
    "createAt": 1785427200,
    "updateAt": -1,
    "deleteAt": -1,
    "dashboardBidding": {
      "host": [
        {
          "op": "in",
          "value": [
            "web-01"
          ]
        }
      ]
    },
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

이름 충돌 시의 HTTP 200 응답

{
  "code": 200,
  "content": {
    "repeatInfo": {
      "name": [
        {
          "name": "主机详情内置视图",
          "identifier": "",
          "fileName": "",
          "importName": "主机详情内置视图",
          "importIdentifier": "",
          "existName": "主机详情内置视图",
          "existIdentifier": "host-overview",
          "nameConflictUUID": "dsbd_inner_example",
          "existNameIdentifier": "host-overview",
          "isCrossConflict": false,
          "conflictUUIDs": [
            "dsbd_inner_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 내장 뷰 수 제한이 활성화되어 있고 워크스페이스가 생성 상한에 도달함 무료 플랜 워크스페이스 {}가 상한({}개)에 도달하여 생성할 수 없습니다. 상용 플랜을 활성화하면 제한이 해제됩니다 현재 워크스페이스 할당량을 확인하고 보존할 필요가 없는 뷰를 정리한 후 다시 시도합니다.
406 ft.ParameterCheckFailed 워크스페이스에서 왼쪽 와일드카드를 제한하며, 바인딩 값이 *로 시작하는 와일드카드 조건과 일치함 쿼리 구성에서 퍼지 매칭의 왼쪽 * 일치는 현재 지원되지 않습니다 값 앞의 *를 제거하거나 정확한 값으로 변경합니다. 이 제한은 wildcard 또는 필드 이름이 *, -*로 시작하는 조건에 적용됩니다. 단독 *는 이 검증을 트리거하지 않습니다. 오류 응답의 content는 true입니다.
400 ft.IdentificationIdExists 내장 뷰 식별자 또는 새 뷰 UUID가 이미 사용 중임 식별자 ID가 이미 존재합니다 사용되지 않은 값을 사용하거나 사용자 정의 UUID를 생략하여 서비스에서 생성하도록 합니다.
406 ft.ExceedMaxCharacterLimit 템플릿 차트 또는 뷰 그룹 이름이 256자를 초과함 {}이 최대 문자 길이 제한을 초과했습니다 해당 템플릿 필드를 줄입니다.
406 ft.InvalidParameter 템플릿 구조가 유효하지 않음. 예: main이 객체가 아니거나 charts, vars 또는 groups가 배열이 아니거나 차트 쿼리 구조가 유효하지 않음 파라미터 {}가 유효하지 않습니다 오류에 표시된 필드 경로에 따라 템플릿을 수정합니다. 이 버전의 내보내기 인터페이스에서 반환된 전체 템플릿을 우선 사용합니다.

문서 평가

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