1. 仪表盘

1.1. 仪表盘说明

1.1.1. 仪表盘 的定义

仪表盘是由多个图表按照一定的业务逻辑排布形成的数据看板。仪表盘属于一个应用。

仪表盘结构说明

字段 类型 描述
appId LONG 仪表盘所属的应用 id
title STRING 仪表盘标题
options OBJECT 仪表盘配置信息
options.layouts MAP key是图表的id，value是图表的位置 {h: 高度, i: "图表id", w: 宽度, x: x轴位置, y: y轴位置}。高级仪表盘布局中的 w 和 h 都不能小于40
options.filters HE 数组 仪表盘的过滤器
options.type STRING 仪表盘类型，可用类型： Dashboard，InfoGraphic，Report
options.backgroundImageIds INTEGER 数组 背景图的 id 列表
options.page OBJECT 仪表盘的页面配置
options.config OBJECT 前端需要的任意数据，后端只存储，不使用
options.hide BOOLEAN 仪表盘隐藏标识,用于表示仪表盘是否处于隐藏状态
hsVersion INTEGER 可选，本次编辑的版本号，从0开始，修改前先GET待修改资源获取当前版本号，修改时带上刚刚获取的版本号，服务端会检查并发冲突。不带版本号不检查并发冲突。

仪表盘隐藏说明

仪表盘可以被设置为隐藏状态,其效果体现在:发布、预览、分享时,被隐藏的仪表盘不可见,且如果直接通过url访问被隐藏的仪表盘,会响应404

1.2. 接口说明

1.2.1. 新增仪表盘

新增仪表盘

请求URL

POST /api/v1/apps/${appId}/dashboards

需要认证：是

请求参数

URL 参数
字段 类型 是否必须 说明
appId INTEGER 是 仪表盘所在的应用 id
Request Body 参数

仪表盘配置信息，见仪表盘结构

返回对象的格式说明

字段 类型 说明
version STRING 当前系统版本哈希值
data OBJECT 仪表盘的完整配置信息，见仪表盘结构

接口示例1: 新增普通仪表盘

POST /api/v1/apps/1/dashboards

{
    "title": "新建仪表盘",
    "options": {
        "type": "Dashboard",
        "charts": [],
        "filters": [],
        "layouts": {},
        "page": {
            "width": 1280,
            "height": 800,
            "padding": [
                0,
                0,
                0,
                0
            ],
            "background": "rgba(255, 255, 255, 1)",
            "showGrid": false
        },
        "config": {
            "theme": "CLASSIC",
            "showGrid": false,
            "background": {
                "image": "",
                "size": "auto",
                "repeat": "no-repeat",
                "position-x": "left",
                "position-y": "top"
            },
            "pc": {
                "w": 12,
                "scale": "4*3",
                "gap": 10
            },
            "mobile": {
                "mode": "auto",
                "w": 6,
                "scale": "1*1",
                "gap": 10
            }
        }
    }
}

接口示例1: 新增高级仪表盘

POST /api/v1/apps/1/dashboards

{
    "title": "新建高级仪表盘",
    "options": {
        "type": "InfoGraphic",
        "charts": [],
        "filters": [],
        "layouts": {},
        "page": {
            "width": 1280,
            "height": 800,
            "padding": [
                0,
                0,
                0,
                0
            ],
            "background": "rgba(255, 255, 255, 1)",
            "showGrid": false
        }
    }
}

接口示例1: 新增报表类型的仪表盘

新建报表的时候，后端会同时创建一个复杂表格，并在接口返回中包含复杂表格对应的chart id。

POST /api/apps/1/dashboards?dataAppId=123&datasetId=4

{
    "title": "新建报表",
    "options": {
        "type": "Report",
        "charts": [],
        "filters": [],
        "layouts": {}
    }
}

返回

