가져오기¶
POST /api/v1/dashboards/{dashboard_uuid}/import
개요¶
템플릿으로 지정한 대시보드의 내용을 덮어쓰고 대상 대시보드 UUID는 유지합니다.
호출 전 및 사용 단계¶
먼저 대시보드 내보내기로 대상 대시보드를 백업하고 가져올 템플릿을 검증합니다. main을 포함한 전체 객체를 전달하세요. 대시보드 UUID는 유지됩니다. 기존 차트, 변수, 그룹은 먼저 제거된 후 템플릿으로 재생성되며 차트에는 새 UUID가 생성됩니다. 템플릿은 먼저 검증되고 삭제와 재생성은 동일한 트랜잭션에서 완료됩니다. 실패하면 먼저 상세 정보를 확인하고 현재 내용을 내보낸 후 백업을 기준으로 복구합니다.
경로 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| dashboard_uuid | string | Y | 대상 대시보드 UUID입니다. 예시: dsbd_example가져오기 또는 입력 방법: 대시보드 목록의 content.data[].uuid에서 복사하거나 생성 결과의 content.uuid를 사용할 수도 있습니다. |
요청 헤더¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| templateInfo | json | Y | 비즈니스 필수 템플릿 객체입니다. 누락하면 템플릿 누락 오류가 반환됩니다. 빈 객체로 시도하지 마세요. 빈 객체는 내용을 비울 수 있습니다. null 허용: False 예시: {"title": "生产巡检更新", "summary": "生产服务巡检指标", "identifier": "prod-check-updated", "dashboardType": "CUSTOM", "dashboardExtend": {}, "dashboardMapping": [], "iconSet": {}, "dashboardBindSet": [], "main": {"type": "template", "charts": [], "vars": [], "chartGroupPos": [], "groups": []}}가져오기 또는 입력 방법: 대시보드 내보내기를 호출하고 실제 응답의 content 객체를 사용합니다. 워크스페이스 간 가져오기 후에는 변수, 데이터 소스, 권한을 확인해야 합니다. |
| specifyDashboardUUID | string | 호환 필드로 현재 가져오기 경로에서는 이 필드를 읽지 않습니다. null 허용: False 빈 문자열 허용: False $matchRegExp: ^dsbd_custom_[a-z0-9]{32}$ 예시: dsbd_custom_1234567890abcdef1234567890abcdef가져오기 또는 입력 방법: 새 UUID를 정의해야 할 때는 생성 인터페이스를 사용합니다. 가져오기 시에는 경로의 대상 UUID를 사용하세요. |
매개변수 추가 설명¶
대시보드 템플릿은 내보내기 인터페이스의 content를 사용합니다. main.charts, main.vars, main.groups를 그대로 재사용할 수 있으며, 워크스페이스 간 이동 시에는 데이터 소스를 다시 확인합니다.
| 템플릿 필드 | 입력 방법 |
|---|---|
| title, summary, identifier | 템플릿 제목, 요약, 사용자 정의 식별자입니다. 생성 시 최상위 name과 identifier가 새 값을 결정하며, 최상위 desc가 비어 있거나 생략되면 템플릿의 summary를 사용합니다. 가져오기 시에는 템플릿의 비어 있지 않은 값만 현재 값을 덮어씁니다. |
| dashboardType, dashboardExtend, dashboardMapping | 대시보드 유형, 확장 객체, 변수 매핑입니다. 비어 있지 않은 템플릿은 템플릿의 확장과 매핑을 사용합니다. |
| iconSet | 아이콘 설정 객체입니다. 기존 url과 icon을 포함하여 내보낸 내용을 그대로沿用할 수 있습니다. |
| main.vars | 변수 정의 배열로 제출 순서대로 생성됩니다. |
| main.vars[].name, code | 변수 표시 이름과 쿼리에서 참조하는 키입니다. 기존 쿼리가 참조를 잃지 않도록 동일한 내보내기 템플릿에서 복사하는 것이 좋습니다. 생략하면 빈 문자열입니다. |
| main.vars[].type, datasource | 변수 유형과 데이터 소스입니다. 동일한 유형 변수의 내보낸 값을 복사합니다. type은 대문자로 변환됩니다. |
| main.vars[].definition | 변수 값 설정입니다. 형식은 변수 유형에 따라 달라지며, 같은 유형 변수의 내보낸 구조에 맞춰 입력합니다. 생략하면 {}입니다. |
| main.vars[].multiple, includeStar | 각각 다중 선택 지원 여부와 와일드카드 옵션 포함 여부를 제어합니다. 기본값은 true입니다. |
| main.vars[].hide, isHiddenAsterisk | 변수와 와일드카드 옵션의 숨김 상태를 제어하며 기본값은 0입니다. |
| main.vars[].valueSort, extend | 선택 가능 값 정렬과 확장 설정입니다. 내보낸 템플릿을 따르며, 생략 시 각각 빈 문자열과 빈 객체입니다. |
| main.groups | 차트 그룹 배열입니다. 이름 문자열을 사용하거나 name 및 선택적 extend를 포함하는 객체를 사용할 수 있습니다. 같은 이름은 한 번만 생성됩니다. |
| main.charts | 차트 정의 배열입니다. 가져오기 시 기존 차트 UUID는 무시하고 새로 생성합니다. |
| main.charts[].name, type | 차트 이름과 차트 유형입니다. 이름은 최대 256자이며 기본값은 비어 있습니다. type의 기본값은 line이며, 내보내기에서 실제 유형을 복사할 수 있습니다. |
| main.charts[].queries, extend | 쿼리와 확장 설정입니다. 내부 구조는 차트 유형에 따라 달라지므로 같은 유형 차트의 내보낸 객체를 재사용하는 것이 좋습니다. 생략 시 각각 []와 {}입니다. |
| main.charts[].pos | 차트 레이아웃 객체입니다. 내보낸 항목의 i, x, y, w, h를 재사용할 수 있습니다. |
| main.charts[].group | 그룹 이름 문자열 또는 name을 포함하는 객체이며, 이름은 main.groups의 이름과 대응됩니다. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/dashboards/dsbd_example/import' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"templateInfo":{"title":"生产巡检更新","summary":"生产服务巡检指标","identifier":"prod-check-updated","dashboardType":"CUSTOM","dashboardExtend":{},"dashboardMapping":[],"iconSet":{},"dashboardBindSet":[],"main":{"type":"template","charts":[],"vars":[],"chartGroupPos":[],"groups":[]}}}'
응답¶
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 | 리소스 유형 소속이며, 대시보드는 일반적으로 node입니다. |
| content.type | string | 대시보드 유형이며 예를 들어 CUSTOM입니다. |
| 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.isPublic | integer | 1은 공개, 0은 생성한 주체만 볼 수 있음, -1은 사용자 정의 권한입니다. |
| content.extend | object | 확장 설정입니다. |
| content.mapping | array<object> |
변수 필드 매핑입니다. |
| content.createdWay | string | 리소스 생성 출처입니다. |
| content.dashboardBindSet | array | 뷰 바인딩 설정입니다. |
| 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.creatorInfo | object | 생성자 정보로 빈 객체일 수 있습니다. |
| content.updatorInfo | object | 최근 수정자 정보로 빈 객체일 수 있습니다. |
| content.declaration | object 또는 null | 워크스페이스의 공용 선언입니다. |
| content.skippedTags | array<object> |
일부 태그가 범위 불일치로 건너뛰어진 경우 반환됩니다. |
| content.skippedTags[].name | string | 건너뛴 태그 이름입니다. |
| content.skippedTags[].scope | array<string> |
기존 태그 범위입니다. |
| content.skippedTags[].expectedScope | string | 현재 리소스에서 기대하는 태그 범위입니다. |
| content.skippedTags[].reason | string | 태그가 건너뛰어진 이유입니다. |
{
"code": 200,
"content": {
"id": 21,
"uuid": "dsbd_example",
"name": "生产巡检更新",
"desc": "生产服务巡检指标",
"workspaceUUID": "wksp_example",
"identifier": "prod-check-updated",
"ownerType": "node",
"type": "CUSTOM",
"chartPos": [],
"chartGroupPos": [],
"iconSet": {},
"isPublic": 1,
"extend": {},
"mapping": [],
"createdWay": "import",
"dashboardBindSet": [],
"openPermissionSet": false,
"permissionSet": [],
"readPermissionSet": [],
"tagInfo": [],
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"status": 0,
"declaration": {},
"creatorInfo": {},
"updatorInfo": {}
},
"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 객체에 담습니다. |
| 404 | ft.NotFoundView | 대상 대시보드가 없거나 삭제되었거나 현재 워크스페이스에 없는 경우 | 지정된 뷰를 찾을 수 없습니다 | 현재 워크스페이스 대시보드 목록에서 반환된 UUID로 교체합니다. |
| 403 | ft.ForbiddenDashboardOperation | 호출 주체가 대상 대시보드를 조작할 수 없는 경우 | 대시보드【{}】에 대한 작업 권한이 없습니다 | 대시보드의 공개 범위, 작업 권한, 사용하는 API Key를 확인합니다. |
| 403 | ft.ForbiddenFreeEditionLimit | 대상 워크스페이스에 해당 수량 제한이 활성화되어 있고 현재 수량이 상한에 도달한 경우 | 무료 플랜 워크스페이스 {}이(가) 상한({} 개)에 도달하여 생성할 수 없습니다. 상용 플랜을 개통하면 제한이 해제됩니다 | 워크스페이스 할당량을 확인하고 현재 수량과 대상 작업에 맞게 조정한 후 다시 시도합니다. |
| 400 | ft.IdentificationIdExists | 템플릿의 사용자 정의 식별자가 다른 동종 대시보드에서 이미 사용 중인 경우 | 식별자 ID가 이미 존재합니다 | 템플릿의 identifier를 변경한 후 다시 제출합니다. |
| 406 | ft.ExceedMaxCharacterLimit | 템플릿의 차트, 차트 그룹 또는 태그 이름이 필드 상한을 초과한 경우 | {}이(가) 최대 문자 길이 제한을 초과했습니다 | 차트 및 그룹 이름을 256자 이내, 태그 이름을 128자 이내로 줄인 후 템플릿을 다시 확인합니다. |
| 406 | ft.MissingImportTemplateResourceUUID | 템플릿 객체를 제공하지 않은 경우 | 가져오기 템플릿/가져오기 소스 뷰 UUID 누락 | 내보내기 응답에서 전체 content를 가져와 templateInfo에 넣습니다. |
| 406 | ft.InvalidParameter | 템플릿 구조가 유효하지 않은 경우. 예를 들어 main이 객체가 아니거나 charts, vars, groups가 배열이 아니거나 차트 쿼리 구조가 유효하지 않은 경우 | 매개변수 {}이(가) 유효하지 않습니다 |
오류에서 지적된 필드 경로에 따라 템플릿을 수정합니다. 이 버전의 내보내기 인터페이스가 반환한 전체 템플릿을 우선 사용하세요. |