식별자 ID 가져오기¶
POST /api/v1/board/import/identifier
개요¶
식별자를 기준으로 사이트 전체에서 기존 대시보드/사용자 뷰 콘텐츠를 덮어쓰거나 시스템 뷰 템플릿을 업데이트합니다.
호출 전 준비 및 사용 단계¶
w 권한이 있는 사이트 External AK/SK가 필요합니다(External API 서명 인증). 이 엔드포인트는 workspaceUUID를 받지 않으며 identifier에 따라 사이트 전체에서 활성 CUSTOM 워크스페이스 객체와 선택한 시스템 언어 템플릿을 선택합니다. 먼저 백업하고 동일 식별자의 모든 리소스를 점검해야 하며, 비어 있지 않은 정확한 식별자를 사용해야 합니다. 워크스페이스 대상은 전체 콘텐츠 덮어쓰기입니다. 기존 차트/그룹/변수를 소프트 삭제하고 ID를 다시 생성한 다음 템플릿 콘텐츠를 저장합니다. main, dashboardExtend, dashboardMapping 등을 생략해도 원래 값이 유지되지 않습니다. 제목만 변경하려면 워크스페이스 범위가 있는 일반 수정 API를 사용해야 합니다. title/summary/iconSet/바인딩 설정에는 각각 비어 있지 않은 경우에만 덮어쓰는 호환 규칙이 있으므로 이전 설명의 "전달하지 않으면 모두 유지"를 적용할 수 없습니다. 현재 구현은 동일한 배치의 워크스페이스 대상에 템플릿 객체를 재사용합니다. 차트 pos/group/uuid는 첫 번째 대상을 처리할 때 제자리에서 가져가므로 이후 대상의 레이아웃/그룹이 달라질 수 있습니다. 여러 대상이 동일한 레이아웃을 유지해야 한다면 각 워크스페이스의 단일 리소스 가져오기 엔드포인트로 나누는 것을 우선하고, 이 전역 엔드포인트는 HTTP 200만 보지 말고 대상을 하나씩 검증해야 합니다. innerViewerZh/En은 언어 선택의 시작점일 뿐입니다. 조회 시 먼저 요청 언어에 사용자 정의가 아닌 템플릿이 있어야 하며, 사용자 정의 템플릿만 있거나 해당 언어 템플릿이 없으면 대체할 수 있습니다(zh→en, en→zh). 따라서 innerViewerEn이 중국어 템플릿을 선택하고 status=3(삭제 상태)으로 설정할 수 있으며, 두 분기를 동시에 선택하면 동일 템플릿을 먼저 업데이트한 뒤 삭제할 수 있으므로 "영어 리소스만 수정"이라고 할 수 없습니다. 두 분기는 최종 템플릿 meta에 원래 있던 키만 덮어쓰며, 실제 UPDATE는 status=0만 일치합니다. 조회에서 0이 아닌 레코드를 선택하면 업데이트 없이도 성공할 수 있습니다. 실행 전에 identifier 기준으로 두 언어의 시스템/사용자 정의 레코드를 점검하고 최종 선택 언어와 UUID를 확인해야 하며, 응답 배열은 이러한 시스템 템플릿의 업데이트 결과를 제공하지 않습니다. 각 대상/언어는 독립적으로 커밋되며 전체 배치 롤백이나 항목별 오류 결과가 없습니다. 실패 시 앞선 대상은 이미 업데이트되었을 수 있습니다. 태그 범위가 맞지 않으면 건너뛸 수 있지만 배열은 skippedTags 요약을 제공하지 않습니다. 성공 시 content는 워크스페이스 리소스 결과만 나열하며, []는 일치 항목 없음, importType 미인식 또는 시스템 템플릿만 처리했음을 의미할 수 있습니다. 가져오기는 차트 UUID를 재생성하므로 이전 차트에 연결된 외부 참조는 별도로 검증해야 합니다. 데이터소스/함수/변수는 대상 워크스페이스에서 유효해야 하며, 저장 성공이 차트 쿼리 실행 가능성을 보장하지 않습니다.
요청 헤더¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 원본 경로 및 요청 본문 서명 버전입니다. 생략한 뒤 이 페이지의 알고리즘을 계속 사용할 수 없습니다. 예: v20240417가져오기 또는 입력 방법: 이 페이지의 예제는 이 고정 버전을 사용하며 예제 서명 알고리즘과 함께 사용됩니다. |
|
| X-Df-Access-Key | string | Y | 읽기 API는 r 또는 w 자격 증명을 사용할 수 있고, 쓰기 API는 w 자격 증명이 필요합니다. 예: <external-access-key>가져오기 또는 입력 방법: 사이트 관리자가 할당한 External API AK를 사용하며, 워크스페이스 OpenAPI Key는 사용할 수 없습니다. |
| X-Df-Nonce | string | Y | 임시 일련번호입니다. 실패 후 재전송할 때도 새 값을 생성하고 서명을 다시 계산합니다. 예: 97d275ee9f774315a7885ba7347acbd9가져오기 또는 입력 방법: 매 요청마다 uuid.uuid4().hex를 다시 생성합니다. |
| X-Df-Signature | string | Y | 대문자 메서드, nonce, 원본 전체 경로, timestamp와 원본 UTF-8 요청 본문을 공백으로 연결한 뒤 HMAC-SHA256을 수행하고 hex 다이제스트를 사용합니다. 예: <hmac-sha256-hex>가져오기 또는 입력 방법: External API 서명 인증에 따라 함께 제공된 SK로 계산하며, 전체 실행 가능한 템플릿은 아래와 같습니다. |
| X-Df-Timestamp | string | Y | 사이트에 구성된 서명 유효 시간 범위 내에 있어야 하며 예제 시간을 재사용할 수 없습니다. 예: 1785427200가져오기 또는 입력 방법: 전송 시 str(int(time.time()))로 현재 Unix 초 문자열을 생성합니다. |
요청 본문 파라미터¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| importType[*] | string | 단일 덮어쓰기 범주이며, 중국어 표시 이름이나 ownerType 값으로 대체할 수 없습니다. 예: dashboard가져오기 또는 입력 방법: 위의 네 가지 정확한 문자열 중에서 선택합니다. |
|
| templateInfo.title | string | 워크스페이스 리소스는 비어 있지 않은 참 값일 때만 name을 대체하며, 생략하거나 빈 문자열이면 기존 제목을 유지합니다. 시스템 템플릿 분기는 meta에 원래 같은 이름의 키가 있을 때만 덮어쓰며, 빈 값도 그대로 덮어씁니다. 예: 业务指标가져오기 또는 입력 방법: 내보낸 템플릿 title에서 조정합니다. |
|
| templateInfo.summary | string | 워크스페이스 리소스는 비어 있지 않은 참 값일 때만 desc를 대체하며, 생략하거나 빈 문자열이면 기존 설명을 유지합니다. 시스템 meta 키 덮어쓰기 로직과 다릅니다. 예: 核心业务指标가져오기 또는 입력 방법: 템플릿 summary에서 조정합니다. |
|
| templateInfo.identifier | string | 워크스페이스 리소스는 비어 있지 않을 때만 식별자를 대체하며, 현재 전역 경로는 단일 워크스페이스 고유성 외부 검사를 수행하지 않습니다. 변경 후 다음부터는 이전 식별자로 더 이상 선택되지 않습니다. 읽기 전용 위치 키로 간주하지 마세요. 예: my-unique-dashboard-template가져오기 또는 입력 방법: 원본 템플릿 identifier를 유지하며, 마이그레이션이 정말 필요하면 먼저 영향을 점검합니다. |
|
| templateInfo.dashboardType | string | 워크스페이스 가져오기에서 누락 시 CUSTOM으로 재설정하며 기존 type을 유지하지 않습니다. CUSTOM을 유지하는 것이 좋습니다. main.type은 이 필드가 아닙니다. 예: CUSTOM가져오기 또는 입력 방법: 유효한 내보내기 템플릿 유형을 유지합니다. |
|
| templateInfo.dashboardExtend | json | 워크스페이스 가져오기에서 extend를 전체 덮어쓰며, 생략 시 기본값은 {}입니다. 증분 병합으로 오해하면 안 됩니다. 동적 키는 내보내기 형식에 따라 유지합니다. 예: {}가져오기 또는 입력 방법: 내보낸 템플릿의 전체 대시보드 확장 설정을 복사합니다. |
|
| templateInfo.dashboardMapping | array | 워크스페이스 가져오기에서 mapping을 전체 덮어쓰며, 생략 시 기본값은 []입니다. 각 항목의 동적 JSON은 유효한 내보내기 형식에 따라 유지하며, 이 경로는 비즈니스 구조를 보완하지 않습니다. 예: []가져오기 또는 입력 방법: 내보낸 뷰 변수 필드 매핑 배열을 복사합니다. |
|
| templateInfo.dashboardMapping[*] | json | 단일 전체 매핑 객체입니다. 이전의 빈 헤더를 보고 매핑 키를 추측하여 만들지 마세요. 예: {}가져오기 또는 입력 방법: 대상 템플릿의 실제 매핑 구성 한 건을 복사합니다. |
|
| templateInfo.iconSet | json | 워크스페이스 리소스는 객체가 비어 있지 않을 때만 대체하며, 생략하거나 {}이면 기존 아이콘을 유지합니다. 키는 원래 구성대로 저장합니다. 최상위 icon/thumbnail은 현재 워크스페이스 분기에서 별도로 사용하지 않습니다. 예: {"url": "", "icon": ""}가져오기 또는 입력 방법: 내보낸 아이콘 객체를 유지합니다. |
|
| templateInfo.iconSet.url | string | 선택적 아이콘 URL이며, 표시 여부는 클라이언트 구성에 따릅니다. 다른 브랜드의 고정 리소스 도메인을 사용하지 마세요. 예: https://example.com/icon.png가져오기 또는 입력 방법: 자신이 접근 가능한 아이콘 리소스에서 주소를 가져오거나 원래 값을 유지합니다. |
|
| templateInfo.iconSet.icon | string | 선택적 작은 아이콘 구성 값이며, 실제 구조는 원본 내보내기를 기준으로 합니다. 예: chart가져오기 또는 입력 방법: 콘솔에서 내보낸 아이콘 식별자/구성을 유지합니다. |
|
| templateInfo.dashboardBindSet | array | 비어 있지 않은 참 값일 때만 대체하며, 생략하거나 []이면 기존 바인딩을 유지합니다. 비우는 것이 아닙니다. 예: []가져오기 또는 입력 방법: 대상의 유효한 내보내기 템플릿에서 전체 바인딩 설정을 유지합니다. |
|
| templateInfo.dashboardBindSet[*] | json | 원래 바인딩 구성의 동적 구조대로 저장하며, 이 엔드포인트는 리소스 소속을 완전히 검증하지 않습니다. 예: {}가져오기 또는 입력 방법: 유효한 내보내기의 바인딩 객체 한 건을 복사합니다. |
|
| templateInfo.tags | array | node 워크스페이스 대시보드는 이름으로 태그 연결을 재설정하며, 비어 있지 않은 tags를 우선 사용합니다. 생략하거나 []이면 tagInfo를 시도하고, 둘 다 없으면 비웁니다. 동일 이름의 scene/all이 아닌 태그는 가져오기 컨텍스트에서 건너뛰지만 기존 연결을 지울 수 있으며, 배열 응답은 skippedTags 요약을 제공하지 않습니다. userViewer의 실제 inner 분기는 이러한 시나리오 태그 업데이트를 거치지 않습니다. 예: ["production"]가져오기 또는 입력 방법: 대상 워크스페이스에 이미 있는 scene/all 태그 이름 또는 필요한 비즈니스 태그에서 선택하고, 먼저 범위를 확인합니다. |
|
| templateInfo.tags[*] | string | 단일 태그 이름이며 최대 128자입니다. 새 이름은 대상 워크스페이스에서 scene 태그를 생성할 수 있습니다. 예: production가져오기 또는 입력 방법: 해당 태그 name을 복사하고 tag_UUID를 사용하지 않습니다. |
|
| templateInfo.tagInfo | array | tags에 비어 있지 않은 값이 없을 때만 각 항목의 name으로 태그를 선택하며, 의미는 tags와 같습니다. 추가가 아니며 tagInfo.uuid로 교차 워크스페이스 태그를 지정할 수 없습니다. 예: [{"name": "production"}]가져오기 또는 입력 방법: 내보내기 형식에 이미 tagInfo가 있으면 유지합니다. |
|
| templateInfo.tagInfo[*] | json | name만 읽으며, 나머지 클라이언트 표시 필드는 연결을 결정하지 않습니다. 예: {"name": "production"}가져오기 또는 입력 방법: 유효한 내보내기 태그 정보에서 복사합니다. |
|
| templateInfo.tagInfo[*].name | string | 단일 태그 이름입니다. 예: production가져오기 또는 입력 방법: 대상에 이미 있는/새 비즈니스 태그 이름에서 가져옵니다. |
|
| templateInfo.main | json | 차트, 그룹, 변수의 전체 대상입니다. 생략하거나 {}이면 빈 컬렉션으로 재생성되며, 제목만 변경하는 패치로 사용할 수 없습니다. 예: {"groups": [], "charts": [], "vars": []}가져오기 또는 입력 방법: 유효한 전체 내보내기 템플릿 main을 복사합니다. |
|
| templateInfo.main.type | string | 구형 템플릿의 시스템 유형 정보이며, 현재 워크스페이스 재생성에서는 이것으로 dashboardType을 대체하지 않습니다. 예: dashboard가져오기 또는 입력 방법: 원본 템플릿의 시스템 표시를 유지합니다. |
|
| templateInfo.main.groups | array | 그룹 목록이며 이름 문자열 또는 {name,extend} 객체를 지원합니다. 같은 이름은 중복 제거됩니다. 생략하거나 []이면 비우고 그룹 UUID를 재생성합니다. 예: ["业务指标"]가져오기 또는 입력 방법: 내보낸 템플릿의 그룹 순서대로 복사하며, 수정 시 차트 group이 해당 이름과 대응하도록 보장합니다. |
|
| templateInfo.main.groups[*] | string 또는 object | 문자열이면 그룹 이름이고, 객체이면 name/extend를 읽으며 name이 빈 객체는 무시합니다. 그룹 이름은 최대 256자입니다. 예: {"name": "业务指标", "extend": {}}가져오기 또는 입력 방법: 내보낸 그룹 구조에서 복사합니다. |
|
| templateInfo.main.groups[*].name | string | 객체 형식의 그룹 이름이며 비어 있을 수 없습니다. 차트는 동일 이름 group으로 그룹화됩니다. 예: 业务指标가져오기 또는 입력 방법: 그룹 이름을 직접 정의하거나 기존 내보내기 이름을 복사합니다. |
|
| templateInfo.main.groups[*].extend | json | 선택적 그룹 확장 객체이며 생략 시 {}입니다. 예: {}가져오기 또는 입력 방법: 그룹 접기 등 내보내기 설정을 유지합니다. |
|
| templateInfo.main.charts | array | 전체 차트 집합입니다. 생략하거나 []이면 기존 차트를 삭제하고 재생성하지 않습니다. 기존 chart UUID는 삭제되고 새 ID가 생성됩니다. 예: []가져오기 또는 입력 방법: 유효한 내보내기 템플릿에서 전체 차트 배열을 복사하며, 상세 chartPos로 대체할 수 없습니다. |
|
| templateInfo.main.charts[*] | json | 차트 객체이며, type이 문자열, queries가 배열, 각 query가 객체인지 검증합니다. 모든 클라이언트 확장 키가 서버에서 완전히 검증되는 것은 아닙니다. 예: {"name": "CPU空闲", "type": "line", "queries": [{"qtype": "dql", "query": {"q": "M::`cpu`:(`usage_idle`)"}}], "pos": {"x": 0, "y": 0, "w": 12, "h": 6}}가져오기 또는 입력 방법: 콘솔에서 검증된 차트 내보내기 객체를 복사하고 실제 쿼리 문을 수정합니다. |
|
| templateInfo.main.charts[*].name | string | 누락되거나 빈 값이면 빈 제목이며 최대 256자입니다. 예: CPU空闲가져오기 또는 입력 방법: 차트 표시 이름을 입력합니다. |
|
| templateInfo.main.charts[*].type | string | 기본값은 line이고 저장 시 소문자로 변환되며, 현재 sequence 하나만 있는 것이 아닙니다. 지원 유형은 콘솔 내보내기를 기준으로 합니다. 예: line가져오기 또는 입력 방법: 유효한 내보내기 차트 유형을 유지합니다. 예: line 또는 combine. |
|
| templateInfo.main.charts[*].uuid | string | 제공하더라도 버리고 새 차트 ID를 재생성합니다. 이전 차트 연결을 유지하는 데 사용할 수 없습니다. 예: chrt_example가져오기 또는 입력 방법: 이전 내보내기에서 포함될 수 있으나 일반 호출에서는 입력할 필요가 없습니다. |
|
| templateInfo.main.charts[*].group | json | 문자열 그룹 이름, {name:그룹 이름} 또는 null일 수 있습니다. 대응하는 그룹이 없으면 default로 분류됩니다. 객체는 name으로 해석합니다. 예: {"name": "业务指标"}가져오기 또는 입력 방법: 이번 main.groups의 이름과 정확히 일치시킵니다. |
|
| templateInfo.main.charts[*].group.name | string | 그룹 이름이며 null이면 그룹화하지 않음을 의미합니다. 예: 业务指标가져오기 또는 입력 방법: 이번 main.groups의 name을 참조합니다. |
|
| templateInfo.main.charts[*].pos | json | 레이아웃 객체이며 생략 시 {}입니다. 클라이언트 레이아웃 단위로 해석되고 서버는 그대로 저장하며, 이전 설명의 string을 강제 숫자 계약으로 간주하지 않습니다. 예: {"x": 0, "y": 0, "w": 12, "h": 6}가져오기 또는 입력 방법: 내보낸 레이아웃에서 복사합니다. |
|
| templateInfo.main.charts[*].pos.x | number | 가로 위치이며 클라이언트 그리드 단위입니다. 예: 0가져오기 또는 입력 방법: 내보낸 그리드 가로 좌표를 복사합니다. |
|
| templateInfo.main.charts[*].pos.y | number | 세로 위치입니다. 예: 0가져오기 또는 입력 방법: 내보낸 그리드 세로 좌표를 복사합니다. |
|
| templateInfo.main.charts[*].pos.w | number | 너비입니다. 예: 12가져오기 또는 입력 방법: 내보낸 그리드 너비를 복사합니다. |
|
| templateInfo.main.charts[*].pos.h | number | 높이입니다. 예: 6가져오기 또는 입력 방법: 내보낸 그리드 높이를 복사합니다. |
|
| templateInfo.main.charts[*].pos.i | string | 선택적 클라이언트 레이아웃 표시이며 새 차트의 실제 UUID로 사용되지 않습니다. 예: chart-position가져오기 또는 입력 방법: 원본 내보내기의 표시 표시(있는 경우)를 유지합니다. |
|
| templateInfo.main.charts[*].extend | json | 전체 차트 확장 객체이며 생략 시 {}입니다. 중첩 키는 차트 유형에 따라 동적이며 현재 원본 JSON대로 저장하고, 필요한 클라이언트 설정을 자동으로 보완하지 않습니다. 예: {}가져오기 또는 입력 방법: settings/style 등 유효한 내보내기 차트 확장 구성을 완전히 유지합니다. |
|
| templateInfo.main.charts[*].queries | array | 일반 차트는 쿼리 객체 배열이고, combine 바깥은 하위 차트 객체이며 각 하위 차트가 자체 queries 배열을 포함합니다. 문자열/단일 객체로 배열을 대체할 수 없습니다. 예: [{"qtype": "dql", "query": {"q": "M::`cpu`:(`usage_idle`)"}}]가져오기 또는 입력 방법: 검증된 차트 내보내기 쿼리 구조에서 복사합니다. |
|
| templateInfo.main.charts[*].queries[*] | json | 일반 쿼리 객체는 qtype/query를 읽고 추가 표시 키는 유지합니다. combine 하위 차트 uuid는 첫 번째 main 및 기타 고유 내부 ID로 정규화되며, 중첩 queries를 재귀적으로 검증합니다. 예: {"qtype": "dql", "query": {"q": "M::`cpu`:(`usage_idle`)"}}가져오기 또는 입력 방법: 일반은 내보낸 쿼리 객체를 사용하고, combine은 내보낸 전체 하위 차트 객체를 사용합니다. |
|
| templateInfo.main.charts[*].queries[*].qtype | string | 일반 쿼리 유형이며, 이 가져오기 호출에서 쿼리를 실행하거나 비즈니스 데이터 존재를 검증하지 않습니다. 예: dql가져오기 또는 입력 방법: dql/promql 등 실제 쿼리 구문 유형을 사용합니다. |
|
| templateInfo.main.charts[*].queries[*].query | json | 일반 쿼리 파라미터 동적 객체입니다. query 키가 있으면 객체여야 하며, 시간/변수/데이터소스 필드는 유효한 내보내기대로 유지합니다. 이 엔드포인트는 저장만 하고 이를 통해 데이터 쿼리를 동기적으로 실행하지 않습니다. 예: {"q": "M::`cpu`:(`usage_idle`)"}가져오기 또는 입력 방법: 유효한 내보내기 쿼리 객체를 복사하며, 실제 필드는 동기화 쿼리 파라미터를 참고합니다. |
|
| templateInfo.main.charts[*].queries[*].query.q | string | 일반 쿼리 문이며 템플릿 변수를 포함할 수 있습니다. 교차 워크스페이스 템플릿은 실제 데이터셋/필드/변수 사용 가능 여부를 확인해야 합니다. 예: M::`cpu`:(`usage_idle`)가져오기 또는 입력 방법: 대상 워크스페이스 쿼리 도구에서 검증한 후 DQL/PromQL을 복사합니다. |
|
| templateInfo.main.charts[*].queries[*].query.outerDatasourceInfo | json | 관리형 참조는 configMd5에 따라 대상 워크스페이스에서 uuid를 다시 바인딩합니다. 일치 항목을 찾지 못하면 이전 워크스페이스 uuid를 제거하지만 다이제스트는 유지하며, 데이터소스를 생성하지 않습니다. funcServerId 등 함수 참조는 대상 워크스페이스 구성을 확인해야 하며, 이 경로는 완전한 리소스 마이그레이션이 아닙니다. 예: {"configMd5": "<exported-config-digest>"}가져오기 또는 입력 방법: 관리형 외부 데이터소스 참조는 내보낸 configMd5를 유지하고, 각 대상 워크스페이스에 동일 내용의 데이터소스를 미리 구성해야 합니다. |
|
| templateInfo.main.charts[*].queries[*].query.outerDatasourceInfo.configMd5 | string | 대상 데이터소스 구성 일치 다이제스트입니다. 예: <exported-config-digest>가져오기 또는 입력 방법: 유효한 내보내기 값을 직접 사용하고, 비즈니스 다이제스트를 수동으로 생성하지 않습니다. |
|
| templateInfo.main.charts[*].queries[*].queries | array | 결합 하위 차트 계층에서만 사용하며 내부 구조는 일반 queries와 같고 재귀할 수 있습니다. 일반 query 객체로 간주하지 마세요. 예: []가져오기 또는 입력 방법: combine 차트에서 유효하게 내보낸 하위 차트 쿼리 배열을 유지합니다. |
|
| templateInfo.main.vars | array | 전체 변수 집합이며 생략하거나 []이면 비웁니다. 배열 순서에 따라 seq를 0부터 다시 설정하고 UUID를 생성합니다. 예: []가져오기 또는 입력 방법: 유효하게 내보낸 전체 뷰 변수 배열을 복사합니다. |
|
| templateInfo.main.vars[*] | json | 변수 객체이며 name/code/type은 앞뒤 공백이 제거되고 type은 대문자로 변환됩니다. 변수 유형별 definition/extend 동적 구조는 콘솔의 유효한 내보내기를 유지해야 하며, 서버는 여기서 프런트엔드 의미를 전면 검증하지 않습니다. 예: {"name": "主机", "code": "host", "type": "QUERY", "definition": {}}가져오기 또는 입력 방법: 대상에서 사용 가능한 템플릿의 변수 객체를 내보내고, 이름을 보고 definition 형식을 추측하지 않습니다. |
|
| templateInfo.main.vars[*].name | string | 표시 이름이며 기본값은 빈 값이고 앞뒤 공백을 제거합니다. 예: 主机가져오기 또는 입력 방법: 유효한 내보내기 변수 객체에서 복사하고 이 템플릿 쿼리 참조와 확인합니다. |
|
| templateInfo.main.vars[*].code | string | 변수 코드이며 기본값은 빈 값이고 앞뒤 공백을 제거합니다. 쿼리의 변수 참조와 일치해야 합니다. 예: host가져오기 또는 입력 방법: 유효한 내보내기 변수 객체에서 복사하고 이 템플릿 쿼리 참조와 확인합니다. |
|
| templateInfo.main.vars[*].type | string | 변수 유형이며 기본값은 빈 값이고 이후 대문자로 변환됩니다. 콘솔에서 유효하게 내보낸 유형을 사용합니다. 예: QUERY가져오기 또는 입력 방법: 유효한 내보내기 변수 객체에서 복사하고 이 템플릿 쿼리 참조와 확인합니다. |
|
| templateInfo.main.vars[*].definition | json | 변수 유형에 따라 내보낸 정의를 전체 복사하며 기본값은 {}입니다. 예: {}가져오기 또는 입력 방법: 유효한 내보내기 변수 객체에서 복사하고 이 템플릿 쿼리 참조와 확인합니다. |
|
| templateInfo.main.vars[*].datasource | string | 선택적 데이터소스 유형이며 기본값은 빈 문자열이고 원본 내보내기대로 유지합니다. 예: metric가져오기 또는 입력 방법: 유효한 내보내기 변수 객체에서 복사하고 이 템플릿 쿼리 참조와 확인합니다. |
|
| templateInfo.main.vars[*].valueSort | string | 선택적 값 정렬이며 기본값은 빈 문자열입니다. 예: asc가져오기 또는 입력 방법: 유효한 내보내기 변수 객체에서 복사하고 이 템플릿 쿼리 참조와 확인합니다. |
|
| templateInfo.main.vars[*].hide | integer | 숨김 표시 스위치이며 기본값은 0입니다. 예: 0가져오기 또는 입력 방법: 유효한 내보내기 변수 객체에서 복사하고 이 템플릿 쿼리 참조와 확인합니다. |
|
| templateInfo.main.vars[*].isHiddenAsterisk | integer | 숨김 별표 옵션 스위치이며 기본값은 0입니다. 예: 0가져오기 또는 입력 방법: 유효한 내보내기 변수 객체에서 복사하고 이 템플릿 쿼리 참조와 확인합니다. |
|
| templateInfo.main.vars[*].multiple | boolean | 다중 선택 여부이며 기본값은 true입니다. 예: true가져오기 또는 입력 방법: 유효한 내보내기 변수 객체에서 복사하고 이 템플릿 쿼리 참조와 확인합니다. |
|
| templateInfo.main.vars[*].includeStar | boolean | 별표 옵션 포함 여부이며 기본값은 true입니다. 예: true가져오기 또는 입력 방법: 유효한 내보내기 변수 객체에서 복사하고 이 템플릿 쿼리 참조와 확인합니다. |
|
| templateInfo.main.vars[*].extend | json | 변수 확장 객체이며 기본값은 {}이고 원본 내보내기대로 전체 복사합니다. 예: {}가져오기 또는 입력 방법: 유효한 내보내기 변수 객체에서 복사하고 이 템플릿 쿼리 참조와 확인합니다. |
|
| templateInfo.main.vars[*].seq | integer | 가져올 때 배열 위치로 재계산하며 이 값으로 최종 순서를 제어하지 않습니다. 예: 0가져오기 또는 입력 방법: 유효한 내보내기 변수 객체에서 복사하고 이 템플릿 쿼리 참조와 확인합니다. |
|
| identifier | string | Y | 필수 문자열이며 사이트 전체의 현재 활성 CUSTOM 리소스 및 선택한 범주와 정확히 일치시키고 워크스페이스에 제한되지 않습니다. 빈 문자열을 전달하지 마세요(현재 비어 있음을 강제하지 않아 식별자가 없는 많은 객체와 일치할 수 있음). 먼저 동일 식별자의 모든 리소스를 점검해야 하며, 이것은 리소스 UUID가 아닙니다. null 허용: False 예: my-unique-dashboard-template가져오기 또는 입력 방법: 업데이트하려는 대시보드/뷰 상세 또는 내보내기 템플릿의 identifier에서 실제이고 비어 있지 않은 식별자를 가져옵니다. |
| importType | array | Y | 필수 배열입니다. dashboard는 ownerType=node인 워크스페이스 대시보드를 업데이트하고, userViewer는 실제로 ownerType=inner인 워크스페이스 사용자 뷰와 일치하며, innerViewerZh/En은 각각 zh/en을 언어 조회 시작점으로 사용하지만 실제로는 대체(zh→en, en→zh)가 발생하므로 언어 격리 보장이 아닙니다. 해당 언어의 사용자 정의 템플릿만 있어도 우선 일치를 보장하지 않습니다. 알 수 없는 값은 무시하고 []이면 처리하지 않으며, 이를 사용해 워크스페이스를 지정할 수 없습니다. null 허용: False 예: ["dashboard"]가져오기 또는 입력 방법: 필요에 따라 dashboard, userViewer, innerViewerZh, innerViewerEn 중 하나 이상을 선택하고, 작업 전에 사이트 전체 영향을 확인합니다. |
| templateInfo | json | 선언상 선택 사항이지만 실제로는 전체 대상에 맞게 제공해야 합니다. 생략하거나 {}이면 원래 콘텐츠를 유지하는 것이 아닙니다. 각 워크스페이스 대상은 여전히 기존 차트/그룹/변수를 삭제하고 레이아웃/extend/mapping 등을 재설정합니다. 이 페이지는 기존 일치 리소스를 덮어쓰는 데 사용하며, 일치하지 않는 워크스페이스 리소스를 생성하지 않습니다. 빈 문자열 허용: False null 허용: False 예: {"title": "业务指标", "main": {"groups": [], "charts": [], "vars": []}}가져오기 또는 입력 방법: 검증된 대시보드/사용자 뷰 내보내기 템플릿에서 전체 객체를 가져오고, 각 대상을 먼저 백업합니다. 상세 엔터티를 템플릿으로 직접 사용하지 마세요. |
파라미터 추가 설명¶
이 API는 사이트 수준 전역 덮어쓰기이며, 템플릿 파일 업로드나 새 대시보드 생성이 아닙니다. 워크스페이스별 페이지네이션, dryRun, 비동기 작업 진행률 또는 전체 배치 트랜잭션을 지원하지 않습니다. 템플릿을 전달하지 않는다고 해서 사전 검증을 의미하지 않습니다. 템플릿 main/차트/변수/확장의 기타 클라이언트 동적 키는 유효한 내보내기를 기준으로 하며, 알 수 없는 키가 서버 지원을 약속하는 것은 아닙니다. 리소스의 실제 필드는 이 페이지에서 명시적으로 소비하는 키를 기준으로 합니다.
요청 예제¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 대상 사이트 주소 및 관리자가 할당한 External API AK/SK로 교체합니다.
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'POST'
path = '/api/v1/board/import/identifier'
query = {}
data = {'importType': ['dashboard'], 'identifier': 'my-unique-dashboard-template', 'templateInfo': {'title': '业务指标', 'dashboardType': 'CUSTOM', 'dashboardExtend': {}, 'dashboardMapping': [], 'main': {'groups': [], 'charts': [], 'vars': []}}}
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
응답¶
HTTP 200, application/json 표준 External 래퍼를 사용하고 content는 배열입니다. declaration, 전체 수량, 시스템 템플릿 결과 또는 대상별 실패 목록은 없습니다. 반환값은 이번에 실행된 워크스페이스 리소스의 엔터티 스냅샷이며, 전체 새 차트/변수 상세는 포함하지 않습니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content | 객체 배열 | 워크스페이스 dashboard/userViewer 일치 객체의 업데이트 결과만 포함합니다. 일치 항목이 없거나 시스템 템플릿만 처리한 경우에도 []를 반환하며, 대상별 실행 보고서가 아닙니다. |
| content[].id | integer | 대시보드 레코드 번호입니다. |
| content[].uuid | string | 대시보드 UUID이며 상세, 수정, 삭제 및 캐러셀에 사용됩니다. |
| content[].workspaceUUID | string | 소속 워크스페이스입니다. |
| content[].name | string | 대시보드 표시 이름입니다. |
| content[].desc | string | 대시보드 설명입니다. |
| content[].identifier | string | 외부 사용자 정의 식별자이며 비어 있을 수 있습니다. |
| content[].ownerType | string | 이 엔드포인트의 dashboard는 node이고, userViewer는 현재 구현상 inner입니다. ownerType=viewer가 아닙니다. |
| 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 | 이번 쓰기는 import입니다. |
| 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 | 이 경로는 Dashboard 업데이트 주체를 적극적으로 갱신하지 않으므로 이전 값일 수 있으며, sys임을 보장하지 않습니다. |
| content[].createAt | number | 생성 시간, Unix 초입니다. |
| content[].updateAt | number | 이 경로의 콘텐츠 재생성은 Dashboard._update_time을 적극적으로 호출하지 않으므로 원래 업데이트 시간일 수 있습니다. 이를 근거로 이번 배치 적용 여부를 판단할 수 없습니다. |
| content[].deleteAt | number | 삭제 시간, Unix 초입니다. 삭제되지 않은 경우 -1입니다. |
| content[].creatorInfo | object | 생성자 정보이며 빈 객체일 수 있습니다. |
| content[].updatorInfo | object | 최근 업데이트자 정보이며 빈 객체일 수 있습니다. |
| content[].iconSet.url | string | 선택적 아이콘 URL입니다. |
| content[].iconSet.icon | JSON 값 | 선택적 작은 아이콘 구성입니다. |
| content[].chartPos[].pos.x | number | 가로 그리드 위치입니다. |
| content[].chartPos[].pos.y | number | 세로 그리드 위치입니다. |
| content[].chartPos[].pos.w | number | 너비입니다. |
| content[].chartPos[].pos.h | number | 높이입니다. |
| content[].mapping[] | object | 전체 매핑 항목이며 동적 키는 원본 템플릿을 따릅니다. |
| content[].extend.기타 키 | JSON 값 | 대시보드 확장 원본 값입니다. |
| content[].tagInfo[].tagPermissionInfo.permissionSet | 문자열 배열 | 선택적 작업 권한 주체입니다. |
| content[].tagInfo[].tagPermissionInfo.readPermissionSet | 문자열 배열 | 선택적 읽기 권한 주체입니다. |
| content[].creatorInfo.uuid | string | ID UUID이며 시스템 ID는 비어 있을 수 있습니다. |
| content[].creatorInfo.status | integer | 계정 레코드 상태입니다. |
| content[].creatorInfo.wsAccountStatus | integer | 선택적 상태입니다. 요약 읽기에는 대상 워크스페이스가 전달되지 않으므로 대상 워크스페이스 멤버 유효성을 증명하는 데 사용하지 않습니다. |
| content[].creatorInfo.username | string | 로그인 이름입니다. |
| content[].creatorInfo.name | string | 표시 이름입니다. |
| content[].creatorInfo.iconUrl | string | 선택적 아바타입니다. |
| content[].creatorInfo.email | string | 이메일 또는 시스템 ID 표시입니다. |
| content[].creatorInfo.mobile | string | 선택적 휴대폰 번호입니다. |
| content[].creatorInfo.countryCode | string | 선택적 휴대폰 번호 국가 코드입니다. |
| content[].creatorInfo.acntWsNickname | string | 선택적 워크스페이스 닉네임입니다. |
| content[].updatorInfo.uuid | string | ID UUID이며 시스템 ID는 비어 있을 수 있습니다. |
| content[].updatorInfo.status | integer | 계정 레코드 상태입니다. |
| content[].updatorInfo.wsAccountStatus | integer | 선택적 상태입니다. 요약 읽기에는 대상 워크스페이스가 전달되지 않으므로 대상 워크스페이스 멤버 유효성을 증명하는 데 사용하지 않습니다. |
| content[].updatorInfo.username | string | 로그인 이름입니다. |
| content[].updatorInfo.name | string | 표시 이름입니다. |
| content[].updatorInfo.iconUrl | string | 선택적 아바타입니다. |
| content[].updatorInfo.email | string | 이메일 또는 시스템 ID 표시입니다. |
| content[].updatorInfo.mobile | string | 선택적 휴대폰 번호입니다. |
| content[].updatorInfo.countryCode | string | 선택적 휴대폰 번호 국가 코드입니다. |
| content[].updatorInfo.acntWsNickname | string | 선택적 워크스페이스 닉네임입니다. |
| content[].tagInfo[].tagPermissionInfo.id | integer | 태그 권한 부여 레코드 번호입니다. |
| content[].tagInfo[].tagPermissionInfo.uuid | string | 태그 권한 부여 레코드 UUID입니다. |
| content[].tagInfo[].tagPermissionInfo.workspaceUUID | string | 소속 워크스페이스입니다. |
| content[].tagInfo[].tagPermissionInfo.tagUUID | string | 태그 UUID입니다. |
| content[].tagInfo[].tagPermissionInfo.type | string | 권한 부여 리소스 유형이며 기본값은 dashboard입니다. |
| content[].tagInfo[].tagPermissionInfo.status | integer | 활성 레코드는 0입니다. |
| content[].tagInfo[].tagPermissionInfo.creator | string | 생성자 ID입니다. |
| content[].tagInfo[].tagPermissionInfo.updator | string | 업데이트자 ID입니다. |
| content[].tagInfo[].tagPermissionInfo.createAt | integer | 생성 Unix 초입니다. |
| content[].tagInfo[].tagPermissionInfo.updateAt | integer | 업데이트 Unix 초입니다. |
| content[].tagInfo[].tagPermissionInfo.deleteAt | integer | 삭제 Unix 초이며 삭제되지 않은 경우 -1입니다. |
| content[].tagInfo[].tagPermissionInfo.permissionSetInfo | object | 선택적 작업 권한 주체에서 표시 정보로의 매핑이며, 계정 요약 또는 역할/팀 name/status입니다. |
| content[].tagInfo[].tagPermissionInfo.readPermissionSetInfo | object | 선택적 읽기 권한 주체 표시 정보 매핑입니다. |
| content[].tagInfo[].tagPermissionInfo.permissionSetInfo.식별자 | object | 주체 표시 객체입니다. |
| content[].tagInfo[].tagPermissionInfo.permissionSetInfo.식별자.uuid | string | 계정 선택적 UUID입니다. |
| content[].tagInfo[].tagPermissionInfo.permissionSetInfo.식별자.name | string | 표시 이름입니다. |
| content[].tagInfo[].tagPermissionInfo.permissionSetInfo.식별자.status | integer | 레코드 상태입니다. |
| content[].tagInfo[].tagPermissionInfo.permissionSetInfo.식별자.wsAccountStatus | integer | 계정 워크스페이스 상태입니다. |
| content[].tagInfo[].tagPermissionInfo.permissionSetInfo.식별자.username | string | 계정 로그인 이름입니다. |
| content[].tagInfo[].tagPermissionInfo.permissionSetInfo.식별자.iconUrl | string | 선택적 아바타입니다. |
| content[].tagInfo[].tagPermissionInfo.permissionSetInfo.식별자.email | string | 선택적 이메일입니다. |
| content[].tagInfo[].tagPermissionInfo.permissionSetInfo.식별자.mobile | string | 선택적 휴대폰 번호입니다. |
| content[].tagInfo[].tagPermissionInfo.permissionSetInfo.식별자.countryCode | string | 선택적 국가 코드입니다. |
| content[].tagInfo[].tagPermissionInfo.permissionSetInfo.식별자.acntWsNickname | string | 선택적 워크스페이스 닉네임입니다. |
| content[].tagInfo[].tagPermissionInfo.readPermissionSetInfo.식별자 | object | 주체 표시 객체입니다. |
| content[].tagInfo[].tagPermissionInfo.readPermissionSetInfo.식별자.uuid | string | 계정 선택적 UUID입니다. |
| content[].tagInfo[].tagPermissionInfo.readPermissionSetInfo.식별자.name | string | 표시 이름입니다. |
| content[].tagInfo[].tagPermissionInfo.readPermissionSetInfo.식별자.status | integer | 레코드 상태입니다. |
| content[].tagInfo[].tagPermissionInfo.readPermissionSetInfo.식별자.wsAccountStatus | integer | 계정 워크스페이스 상태입니다. |
| content[].tagInfo[].tagPermissionInfo.readPermissionSetInfo.식별자.username | string | 계정 로그인 이름입니다. |
| content[].tagInfo[].tagPermissionInfo.readPermissionSetInfo.식별자.iconUrl | string | 선택적 아바타입니다. |
| content[].tagInfo[].tagPermissionInfo.readPermissionSetInfo.식별자.email | string | 선택적 이메일입니다. |
| content[].tagInfo[].tagPermissionInfo.readPermissionSetInfo.식별자.mobile | string | 선택적 휴대폰 번호입니다. |
| content[].tagInfo[].tagPermissionInfo.readPermissionSetInfo.식별자.countryCode | string | 선택적 국가 코드입니다. |
| content[].tagInfo[].tagPermissionInfo.readPermissionSetInfo.식별자.acntWsNickname | string | 선택적 워크스페이스 닉네임입니다. |
{
"code": 200,
"content": [],
"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 객체를 제출합니다. |
| 406 | ft.InvalidParameter | 템플릿 main/groups/charts/vars 구조, 차트 type/group 또는 queries/query 구조가 유효하지 않음 | 파라미터 {}가 유효하지 않음 |
전체 유효한 내보내기 템플릿을 사용하고 content.reason/오류 파라미터 경로에 따라 수정합니다. |
| 406 | ft.ExceedMaxCharacterLimit | 차트/그룹 이름이 256자를 초과하거나 태그 이름이 128자를 초과함 | {}이(가) 최대 문자 길이 제한을 초과함 | 이름을 줄이고, 사이트 전체 덮어쓰기를 시작하기 전에 모든 대상 템플릿을 검증합니다. |
| 404 | ft.NotFoundView | 이미 찾은 워크스페이스 리소스가 후속 가져오기 전에 사라지거나 삭제됨 | 지정된 뷰를 찾을 수 없음 | 사이트 전체에서 동일 식별자 리소스를 다시 점검하고, 대상 처리가 완료되었는지 확인한 후 처리합니다. |
| 500 | ft.InternalServerError | 이전 콘텐츠, 템플릿 유형, 관리형 데이터소스/태그/구성, 데이터베이스 또는 반환 정보 처리 예외 | 내부 오류 | traceId를 보관하고, 사전 백업에 따라 대상별로 현재 차트/그룹/변수/시스템 템플릿 상태를 확인하며 전체 배치를 무작정 재실행하지 않습니다. 일부 대상은 이미 커밋되었을 수 있습니다. |