{
    "version": "5.0-SNAPSHOT@5f16923#50b0004",
    "code": 0,
    "msg": "success",
    "data": {
        "dashboardContainerOrTab": false,
        "updatedBy": 7,
        "visible": true,
        "chartIds": [
            1
        ],
        "isDelete": false,
        "dashboardContainer": false,
        "filterControllers": [],
        "dashboardInfoGraphic": false,
        "title": "新建报表",
        "createdAt": 1695683588615,
        "hide": false,
        "createdBy": 7,
        "appId": 129721,
        "dashboardTab": false,
        "options": {
            "charts": [
                1
            ],
            "filters": [],
            "type": "Report",
            "config": {
                "mode": {
                    "current": "pc",
                    "pc": true,
                    "mobile": false
                },
                "version": 5000
            },
            "layouts": {
                "1": {
                    "static": false,
                    "w": 12,
                    "moved": false,
                    "h": 6,
                    "x": 0,
                    "i": "1",
                    "y": 0,
                    "placement": "bottom",
                    "type": "chart",
                    "zIndex": 901
                }
            }
        },
        "id": 1,
        "fixSize": false,
        "updatedAt": 1695685489711
    },
    "chartDataStartTimeMillis": 0
}

1.2.2. 更新仪表盘

更新仪表盘的标题或者配置信息。

请求URL

PUT /api/v1/apps/${appId}/dashboards/{dashboardId}

需要认证：是

请求参数

URL 参数
字段 类型 是否必须 说明
appId INTEGER 是 仪表盘所在的应用 id
dashboardId INTEGER 是 仪表盘的 id
Request Body 参数

仪表盘配置信息，见仪表盘结构

返回对象的格式说明

字段 类型 说明
version STRING 当前系统版本哈希值
data OBJECT 仪表盘的完整配置信息，见仪表盘结构

接口示例1: 修改仪表盘中图表的布局信息

PUT /api/v1/apps/1/dashboards/1

{
    "title": "新建高级仪表盘",
    "hsVersion": 1,
    "options": {
        "layouts": {
            "7": {
                "h": 68,
                "i": "7",
                "w": 237,
                "x": 20,
                "y": 20,
                "src": "",
                "link": "",
                "type": "graph",
                "rotate": 0,
                "zIndex": 10000,
                "padding": [
                    20,
                    20,
                    20,
                    20
                ],
                "arrowEnd": "triangle",
                "imageSize": "auto",
                "arrowBegin": "none",
                "arrowStyle": "solid",
                "arrowWidth": 2,
                "borderColor": "rgba(255, 255, 255, 1)",
                "borderStyle": "solid",
                "borderWidth": 0,
                "borderRadius": 0,
                "imagePosition": "center",
                "titlePosition": "left",
                "backgroundColor": "rgba(255, 255, 255, 0)"
            }
        },
        "filters": [],
        "layoutsVersion": "24*12",
        "backgroundImageIds": [
            48
        ],
        "page": {
            "padding": [
                0,
                0,
                0,
                0
            ],
            "background": "rgba(255, 255, 255, 1)",
            "width": 1024,
            "showGrid": false,
            "height": 768
        },
        "type": "InfoGraphic",
        "charts": [
            7,
            8
        ]
    }
}

返回

{
    "version": "3.0-SNAPSHOT@@git.commit.id.abbrev@#null",
    "code": 0,
    "msg": "success",
    "data": {
        "id": 3,
        "title": "新建高级仪表盘",
        "updatedBy": 1,
        "updatedAt": "2020-02-05 15:16:52",
        "appId": 1,
        "options": {
            "layouts": {
                "7": {
                    "h": 68,
                    "i": "7",
                    "w": 237,
                    "x": 20,
                    "y": 20,
                    "src": "",
                    "link": "",
                    "type": "graph",
                    "rotate": 0,
                    "zIndex": 10000,
                    "padding": [
                        20,
                        20,
                        20,
                        20
                    ],
                    "arrowEnd": "triangle",
                    "imageSize": "auto",
                    "arrowBegin": "none",
                    "arrowStyle": "solid",
                    "arrowWidth": 2,
                    "borderColor": "rgba(255, 255, 255, 1)",
                    "borderStyle": "solid",
                    "borderWidth": 0,
                    "borderRadius": 0,
                    "imagePosition": "center",
                    "titlePosition": "left",
                    "backgroundColor": "rgba(255, 255, 255, 0)"
                }
            },
            "filters": [],
            "layoutsVersion": "24*12",
            "hsVersion": 2,
            "backgroundImageIds": [
                48
            ],
            "page": {
                "padding": [
                    0,
                    0,
                    0,
                    0
                ],
                "background": "rgba(255, 255, 255, 1)",
                "width": 1024,
                "showGrid": false,
                "height": 768
            },
            "type": "InfoGraphic",
            "charts": [
                7,
                8
            ]
        },
        "type": "InfoGraphic",
        "dashboardInfoGraphic": true
    }
}

