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
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.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": "城市 按 省/自治区"
  }
}

results matching ""

    No results matching ""

    数据网关 数据集