1. 概述编辑
1.1 版本
报表服务器版本 | 插件版本 |
---|---|
11.0 | 1.0.6 |
1.2 应用场景
这个插件的本源,是一个web服务的框架。能够依托于FineReport,方便开发人员快速构建向中心系统以外的其他系统,提供安全、灵活、规范、有效的web服务
1.3 功能描述
插件可以通过服务的形式已经把数据库的原始数据,转换成指标数据
插件采用统一的校验规范来保障采集数据的一致性,完整性和准确性
数据服务统一在FR进行开发和管理,降低开发成本
插件可以通过简单的后台开发,安全可靠的向第三方系统提供更灵活的传参方式的接口服务
2. 插件介绍编辑
2.1 插件安装
点击下载插件:开发平台插件
设计器插件安装方法请参见:设计器插件管理
服务器安装插件方法请参见:服务器插件管理
2.2 操作方法
在安装插件之后我们在使用管理员登陆FR的决策平台后可以看到如下的功能菜单(超管可分配权限给子管理员使用)
点开后会看到4个选项卡,分别具有以下的功能和特性
2.2.1 客户端操作
客户端是我们插件服务功能调用的主体对象,通常是第三方应用系统的服务端。这些系统都有相同的诉求场景,即获取FR的某些数据信息、借助FR提交某些数据信息、控制FR系统的相关功能。
添加客户端
点击添加按钮
会弹出如下的弹窗
其中客户端名称、客户端描述、备选认证 是我们可以手动输入的,其他会自动生成
可以先不选任何备选认证,在下面讲认证的时候我们会单独再介绍
编辑客户端
添加成功后,我们看到每一个客户端对应有3个基础的工具栏按钮 。点击编辑按钮可以看到跟添加界面类似的窗口
我们后面主要用到的其实是:客户端ID和密钥,这两个参数也是需要第三方系统管理员严格保密的,如果泄露了就会造成服务数据的泄露!
编辑可以改 客户端名称、描述、备选认证方式和重置密码
移除客户端
客户端移除有两种方式,单个移除和批量移除。
2.2.2 认证方式
为什么要有认证方式
我们对外提供服务的时候需要有相关的安全保障,所以需要认证方式,这里认证的方式我们做了一些默认的,也允许用户自己去进行扩展
默认的认证方式
当前有3种默认的认证方式
假设 $HOST = http://localhost:8075/webroot/decision
注:以下的所有认证使用的参数,均可以携带在请求 cookie/header/query任意一个中
①自签发token认证过程
这个认证是所有的客户端接口都天然支持的,不论你选不选备选认证,这种方式都支持。其认证过程为:
客户端使用客户端ID和密钥获取token
HTTP POST $HOST/sp/client/api/token
参数:client_id = 客户端ID secret= 密钥
利用access_token调用具体的服务,参数名 client_token
②ak sk认证
这种认证就是利用客户端ID和密钥直接作为认证依据,直接调用服务的方式。
出于安全考虑,这种方式并不推荐
③摘要认证
利用摘要算法(比如 MD5/ SHA256),对客户端ID和密钥以及时间戳进行签名,进行认证
在不能用token认证的情况下,比较推荐使用这种认证方式,相对安全一些
签名过程:
已知:client_id=203bc7b8db1d423fb55824150327ef98,secret=98ffd41b86db4868a6875f57e6974bbc, timestamp=1600166180321; 配置的 签名算法为MD5,超时时间为300秒
签名 = MD5(client_id+secret+timestamp)+timestamp = EE6E14BCEC5724C3BC6FC08AFC5C2B111600166180321
访问服务时携带两个参数 _sign_ = 签名; client_id = 客户端ID
添加/编辑/删除认证类型
其中:认证名称、描述 自己随便填,自己能识别即可。
clazz: 是我们需要实现的认证接口的实例对象(同一个类,可以通过配置的改变来变成多种认证方式)
config:是这个认证需要的一些固定配置(比如截图中,我们定义的摘要算法是MD5,有效期是300秒,我们也可以自己修改为SHA-256,7200秒这样的认证方式)
dftParams:这个当前是缺省的,不需要填任何内容。
2.2.3 服务API
创建/删除/编辑 分组
注:内置的分组是无法编辑和删除的
创建/删除/编辑/禁用/修改分组 API
选择一个分组后,点击右侧面板API的增加,就可以添加一个API了
其中API的名称和描述是自己根据业务需要定义的,只要自己能认出来即可,方便管理。
clazz指向的是我们实现的服务接口实例(接口会在开发文档部分进行介绍,一般我们使用默认的几个数据接口实例就可以满足我们的常规需求了)
API路径和方法,表示的是http请求中调用这个接口的 path和方法
config就是我们初始化这个服务需要的配置信息
同样的内置的API部分是不能编辑的,即便能编辑的在重启后也会还原
2.2.4 API权限分配
对于非公开API来说,调用都是需要做权限验证的,那么我们不同的场景不同的客户端可调用的接口范围肯定是不一样的,我们可以在这个页面内进行分配
注:目前不存在分组权限,也就是即便是把某个分组权限打开了,实质上也只是把当前分组下面的API的权限分配给了某个客户端,如果后续发生了API分组变更,或者该分组API新增,那么权限是不会发生变化的
3. 调用示例编辑
3.1 SQL数据服务
这个demo示例用来向我们展示,最简单的将SQL转换成数据服务向第三方提供使用的场景
我们需要用到的接口实例是:com.tptj.plugin.hg.client.center.api.data.GetBySql
包含两个配置项:
connection:SQL运行的数据源连接名称(比如FRDemo之类的)
sql:数据来源的SQL
这个接口主要用于一些基础的简单的数据服务的对外提供,完全不依赖于模板,只要会写SQL就可以了
比如如下的测试例子:
数据源连接 = FRDemo SQL = SELECT * FROM `销量` where 地区 = '${地区}'
这个查询中我们使用到了一个参数 地区
调用一下看看【两种传参的方式】
3.2 模板数据集数据服务
这个demo示例用来向我们展示,对于我们已经做好的模板内的数据集数据如何向第三方进行提供。
我们需要用到的接口实例是:com.tptj.plugin.hg.client.center.api.data.GetByTableData
包含两个配置项:
report:数据集的来源(相对于reportlets)
dsName:数据集的名称
这个接口主要用于一些模板里面已经做好了的数据集第三方需要使用对应数据的,或者数据的来源不是SQL的数据集数据,或者其他不适合直接向第三方开发源数据连接的数据服务。
比如如下的测试例子:
模板路径 = GettingStarter.cpt 数据集名称 = ds1
这个查询中我们使用到了一个参数 地区
调用一下看看【两种传参的方式】
3.3 填报接口调用
填报接口这个demo主要用于展示,当我们希望向第三方提供 数据录入/审批 这类业务服务的时候我们如何借助模板来简单的实现。
首先它需要用到我们开发好的接口实例:com.tptj.plugin.hg.client.center.api.data.WriteReport
配置上支持两个配置项
report : 某个填报模板的路径(相对于reportlets目录)
sheet:【可选】需要执行的具体某个sheet名称对应sheet的模板填报属性内的填报业务。【如果不填这个参数,就会执行所有sheet的模板填报属性内的填报业务】。
注:该填报不会触发JS相关事件!
注:这里我们用到了body这个参数,这个参数可以直接通过URL传,也可以通过请求的body传(仅限通过调用接口服务的情况下)
如果http请求的body是一个json,那么在计算的报表内有两种引用
1.直接通过 $body 或者${body} 这个参数名获取到整个json字符串
2.如果如果是{ key1:xxxx,key2:ffffff,...,keyN:fsss }这种结构的body,还可以直接通过$key1,$key2,....$keyN在报表中使用这些参数
3.4 简单报表行列式数据服务
这个demo示例用来向我们展示,对于一些无法用单个数据集简单取出的数据,可以通过制作成简单的报表的形式输出数据服务。
我们需要用到的接口实例是:com.tptj.plugin.hg.client.center.api.data.GetListByReport
包含两个配置项:
report:数据来源的报表路径(相对于reportlets)
tag:数据来源的sheet名
这个接口主要用于一些模板里面已经做好了的数据集第三方需要使用对应数据的,或者数据的来源不是SQL的数据集数据,或者其他不适合直接向第三方开发源数据连接的数据服务。
比如如下的测试例子:
模板路径 = WorkBook12.cpt sheet名 =sheet1
这个查询中我们使用到了一个参数 地区
通过两个数据集关联实现
我们定义的demo接口配置详情如下
实际测试效果如下【两种传参方式】
特别说明:这并不是一个真正通用的接口实现,如果要使用这个接口实例,制作的模板必须满足以下的限制
只支持纯数据表格
目前简单的把一个sheet分成了以下几种情况
数据行:从上往下,逐行从左往右查看,找到的第一个有 “向下扩展”单元格的且该单元格所在行未隐藏的行作为数据的起始行。往下所有的内容都被简单认为是要输出的数据区域(所以限制了我们一个sheet内只能有一个数据区域)
标题行:数据行之前的所有行中,如果该行只有一个格子有值,且该行未隐藏,则该行被作为标题行。可以有多个标题行,输出顺序按行序号排序(明细数据中不输出标题)
列表头行:数据行之前的所有行中,如果该行有超过一个格子有值,且该行未隐藏,则该行被作为列表头行。可以有多层列表头,但是目前每列的列表头只取最接近数据行的列表头单元格的值作为该列的列表头。
空行:所有行高等于0,或者一整行都没有数据的行。空行不会输出
空列:列宽等于0,或者该列的列表头的值是空的。空列不会输出
合并行的数据会按最合并小行粒度输出。
注:不要使用复杂或大数据量模板
3.5 简单报表分组式数据服务
这个demo示例用来向我们展示,对于一些无法用单个数据集简单取出的数据,可以通过制作成简单的报表的形式输出数据服务。
我们需要用到的接口实例是:com.tptj.plugin.hg.client.center.api.data.SheetGroupDataByReport
包含两个配置项:
report:数据来源的报表路径(相对于reportlets)
tag:数据来源的sheet名
比如如下的测试例子:
模板路径 = WorkBook12.cpt sheet名 =sheet1
这个查询中我们使用到了一个参数 地区
通过两个数据集关联实现
我们定义的demo接口配置详情如下
实际测试效果如下【两种传参方式】
特别说明:这并不是一个真正通用的接口实现,如果要使用这个接口实例,制作的模板必须满足一定的限制,限制跟简单报表行列式数据服务相同
注:不要使用复杂或大数据量模板