1.2.3. 通过 ID 获取仪表盘信息

请求URL

GET /api/v1/apps/${appId}/dashboards/{dashboardId}

需要认证：是

请求参数

URL 参数
字段 类型 是否必须 说明
appId INTEGER 是 仪表盘所在的应用 id
dashboardId INTEGER 是 仪表盘的 id

返回对象的格式说明

字段 类型 说明
version STRING 当前系统版本哈希值
data OBJECT 仪表盘的完整配置信息，见仪表盘结构

1.2.4. 通过 ID 删除仪表盘

请求URL

DELETE /api/v1/apps/${appId}/dashboards/{dashboardId}

需要认证：是

请求参数

URL 参数
字段 类型 是否必须 说明
appId INTEGER 是 仪表盘所在的应用 id
dashboardId INTEGER 是 仪表盘的 id

返回对象的格式说明

字段 类型 说明
version STRING 当前系统版本哈希值
msg STRING 执行成功返回 success

1.2.5. 批量更新仪表盘主题配置

批量更新仪表盘主题配置

请求URL

PUT /api/v1/apps/${appId}/dashboards/update-theme

需要认证：是

请求参数

URL 参数
字段 类型 是否必须 说明
appId INTEGER 是 仪表盘所在的应用 id
Request Body 参数

仪表盘配置信息，见仪表盘结构。这里只有 options -> config -> theme 的配置会被用于批量修改仪表盘，其它信息都被忽略。

返回对象的格式说明

字段 类型 说明
version STRING 当前系统版本哈希值
data OBJECT 返回被更新的仪表盘个数

接口示例1:

PUT /api/v1/apps/1/dashboards/update-theme

{
    "options": {
        "config": {
            "theme": "hengshi"
        }
    }
}

返回

{
    "version": "3.0-SNAPSHOT@@git.commit.id.abbrev@#null",
    "code": 0,
    "msg": "success",
    "data": 2
}

1.2.6. 下载仪表盘中所有图表的聚合数据

请求URL

GET /api/v1/apps/${apiId}/dashboards/${dashboardId}/download

需要认证：是

请求参数

URL 参数
字段 类型 是否必须 说明
appId INTEGER 是 仪表盘所在的应用 id
dashboardId INTEGER 是 仪表盘的 id

返回结果

返回一个excel文件，文件名是仪表盘的名称，excel文件中每个sheet对应一个图表的聚合数据

获取仪表盘列表

分页查询应用中的仪表盘信息

请求URL

GET /api/apps/{appId}/dashboards

请求参数

URL参数
字段 类型 说明
offset INTEGER 可选，分页字段，起始查询位置
limit INTEGER 可选，分页字段，查询数量
orderBy STRING 可选，排序字段，默认是按照更新时间降序排序
orderType STRING 可选，排序类型，asc - 表示升序，desc - 表示降序
queryCharts BOOLEAN 可选,默认为false，是否查询仪表盘中的chart信息，true - 查询，false - 不查询
showHide BOOLEAN 可选,默认为true，是否查询隐藏仪表盘，true - 查询，false - 不查询

返回对象的格式说明

字段 类型 说明
version STRING 当前系统版本哈希值
data OBJECT 指定数量的仪表盘信息

