생성¶
POST /api/v1/dashboards/create
개요¶
대시보드를 생성하고 리소스 식별자를 반환합니다. 템플릿에서 초기화하는 것을 지원합니다.
호출 전 및 사용 단계¶
이름을 제출하면 빈 대시보드를 생성할 수 있습니다. 레이아웃을 그대로 사용해야 하는 경우 대시보드 내보내기에서 템플릿 내용을 가져와 templateInfo에 입력합니다. 생성에 성공하면 content.uuid를 저장합니다. 이름 또는 사용자 정의 식별자가 충돌하면 기본적으로 HTTP 200과 함께 content.repeatInfo를 반환하므로, 클라이언트는 실제로 생성되었는지 확인해야 합니다. recoverIdentifier=true이면 일치하는 기존 대시보드를 먼저 삭제한 후 생성을 시도합니다. 실행 전에 먼저 백업을 내보내고 각 충돌 객체의 UUID를 확인하며, 실패한 후에는 현재 상태를 조회합니다.
요청 헤더¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 매개변수¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| name | string | Y | 대시보드 표시 이름입니다. null 허용: False 최대 길이: 128 예시: 生产巡检획득 또는 입력 방법: 현재 워크스페이스 내에서 다른 대시보드가 사용하지 않는 이름을 사용합니다. |
| desc | string | 생성 시의 설명입니다. null 허용: False 빈 문자열 허용: True 최대 길이: 2048 예시: 生产服务巡检指标획득 또는 입력 방법: 대시보드 용도를 입력합니다. 템플릿을 사용할 때 생략하거나 빈 값으로 전달하면 템플릿의 summary를 사용합니다. |
|
| recoverIdentifier | boolean | 기본값은 false이며 충돌 상세를 반환합니다. true이면 충돌 객체를 먼저 삭제합니다. null 허용: False 예시: false획득 또는 입력 방법: 최초 제출 시에는 false를 유지합니다. repeatInfo를 받은 후, 일치하는 대시보드를 삭제할 것이 확실할 때만 true로 설정합니다. |
|
| identifier | string | 사용자 정의 식별자 ID이며 최대 128자입니다. 이 값과 UUID는 각각 사용됩니다. null 허용: False 빈 문자열 허용: True 최대 길이: 128 예시: prod-check획득 또는 입력 방법: 호출자의 명명 규칙에 따라 이 워크스페이스 내에서 다른 대시보드가 사용하지 않는 식별자를 지정합니다. |
|
| extend | json | 대시보드 확장 설정입니다. 필요에 따라 기존 필드를 재사용합니다. null 허용: False 예시: {}획득 또는 입력 방법: 대시보드 상세의 content.extend에서 기존 객체를 가져옵니다. |
|
| mapping | array | 대시보드 변수의 필드 매핑 배열입니다. 매핑이 없으면 빈 배열을 전달할 수 있습니다. null 허용: False 예시: []획득 또는 입력 방법: 기존 대시보드의 content.mapping 또는 내보낸 템플릿의 content.dashboardMapping에서 값을 가져옵니다. |
|
| tagNames | array | 시나리오 태그 이름 배열입니다. 비어 있어도 템플릿의 tagInfo를 사용할 수 있으며, 태그가 없는 대시보드를 생성하려면 템플릿의 연관 태그도 함께 정리해야 합니다. null 허용: False 예시: ["team:ops"]획득 또는 입력 방법: 대시보드 상세의 content.tagInfo[].name에서 복사하거나 연결할 태그 이름을 입력합니다. |
|
| templateInfo | json | 대시보드 템플릿 객체이며, main.charts, main.vars, main.groups로 내용을 정의합니다. null 허용: False 빈 문자열 허용: False 예시: {"title": "生产巡检", "summary": "生产服务巡检指标", "identifier": "prod-check", "dashboardType": "CUSTOM", "dashboardExtend": {}, "dashboardMapping": [], "iconSet": {}, "dashboardBindSet": [], "main": {"type": "template", "charts": [], "vars": [], "chartGroupPos": [], "groups": []}}획득 또는 입력 방법: 대시보드 내보내기를 호출하여 실제 응답의 content 객체를 사용합니다. 워크스페이스를 넘어 가져온 후에는 변수, 데이터 소스, 권한을 확인해야 합니다. |
|
| specifyDashboardUUID | string | 선택 사항인 새 대시보드 UUID이며, 전체 형식은 dsbd_custom_ 뒤에 32자리 소문자 영숫자입니다. null 허용: False 빈 문자열 허용: False $matchRegExp: ^dsbd_custom_[a-z0-9]{32}$ 예시: dsbd_custom_1234567890abcdef1234567890abcdef획득 또는 입력 방법: 클라이언트에서 32자리 소문자 영숫자를 생성하여 dsbd_custom_을 이어 붙입니다. 반드시 아직 사용되지 않았는지 먼저 확인합니다. |
|
| isPublic | int | 1은 공개, 0은 생성한 주체만 볼 수 있음, -1은 사용자 정의 권한입니다. 생성 시 전달하지 않으면 기본값은 1입니다. null 허용: False 예시: 1획득 또는 입력 방법: 대상 가시 범위에 따라 1, 0 또는 -1을 선택합니다. |
|
| openPermissionSet | boolean | 과거 호환 필드이며, 현재 생성 처리에서는 isPublic으로 사용자 정의 권한 활성화 여부를 결정합니다. null 허용: False 예시: false획득 또는 입력 방법: 이전 클라이언트와 호환용입니다. 새로운 설정은 isPublic=-1을 사용합니다. |
|
| permissionSet | array | isPublic=-1일 때 사용하는 작업 권한 명단이며, 역할(소유자 제외), 멤버, 팀 UUID를 포함할 수 있습니다. null 허용: False 예시: ["role_example"]획득 또는 입력 방법: 역할 목록, 멤버 목록 또는 팀 목록에서 UUID를 가져옵니다. |
|
| readPermissionSet | array | isPublic=-1일 때 사용하는 읽기 권한 명단이며, 역할(소유자 제외), 멤버, 팀 UUID를 포함할 수 있습니다. null 허용: False 예시: ["role_example"]획득 또는 입력 방법: 역할 목록, 멤버 목록 또는 팀 목록에서 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의 이름과 대응됩니다. |
빈 대시보드를 생성할 때는 최상위 extend와 mapping을 사용할 수 있습니다. 권한은 최상위 isPublic과 명단으로 결정됩니다. 최상위 tagNames를 우선 사용하며, 입력하지 않거나 비어 있으면 템플릿의 tagInfo를 사용할 수도 있습니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/dashboards/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"生产巡检","desc":"生产服务巡检指标","identifier":"prod-check","isPublic":1}'
응답¶
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.declaration | object 또는 null | 워크스페이스의 공용 선언입니다. |
| content.repeatInfo | object | 기본 처리에서 충돌이 발생하면 반환됩니다. 이름, 식별자, 동시 충돌로 그룹화되며, 이 응답에는 새 UUID가 포함되지 않습니다. |
| content.repeatInfo.name_and_identifier | array<object> |
이름과 식별자가 동시에 일치한 충돌 항목입니다. |
| content.repeatInfo.name | array<object> |
이름 충돌 항목입니다. |
| content.repeatInfo.identifier | array<object> |
식별자 충돌 항목입니다. |
| content.repeatInfo.*[].conflictUUIDs | array<string> |
해당 충돌과 관련된 모든 기존 대시보드 UUID입니다. |
| content.repeatInfo.*[].isCrossConflict | boolean | 이름과 식별자가 각각 서로 다른 두 객체와 일치했는지 여부입니다. |
{
"code": 200,
"content": {
"id": 21,
"uuid": "dsbd_example",
"name": "生产巡检",
"desc": "生产服务巡检指标",
"workspaceUUID": "wksp_example",
"identifier": "prod-check",
"ownerType": "node",
"type": "CUSTOM",
"chartPos": [],
"chartGroupPos": [],
"iconSet": {},
"isPublic": 1,
"extend": {},
"mapping": [],
"createdWay": "manual",
"dashboardBindSet": [],
"openPermissionSet": false,
"permissionSet": [],
"readPermissionSet": [],
"tagInfo": [],
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"status": 0,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
이름과 식별자가 모두 충돌할 때의 HTTP 200 응답
{
"code": 200,
"content": {
"repeatInfo": {
"name_and_identifier": [
{
"name": "生产巡检",
"identifier": "prod-check",
"fileName": "",
"importName": "生产巡检",
"importIdentifier": "prod-check",
"existName": "生产巡检",
"existIdentifier": "prod-check",
"nameConflictUUID": "dsbd_example",
"identifierConflictUUID": "dsbd_example",
"existNameIdentifier": "prod-check",
"existIdentifierName": "生产巡检",
"isCrossConflict": false,
"conflictUUIDs": [
"dsbd_example"
]
}
],
"name": [],
"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 객체에 넣습니다. |
| 400 | ft.IdentificationIdExists | 지정한 새 UUID가 이미 사용 중임 | 식별자 ID가 이미 존재합니다 | 아직 사용되지 않은 새 UUID를 선택하거나, 해당 필드를 생략하여 서비스가 할당하도록 합니다. |
| 403 | ft.ForbiddenDashboardOperation | 호출 주체가 대상 대시보드를 조작할 수 없음 | 대시보드【{}】에 대한 작업 권한이 없습니다 | 대시보드의 가시 범위, 작업 권한 부여, 사용하는 API Key를 확인합니다. |
| 403 | ft.ForbiddenFreeEditionLimit | 대상 워크스페이스에 해당 수량 제한이 활성화되어 있고 현재 수량이 상한에 도달함 | 무료 플랜 워크스페이스 {} 가 상한({} 개)에 도달하여 생성할 수 없습니다. 상용 플랜을 개통하면 제한이 해제됩니다 | 워크스페이스 할당량을 확인하고, 현재 수량과 대상 작업에 맞게 조정한 후 다시 시도합니다. |
| 400 | ft.TagScopeMismatch | 태그 이름은 이미 존재하지만 그 범위가 시나리오 태그와 호환되지 않음 | 메시지에 태그 이름과 범위가 포함됩니다. 예: team:ops: ['monitor'] -> scene. | 시나리오 또는 공용 범위의 태그 이름을 선택하거나, 이름을 변경합니다. |
| 406 | ft.ExceedMaxCharacterLimit | 템플릿의 차트, 차트 그룹 또는 태그 이름이 필드 상한을 초과함 | {}이(가) 최대 문자 길이 제한을 초과했습니다 | 차트 및 그룹 이름을 256자 이내로, 태그 이름을 128자 이내로 줄인 후 템플릿을 다시 확인합니다. |
| 406 | ft.InvalidParameter | 지정한 UUID가 운영 엔트리에서 인정되지 않음 | 매개변수{}이(가) 유효하지 않습니다 |
dsbd_custom_ 뒤에 32자리 소문자 영숫자를 붙이거나, 생략하여 시스템이 생성하도록 합니다. |
| 406 | ft.InvalidParameter | 템플릿 구조가 유효하지 않음. 예를 들어 main이 객체가 아니거나 charts, vars, groups가 배열이 아니거나 차트 쿼리 구조가 유효하지 않음 | 매개변수{}이(가) 유효하지 않습니다 |
오류에서 지적된 필드 경로에 따라 템플릿을 수정합니다. 이 버전 내보내기 인터페이스가 반환한 전체 템플릿을 우선 사용합니다. |