# 指南
# 概述
- LiteBI是一款专为API设计的报表软件,可以快速构建图表(柱状图、饼图、折线图、散点图、地图等),可快速创建仪表板
- 不依赖其他软件(只需要JDK环境),一键启动,支持windows、linux、macOS
- 支持图表、仪表板链接分享,方便将图表、仪表板嵌入到其他系统。
- 仅支持API数据源,对API做了丰富的场景适配。支持动态http参数值,支持token验证,支持定期获取token,支持复杂嵌套的json参数,支持header传参
# 演示网站
- 演示网站 (opens new window)
- 账号密码:admin/admin (请不要修改密码)
# 为什么选择LiteBI?
传统BI工具是在页面上配置数据库账号,然后在页面对数据进行分析汇总(比如选择表、维度字段、指标字段、指标函数),然后选择图形类型,配置图形参数,最后将分析结果以图形展示。这就面临一个问题,报表工具和分析数据的业务逻辑强耦合,比方说如果要切换报表工具,那上面的分析过程就要重做一遍,并且分析汇总后的结果数据只有报表工具自身持有,无法对其他系统提供数据服务。
LiteBI的设计理念认为报表系统应该前后端分离,报表工具仅仅只是一个图形渲染工具,不应该关心数据分析汇总的逻辑,数据分析应该全部放在后端服务中,数据通过API与报表对接,这样分析汇总的结果数据永远在后端接口服务中持有,后端接口服务可以对各个系统提供数据服务,并且一旦报表工具切换,数据资产仍然存在,不需要重新进行数据分析。
鉴于以上理念,LiteBI设计成仅支持API数据源。如果您已经有大量的数据类API,比如您已经有DBAPI (opens new window)平台,LiteBI将是您不错的BI软件选择。又或者您非常看重数据资产化,希望分析数据全部放在后端接口服务中,LiteBI将是您不错的BI软件选择。
有朋友会问其他BI工具也支持API数据源,为什么选择LiteBI?答案是LiteBI对API的支持做了很多适配设计,支持API使用的各种场景(同类产品对API的支持都是不足的)。比如说API访问的时候要进行token验证,支持定期获取token,也支持token失效的时候重新获取token;支持API传参,包括复杂嵌套的json参数;支持动态参数值,比如把页面上输入框、选择框的值作为请求参数去访问API获取数据。
轻量化、简单、易用也是LiteBI遵循的设计理念,除了JDK,软件的安装不依赖其他软件,可以一键启动。软件对资源消耗极低,2核4g服务器即可运行。页面交互设计非常简洁,图表的创建操作简单,在数据API已有的情况下,半分钟即可创建一张图。如果搭配DBAPI (opens new window)(零代码创建API工具)的使用,可以让您高效快捷的进行数据分析。如果您处在中小企业、传统行业,数据分析团队小,开发能力不足,这样一款小巧简便的BI工具,会是您不错的选择。
# 基本概念
# 图表
- 最基础的图表,可以是表格、柱状图、饼图、折线图、散点图、地图等。
# 仪表板
- 仪表板是图表的集合,可以创建仪表板,将多个图表拼接成仪表板。类似于可视化数据大屏。仪表板中还可以添加输入控件,例如输入框、下拉选择器、日期选择器等,控件中的数据可以作为变量传入图表中,实现图表数据按条件动态变化。
# 变量
- 变量分为系统变量和局部变量
- 系统变量是系统中的全局变量,在API的传参中可以引用系统变量作为参数。比如API接口鉴权需要携带token,所有的API都需要使用token,就可以创建一个系统变量token,给多个图表中的API使用。并且系统变量可以设置是从API获取,并且可以定时访问API进行更新,保证token没有过期。
- 局部变量只在仪表板中存在,仪表板中的每个输入控件(文本输入框、下拉选择器、日期选择器等等)会绑定一个局部变量名,仪表板中的图表中的API就可以引用此局部变量作为请求参数。典型场景是根据输入条件筛选数据。
# 快速开始
# 登录
- 访问
http://localhost:7000/login
,默认用户名密码:admin/admin
# 创建第一个图表
- 选择图表菜单,点击创建图表按钮
- 进入图表编辑页面,选择折线图
- 填写基本信息
图表名称填写第一个图表
- 填写API数据集
LiteBI系统自带测试的数据API,地址是
http://localhost:7000/test/data1
,我们使用此API来创建折线图
方法选择post,
请求地址填写http://localhost:7000/test/data1
(注意IP端口要改成您自己的IP和端口),
其余项不填。
- 点击预览API数据按钮,您可以看到API返回的数据
- 填写图表参数
分类字段填写month 指标字段填写apple
- 预览图表
点击预览按钮,可以看到图表
- 保存图表
点击保存按钮,即可保存图表
- 返回图表列表
点击图表菜单,可以看到创建了第一个图表
- 预览图表
鼠标悬浮在图上会显示一些操作按钮,点击查看按钮,可以在新页面看到图表
- 编辑图表
点击编辑按钮,进入编辑页面,您可以修改配置再保存
- 删除图表
点击删除按钮,在弹出的确认窗口中点确认,即可删除图表
- 分享图表链接
点击分享按钮,弹窗中填写过期时间,即可生成分享链接,该链接可以嵌入其他系统的页面(使用iframe标签)。 过期时间如果填写-1表示永久有效。
# 创建第一个仪表板
- 选择仪表板菜单,点击创建仪表板按钮,进入仪表板编辑页面
- 选择左侧图表菜单,可以看到展示了所有图表,点击图表右上角的添加按钮,即可添加到仪表板
- 选中图表可以拖动位置
- 鼠标悬浮在图表右下角,可以拖动改变图表尺寸
- 填写仪表板名称,点击保存按钮保存
- 点击仪表板菜单,查看仪表板列表
- 点击查看按钮,可以在单独的页面查看整个仪表板
- 点击编辑按钮,可以进入修改仪表板页面
- 点击删除按钮,可以删除仪表板
- 点击分享按钮,在弹窗中填写过期时间,即可生成分享链接,该链接可以嵌入其他系统的页面(使用iframe标签)
过期时间如果填写-1表示永久有效。
- 分享链接可以在链接管理页面查看
# API配置
- LiteBI设计遵循一切数据皆来源于API,图表的数据均来自于API,系统变量的值可以来源于API,仪表板中部分控件的参数也可以来源于API(比如下拉选择器的所有选项)
- 可以配置API的请求地址、请求方法、请求参数、请求头、数据转换脚本。
# 请求方法
- LiteBI支持GET和POST两种请求方法
# 请求地址
- 请求地址填写http协议的url,比如
http://localhost:7000/test/data1
注意因为LiteBI使用js代码访问API,所以API端要设置跨域
# 请求参数
如果是GET类型请求,参数只能写在地址中,比如
http://localhost:7000/test/data?name=litebi&num=1
, 如果参数值中有变量,可以使用${变量名}
格式,比如http://localhost:7000/test/data?name=${name}&num=${num}
如果是POST类型请求,参数写在参数输入框中,使用JSON格式填写,比如
{"name":"litebi","num":1}
, 如果参数值中有变量,可以使用${变量名}
格式,比如{"name":${name},"num":${num}}
注意参数值如果是字符串变量,不需要在变量引用外层使用引号包裹
# 请求头
请求头默认包含一项
Content-Type: application/x-www-form-urlencoded
,可以配置多个请求头,点击添加按钮,可以创建多个请求头对于POST类型请求,可以传入多层嵌套JSON格式的参数,比如
{"name":"litebi","num":1,"data":{"name":"litebi","num":1}}
如果您要传入嵌套JSON格式的参数,必须将请求头
Content-Type
设置为application/json
请求头的值可以使用变量值,包括仪表板中的局部变量和系统变量,使用
${变量名}
格式典型使用场景是API鉴权,需要添加Authorization请求头,其值就是token,token又是一个系统变量,就可以如下填写
# API数据转换
- 不同图表需要的数据格式不同,如果API返回的数据格式和图表需要的数据格式不一致,可以配置数据转换脚本,将API返回的数据转换成图表需要的数据格式。
- 数据转换脚本有2种类型,JSONPath和 JavaScript 。脚本编写规则请参考数据转换脚本
如果不填写表示API返回的数据不需要转换
# 图表
- 图表的创建和编辑,需要填写基本信息、API数据集、图表参数3部分。
- 其中基本信息、API数据集每种图表配置方式都一样,只有图表参数配置不同。API数据集配置方法参考API配置,以下就介绍不同图表的参数配置。
# 柱状图
- 柱状图要求API返回数据(或者数据转换后的数据)格式必须是对象数组格式,比如:
[{
"banana": 200,
"apple": 100,
"month": "2024-01"
}, {
"banana": 190,
"apple": 78,
"month": "2024-02"
}, {
"banana": 157,
"apple": 150,
"month": "2024-03"
}, {
"banana": 120,
"apple": 100,
"month": "2024-04"
}
]
- X轴字段填写分类的字段,以上面的数据为例,月份就是分类字段,所以填写month
- 数据字段填写需要展示的数据字段,填写apple,就展示apple对应的数据
- 图例如果需要显示就勾选,否则不显示
- 标签代表柱子上的数据,如果需要显示就勾选,否则不显示
- 可以制作分组柱状图,点击数据字段的添加按钮,填写新的字段banana
# 堆叠柱状图
- 堆叠柱状图要求API返回数据(或者数据转换后的数据)格式必须是对象数组格式,比如:
[{
"banana": 200,
"apple": 100,
"month": "2024-01"
}, {
"banana": 190,
"apple": 78,
"month": "2024-02"
}, {
"banana": 157,
"apple": 150,
"month": "2024-03"
}, {
"banana": 120,
"apple": 100,
"month": "2024-04"
}
]
- X轴字段填写分类的字段,以上面的数据为例,月份就是分类字段,所以填写month
- 数据字段填写需要展示的数据字段,填写apple,就展示apple对应的数据。点击添加按钮,可以追加新的数据字段,进行堆叠显示
- 图例如果需要显示就勾选,否则不显示
- 标签代表柱子上的数据,如果需要显示就勾选,否则不显示
# 折线图
- 折线图要求API返回数据(或者数据转换后的数据)格式必须是对象数组格式,比如:
[{
"banana": 200,
"apple": 100,
"month": "2024-01"
}, {
"banana": 190,
"apple": 78,
"month": "2024-02"
}, {
"banana": 157,
"apple": 150,
"month": "2024-03"
}, {
"banana": 120,
"apple": 100,
"month": "2024-04"
}
]
- X轴字段填写分类的字段,以上面的数据为例,月份就是分类字段,所以填写month
- 数据字段填写需要展示的数据字段,填写apple,就展示apple对应的数据
- 图例如果需要显示就勾选,否则不显示
- 标签代表柱子上的数据,如果需要显示就勾选,否则不显示
- 圆滑折线,勾选后折线变成曲线显示
- 可以制作分组折线图,点击数据字段的添加按钮,填写新的字段banana
# 堆叠折线图
- 堆叠折线图要求API返回数据(或者数据转换后的数据)格式必须是对象数组格式,比如:
[{
"banana": 200,
"apple": 100,
"month": "2024-01"
}, {
"banana": 190,
"apple": 78,
"month": "2024-02"
}, {
"banana": 157,
"apple": 150,
"month": "2024-03"
}, {
"banana": 120,
"apple": 100,
"month": "2024-04"
}
]
- X轴字段填写分类的字段,以上面的数据为例,月份就是分类字段,所以填写month
- 数据字段填写需要展示的数据字段,填写apple,就展示apple对应的数据。点击添加按钮,可以追加新的数据字段,进行堆叠显示
- 图例如果需要显示就勾选,否则不显示
- 标签代表折线上的数据,如果需要显示就勾选,否则不显示
# 面积图
- 配置同折线图
- 折线可以圆滑显示,可以勾选
# 堆叠面积图
配置同堆叠折线图
折线可以圆滑显示,可以勾选
# 柱线混合图
- 堆叠折线图要求API返回数据(或者数据转换后的数据)格式必须是对象数组格式,比如:
[{
"banana": 200,
"apple": 100,
"month": "2024-01"
}, {
"banana": 190,
"apple": 78,
"month": "2024-02"
}, {
"banana": 157,
"apple": 150,
"month": "2024-03"
}, {
"banana": 120,
"apple": 100,
"month": "2024-04"
}
]
- X轴字段填写分类的字段,以上面的数据为例,月份就是分类字段,所以填写month
- 柱图数据字段,填写柱状图需要展示的数据字段,填写apple,就展示apple对应的数据。
- 折线数据字段,填写折线图需要展示的数据字段,填写banana,就展示banana对应的数据。
- 柱图、折线图都可以添加多组数据,添加添加按钮,添加字段即可
- 图例如果需要显示就勾选,否则不显示
- 标签代表折线上的数据,如果需要显示就勾选,否则不显示
# 条形图
- 柱状图要求API返回数据(或者数据转换后的数据)格式必须是对象数组格式,比如:
[{
"banana": 200,
"apple": 100,
"month": "2024-01"
}, {
"banana": 190,
"apple": 78,
"month": "2024-02"
}, {
"banana": 157,
"apple": 150,
"month": "2024-03"
}, {
"banana": 120,
"apple": 100,
"month": "2024-04"
}
]
- Y轴字段填写分类的字段,以上面的数据为例,月份就是分类字段,所以填写month
- 数据字段填写需要展示的数据字段,填写apple,就展示apple对应的数据
- 图例如果需要显示就勾选,否则不显示
- 标签代表柱子上的数据,如果需要显示就勾选,否则不显示
- 可以制作分组条形图,点击数据字段的添加按钮,填写新的字段banana
# 堆叠条形图
# 饼图
# 环形图
# 半环形图
# 南丁格尔玫瑰图
# 表格
# 水球图
# 数字
# 雷达图
# 仪表板
- 仪表板由图表和控件组成,可以添加已经创建好的图表到仪表板,如果需要条件筛选,可以添加控件到仪表板中。
# 图表操作
# 控件
- 当图表数据需要切换参数,就会使用到控件
# 系统变量
- 系统变量是系统中的全局变量,在API的传参中可以引用系统变量作为参数。
- 比如API接口鉴权需要携带token,所有的API都需要使用token,就可以创建一个系统变量_token,给多个图表中的API使用
- 系统变量值的引用使用
${变量名}
格式,例如${_token}
注意系统变量的名称必须是以下划线
_
开头,不能使用其他字符开头,例如_token
# 系统变量类型
- 系统变量类型有3种,常量值、API、JS
JS暂不支持,在后续版本中会支持
# 常量值
- 顾名思义,就是常量值作为系统变量。直接在页面填写常量值
# API
- 通过API访问获取变量的值,这个值是一个动态值,需要设置更新策略,包含定时刷新和过期刷新两种策略。
# 定时刷新策略
设置固定频率,后台会定时访问API获取值,并更新变量值。
# 过期刷新策略
这种方式要求API返回的数据为JSON格式,并且包含过期时间字段(其值必须是时间戳毫秒格式)
- 页面上设置过期时间提取表达式和数据提取表达式,每次访问API,后台会根据数据提取表达式提取数据作为变量值存下来,并且会根据过期时间提取表达式来提取过期时间保存下来,以后每次用到此变量的时候,会先检查变量的过期时间,判断是否过期,如果过期,则重新访问API获取值(并保存新的值和过期时间),否则直接使用保存的值。
# 数据转换脚本
如果API返回的数据格式和图表需要的数据格式不一致,可以配置数据转换脚本,将API返回的数据转换成图表需要的数据格式。
# JSONPath语法
要求API返回的数据必须是JSON格式
符号 | 含义 |
---|---|
$ | 表示整个数据 |
@ | 表示当前数据 |
. | 访问属性 |
[] | 访问数组 |
* | 匹配所有 |
[,] | 访问数组指定索引 |
[?] | 匹配条件 |
[?(condition)] | 匹配条件 |
[?(@.age>18)] | 匹配age大于18的 |
- 示例1:
原始数据:
{
"name": "张三",
"age": 18,
"address": {
"province": "浙江",
"city": "杭州"
}
}
表达式结果如下
$.name
张三
$.age
18
$.address
{
"province": "浙江",
"city": "杭州"
}
$.address.province
浙江
- 示例2:
原始数据
{
data: [
{
"name": "张三",
"age": 18,
"address": {
"province": "浙江",
"city": "杭州"
}
},
{
"name": "李四",
"age": 20,
"address": {
"province": "上海",
"city": "上海"
}
}
],
success: true,
message: "success"
}
表达式结果如下
$.data[*]
[
{
"name": "张三",
"age": 18,
"address": {
"province": "浙江",
"city": "杭州"
}
},
{
"name": "李四",
"age": 20,
"address": {
"province": "上海",
"city": "上海"
}
}
]
# JavaScript语法
使用JavaScript脚本,要求有return关键字,
_data
表示API返回的数据示例1:
原始数据
{
data: [
{
"name": "张三",
"age": 18,
"address": {
"province": "浙江",
"city": "杭州"
}
},
{
"name": "李四",
"age": 20,
"address": {
"province": "上海",
"city": "上海"
}
}
],
success: true,
message: "success"
}
脚本填写
return _data.data.map(item => {
return {
name: item.name,
age: item.age,
address: item.address.province + '-' + item.address.city
}
})
结果
[
{
"name": "张三",
"age": 18,
"address": "浙江-杭州"
},
{
"name": "李四",
"age": 20,
"address": "上海-上海"
}
]