接口示例1

  1. 请求 
    GET /api/apps/{appId}/dashboards
  2. 响应结果
    {
"version": "3.2-SNAPSHOT@f8dc947#95a976a",
"code": 0,
"msg": "success",
"data": [
 {
   "id": 1,
   "title": "新建仪表盘",
   "createdBy": 1,
   "createdAt": "2020-05-13 14:17:02",
   "updatedBy": 1,
   "updatedAt": "2020-05-13 14:17:02",
   "visible": true,
   "isDelete": false,
   "appId": 45821,
   "accessCount": 1,
   "options": {
     "hide": false,
     "layouts": {},
     "filters": [],
     "page": {
       "padding": [
         0,
         0,
         0,
         0
       ],
       "background": "rgba(255, 255, 255, 1)",
       "width": 1280,
       "showGrid": false,
       "height": 800
     },
     "type": "Dashboard",
     "charts": [],
     "config": {
       "pc": {
         "w": 12,
         "gap": 10,
         "scale": "4*3"
       },
       "mobile": {
         "w": 6,
         "gap": 10,
         "mode": "auto",
         "scale": "1*1"
       },
       "theme": "CLASSIC",
       "showGrid": false
     }
   },
   "hsVersion": 0,
   "creator": {
     "id": 1,
     "name": "test",
     "email": "test@hengshi.com"
   },
   "updater": {
     "id": 1,
     "name": "test",
     "email": "test@hengshi.com"
   },
   "dashboardInfoGraphic": false,
   "type": "Dashboard"
 },
 {
   "id": 2,
   "title": "新建仪表盘 (1)",
   "createdBy": 1,
   "createdAt": "2020-05-13 14:17:06",
   "updatedBy": 1,
   "updatedAt": "2020-05-13 14:17:06",
   "visible": true,
   "isDelete": false,
   "appId": 45821,
   "accessCount": 1,
   "options": {
     "hide": true,
     "layouts": {},
     "filters": [],
     "page": {
       "padding": [
         0,
         0,
         0,
         0
       ],
       "background": "rgba(255, 255, 255, 1)",
       "width": 1280,
       "showGrid": false,
       "height": 800
     },
     "type": "Dashboard",
     "charts": [],
     "config": {
       "pc": {
         "w": 12,
         "gap": 10,
         "scale": "4*3"
       },
       "mobile": {
         "w": 6,
         "gap": 10,
         "mode": "auto",
         "scale": "1*1"
       },
       "theme": "CLASSIC",
       "showGrid": false
     }
   },
   "hsVersion": 0,
   "creator": {
     "id": 1,
     "name": "test",
     "email": "test@hengshi.com"
   },
   "updater": {
     "id": 1,
     "name": "test",
     "email": "test@hengshi.com"
   },
   "dashboardInfoGraphic": false,
   "type": "Dashboard"
 },
 {
   "id": 3,
   "title": "新建仪表盘 (2)",
   "createdBy": 1,
   "createdAt": "2020-05-13 14:17:10",
   "updatedBy": 1,
   "updatedAt": "2020-05-13 14:17:10",
   "visible": true,
   "isDelete": false,
   "appId": 45821,
   "accessCount": 1,
   "options": {
     "hide": true,      
     "layouts": {},
     "filters": [],
     "page": {
       "padding": [
         0,
         0,
         0,
         0
       ],
       "background": "rgba(255, 255, 255, 1)",
       "width": 1280,
       "showGrid": false,
       "height": 800
     },
     "type": "Dashboard",
     "charts": [],
     "config": {
       "pc": {
         "w": 12,
         "gap": 10,
         "scale": "4*3"
       },
       "mobile": {
         "w": 6,
         "gap": 10,
         "mode": "auto",
         "scale": "1*1"
       },
       "theme": "CLASSIC",
       "showGrid": false
     }
   },
   "hsVersion": 0,
   "creator": {
     "id": 8,
     "name": "test",
     "email": "test@hengshi.com"
   },
   "updater": {
     "id": 8,
     "name": "test",
     "email": "test@hengshi.com"
   },
   "dashboardInfoGraphic": false,
   "type": "Dashboard"
 }
],
"totalHits": 3,
"offset": 0
}

接口示例2

  1. 请求 
    GET /api/apps/{appId}/dashboards?queryCharts=true
  2. 响应结果
    {
"version": "3.2-SNAPSHOT@f8dc947#95a976a",
"code": 0,
"msg": "success",
"data": [
 {
   "id": 1,
   "title": "新建仪表盘",
   "createdBy": 1,
   "createdAt": "2020-05-13 14:17:02",
   "updatedBy": 1,
   "updatedAt": "2020-05-13 14:17:02",
   "visible": true,
   "isDelete": false,
   "appId": 45821,
   "accessCount": 1,
   "chartList": [
     {
       "id": 1,
       "title": "新建探索",
       "options": {
         "axes": [],
         "name": "Bar",
         "titleStyle": {}
       }
     }
   ],
   "options": {
     "hide": false,
     "layouts": {},
     "filters": [],
     "page": {
       "padding": [
         0,
         0,
         0,
         0
       ],
       "background": "rgba(255, 255, 255, 1)",
       "width": 1280,
       "showGrid": false,
       "height": 800
     },
     "type": "Dashboard",
     "charts": [],
     "config": {
       "pc": {
         "w": 12,
         "gap": 10,
         "scale": "4*3"
       },
       "mobile": {
         "w": 6,
         "gap": 10,
         "mode": "auto",
         "scale": "1*1"
       },
       "theme": "CLASSIC",
       "showGrid": false
     }
   },
   "hsVersion": 0,
   "creator": {
     "id": 1,
     "name": "test",
     "email": "test@hengshi.com"
   },
   "updater": {
     "id": 1,
     "name": "test",
     "email": "test@hengshi.com"
   },
   "dashboardInfoGraphic": false,
   "type": "Dashboard"
 },
 {
   "id": 2,
   "title": "新建仪表盘 (1)",
   "createdBy": 1,
   "createdAt": "2020-05-13 14:17:06",
   "updatedBy": 1,
   "updatedAt": "2020-05-13 14:17:06",
   "visible": true,
   "isDelete": false,
   "appId": 45821,
   "accessCount": 1,
   "chartList": [
     {
       "id": 2,
       "title": "新建探索2",
       "options": {
         "axes": [],
         "name": "Pie",
         "titleStyle": {}
       }
     }
   ],
   "options": {
     "hide": true,
     "layouts": {},
     "filters": [],
     "page": {
       "padding": [
         0,
         0,
         0,
         0
       ],
       "background": "rgba(255, 255, 255, 1)",
       "width": 1280,
       "showGrid": false,
       "height": 800
     },
     "type": "Dashboard",
     "charts": [],
     "config": {
       "pc": {
         "w": 12,
         "gap": 10,
         "scale": "4*3"
       },
       "mobile": {
         "w": 6,
         "gap": 10,
         "mode": "auto",
         "scale": "1*1"
       },
       "theme": "CLASSIC",
       "showGrid": false
     }
   },
   "hsVersion": 0,
   "creator": {
     "id": 1,
     "name": "test",
     "email": "test@hengshi.com"
   },
   "updater": {
     "id": 1,
     "name": "test",
     "email": "test@hengshi.com"
   },
   "dashboardInfoGraphic": false,
   "type": "Dashboard"
 },
 {
   "id": 3,
   "title": "新建仪表盘 (2)",
   "createdBy": 1,
   "createdAt": "2020-05-13 14:17:10",
   "updatedBy": 1,
   "updatedAt": "2020-05-13 14:17:10",
   "visible": true,
   "isDelete": false,
   "appId": 45821,
   "accessCount": 1,
   "chartList": [],
   "options": {
     "hide": true,      
     "layouts": {},
     "filters": [],
     "page": {
       "padding": [
         0,
         0,
         0,
         0
       ],
       "background": "rgba(255, 255, 255, 1)",
       "width": 1280,
       "showGrid": false,
       "height": 800
     },
     "type": "Dashboard",
     "charts": [],
     "config": {
       "pc": {
         "w": 12,
         "gap": 10,
         "scale": "4*3"
       },
       "mobile": {
         "w": 6,
         "gap": 10,
         "mode": "auto",
         "scale": "1*1"
       },
       "theme": "CLASSIC",
       "showGrid": false
     }
   },
   "hsVersion": 0,
   "creator": {
     "id": 8,
     "name": "test",
     "email": "test@hengshi.com"
   },
   "updater": {
     "id": 8,
     "name": "test",
     "email": "test@hengshi.com"
   },
   "dashboardInfoGraphic": false,
   "type": "Dashboard"
 }
],
"totalHits": 3,
"offset": 0
}

接口示例3

  1. 请求 
    GET /api/apps/{appId}/dashboards?queryCharts=true&showHide=false
  2. 响应结果
{
  "version": "3.2-SNAPSHOT@f8dc947#95a976a",
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "title": "新建仪表盘",
      "createdBy": 1,
      "createdAt": "2020-05-13 14:17:02",
      "updatedBy": 1,
      "updatedAt": "2020-05-13 14:17:02",
      "visible": true,
      "isDelete": false,
      "appId": 45821,
      "accessCount": 1,
      "chartList": [
        {
          "id": 1,
          "title": "新建探索",
          "options": {
            "axes": [],
            "name": "Bar",
            "titleStyle": {}
          }
        }
      ],
      "options": {
        "hide": false,
        "layouts": {},
        "filters": [],
        "page": {
          "padding": [
            0,
            0,
            0,
            0
          ],
          "background": "rgba(255, 255, 255, 1)",
          "width": 1280,
          "showGrid": false,
          "height": 800
        },
        "type": "Dashboard",
        "charts": [],
        "config": {
          "pc": {
            "w": 12,
            "gap": 10,
            "scale": "4*3"
          },
          "mobile": {
            "w": 6,
            "gap": 10,
            "mode": "auto",
            "scale": "1*1"
          },
          "theme": "CLASSIC",
          "showGrid": false
        }
      },
      "hsVersion": 0,
      "creator": {
        "id": 1,
        "name": "test",
        "email": "test@hengshi.com"
      },
      "updater": {
        "id": 1,
        "name": "test",
        "email": "test@hengshi.com"
      },
      "dashboardInfoGraphic": false,
      "type": "Dashboard"
    }
  ],
  "totalHits": 1,
  "offset": 0
}

1.2.7. 异步导出仪表盘PNG/PDF

请求URL

POST /api/apps/{appId}/dashboards/{dashboardId}/async-export

需要认证：是

请求参数

URL 参数
字段 类型 是否必须 说明
appId LONG 是 仪表盘所在的应用 id
dashboardId LONG 是 仪表盘id
type STRING 否 传png或者pdf
timeout INTEGER 否 导出超时时间，timeout内完成，直解返回二进制流下载，timeout未完成或出现异常，返回json信息
width INTEGER 否 宽度
height INTEGER 否 单页的高度
totalHeight INTEGER 否 整个页面的总高度
Request Body 参数

DownloadDto

字段 类型 是否必须 说明
app OBJECT 否 全局过滤器 见应用结构
dashboard OBJECT 否 仪表盘过滤器 见仪表盘结构
chartNames MAP 否 chart名称map，key为chartId

返回对象的格式说明

如果导出任务没有完成，返回PENDING状态；若任务已完成，返回png/pdf格式文件流下载，文件名是仪表盘的名称

接口示例1: 导出仪表盘PDF

POST /api/apps/41589/dashboards/1/async-export?type=pdf&timeout=170000

{
  "app": {
    "id": 41589,
    "options": {
      "filters": []
    }
  },
  "dashboard": {
    "id": 1,
    "options": {
      "filters": []
    }
  }
}

接口示例2: 导出仪表盘PNG

POST /api/apps/41589/dashboards/1/async-export?type=png&timeout=170000&width=1255&height=1049&totalHeight=1295

{
  "app": {
    "id": 41589,
    "options": {
      "filters": []
    }
  },
  "dashboard": {
    "id": 1,
    "options": {
      "filters": []
    }
  },
  "chartNames": {
    "2": "邮寄方式 按 省/自治区",
    "3": "城市 按 省/自治区"
  }
}

1.2.8. 复制仪表盘

请求URL

POST /api/v1/apps/${appId}/dashboards/{dashboardId}/duplicate

需要认证：是

请求参数

URL 参数
字段 类型 是否必须 说明
appId INTEGER 是 仪表盘所在的应用 id
dashboardId INTEGER 是 仪表盘的 id
title STRING 否 新仪表盘的标题
Request Body 参数

只复制仪表盘，不修改的情况下，传空的 json 即可。

返回对象的格式说明

字段 类型 说明
version STRING 当前系统版本哈希值
msg STRING 执行成功返回 success

results matching ""

    No results matching ""

    数据网关 过滤控件

    衡石文档