1. 概述编辑
1.1 版本
| 报表服务器版本 | 开放平台BETA 插件版本 |
|---|---|
| 10.0.19 | V1.3 |
| 11.0 | V1.3 |
1.2 应用场景
客户希望在自身的第三方业务系统中，通过访问应用，调用API的方式，实现帆软决策系统的管理效果，以及自定义的数据服务功能
1）IT部门，基于开放平台，实现企业内各系统的互联互通。
2）软件公司，通过集成方式，实现其行业产品的帆软相关功能。
3）终端企业，基于接口服务，实现客制化需求。
1.3 功能简介
帆软提供「开放平台BETA」插件：
1）提供安全、灵活、规范、有效的web服务，方便开发人员快速构建应用，实现在自身的业务系统中，对帆软系统、报表进行相应的管理、开展数据服务。
2）提供统一的平台配置，实现客户端API的权限管理、安全认证管理。
3）提供日志管理功能，实现对于API、应用的请求、访问状态查看。
1.4 公共接口
1）官方接口
对于开放平台中内置的接口，帆软提供相关 API 文档，方便用户进行理解和使用。
该 API 文档，仅作为官方示例，提供给具备自主产品集成能力的用户使用。技术支持不负责接口示例的维护和使用问题解答。
注：平台接口文档为开放平台文档；FineReport、FineBI接口文档为同系列其他接口插件文档，需下载安装相应插件后，方可正常使用
| 分类 | API文档 |
|---|---|
| 平台 | 平台接口文档 |
| FineReport | FineReport接口文档 |
| FineBI | FineBI接口文档 |
2）定制接口
若内置的认证方式或API不足以满足业务需求，希望能够添加自定义开发认证方式或API。
帆软提供自定义开发示例，仅做参考。用户可参考相关逻辑自行开发，详情请参见：开放平台子插件示例 。
注：如需官方开发人员做相关定制开发，请联系销售经理进一步咨询。
2. 插件简介编辑
2.1 插件安装
FineReport11.0默认安装了「开放平台BETA」插件。FineReport10.0需自行安装该插件。
点击下载插件：开放平台BETA插件
设计器插件安装方法参照：设计器插件管理
服务器安装插件方法参照：服务器插件管理
注：在升级插件时，如果有使用同系列插件，需要在升级开放平台插件前，禁用同系列插件，或者升级后重启服务器！
同系列插件列表：开放平台-FineBI接口、开放平台-FR报表接口、开放平台-平台登录认证接口。
2.2 界面简介
插件安装成功后，管理员登录数据决策系统，点击「管理系统>开放平台」，即可进入功能界面，如下图所示：
3. 功能简介编辑
3.1 API管理
在「API管理」中，包含第三方系统与Finereport进行资料互动服务的所有配置。
1）分组管理
「API管理」界面左侧为分组。平台已内置多个分组，用户可根据需需求，自行增删分组。
对于内置的分组，使用者不可删除和编辑。
对于非内置的分组，使用者可进行编辑、删除等操作。被删除的分组内的API，会自动移动到默认分组中。
2）API管理
每个分组内存放着多个API。平台已内置部分常用的API，使用者也可自行新增API。
对于内置的API，使用者仅可进行编辑、复制、更换分组操作，不可删除和禁用。
对于非内置的API，使用者可进行编辑、复制、更换分组、删除和禁用等操作。
3.2 应用管理
1）新增应用
在「应用管理」中，使用者可以通过添加事件的方式，新建应用。
使用者点击「应用管理」，点击「增加」，设置相关内容，点击「确定」，即可新增应用。
自动生成的「应用ID」和「密钥」，可用于API的鉴权，作为第三方系统的访问凭证。
| 设置项 | 说明 |
|---|---|
| 应用ID | 自动生成，不可手动设置 |
| 应用名称 | 应用的名称，必填 |
| 应用描述 | 应用的描述，选填 |
| 密钥 | 自动生成，不可手动设置 |
| 备选认证 | 认证方式中预先设置好的几种方式，选填 |
2）应用管理
对于添加的应用，支持新增、编辑、复制、禁用、单个删除、批量删除等操作。编辑时可重置密钥。
3.3 认证方式
3.3.1 内置的认证方式
| 认证方式 | 说明 |
|---|---|
| 国密SM2签名认证 | 利用国密SM2椭圆算法进行加解密，使用标准椭圆参数 签名_sign_=sm2(clientId+secret+timestamp) 配置项priKey=密钥 timeout=超时时间（秒） |
| 摘要签名认证 | 1）应用场景： 在不能使用token认证的情况下，使用摘要演算法（比如 SM3/MD5/ SHA256），对应用ID、密钥以及时间戳进行签名后，通过签名和应用ID进行认证。 推荐使用这种认证方式，安全性更高 2）功能简介： 签名= 摘要算法(应用ID+密钥+时间戳)+时间戳 示例背景：
示例签名 = MD5(client_id+secret+timestamp)+timestamp = EE6E14BCEC5724C3BC6FC08AFC5C2B111600166180321 |
| AkSk直接认证 | 使用用应用ID和密钥直接作为认证依据，直接呼叫服务。 出于安全考虑，不推荐使用这种认证方式。 在认证方式的编辑界面的配置信息中，不可编辑。 在请求头中添加 client_id={应用ID} secret={密钥} 即可直接访问应用 |
3.3.2 自定义认证方式
编辑、禁用、单个删除、批量删除等操作。
在「认证方式」页面，点击「增加」按钮，设置相关配置项，点击「确定」，即可新增认证方式。如下图所示：
| 配置项 | 说明 |
|---|---|
| 基础 | 支持自定义「认证名称」、「认证描述」和「接口类」，方便使用者区分设置的认证方式 1）「认证名称」必填，不可为空 2）「认证描述」选填 3）「接口类」是需要实现的认证API的例项物件。同一个类，可以通过配置的改变，实现多种认证方式。 |
| 配置 | 在认证方式的编辑界面的配置信息中，需进行一些固定配置，例如摘要签名认证需要定义「摘要算法」和「有效期」； 配置可以设置为加密项，这样加密后的信息在保存后，也无法从前端读取 |
| 默认参数 | 自定义参数设置 |
3.4 权限管理
针对非公开API，调用均需要做权限验证。不同的场景、不同的应用，可调用的接口范围是不一样的。管理员可以权限管理下，进行权限配置。
公开API可以随意调用，不受权限验证的约束。
注：目前不存在分组权限，意思是即使把某个分组权限打开了，实质上也只是把当前分组下面的API的权限分配给了某个应用。
如果后续发生了API分组变更，或者该分组下API新增，那么之前已设置好的API权限是不变的。
例如：针对一个应用，打开目录树管理的分组权限，相当于打开下属所有API的权限。如果该分组下的API更换到其他分组，则该API仍保持权限打开的状态；如果在目录树管理的分组下，新增API，则该API为权限关闭状态
3.5 日志管理
在日志管理中，管理员可以查看API的请求频率和详细记录。
4. 调用示例编辑
上述配置完成后，就可以调用相应的API接口，实现相应的功能。本章将提供多种调用示例Demo，帮助大家理解开放平台的使用。
注：本章的示例，均调用的是基础数据接口下的内置服务，在决策系统重启后，服务的配置数据均会重置为默认数据；建议使用者在实际使用中，将内置服务复制，可以避免上述问题
4.1 SQL数据服务
本Demo示例展示：如何将SQL转换成数据服务向第三方提供使用的场景。
需用到的API接口实例是：[demo]Sql数据服务
具体步骤：
1、在API管理的基础数据接口中，点击[demo]Sql数据服务的编辑按钮，如图所示
具体步骤：
1、在API管理的基础数据接口中，点击[demo]Sql数据服务的编辑按钮，如图所示
2、（1）在基础页面，信息已默认写好，无需任何操作，此处只需记下API路径和API方法两个参数，用于后续步骤中，API调用时的链接填写
（2）在配置页面，有2个配置项，分别为：
connection：SQL运行的数据源连接名称（比如FRDemo之类的）；sql：数据来源的SQL
在这个示例中，我们的配置为：
connection = FRDemo；sql = SELECT * FROM `销量` where 地区 = '华东'
3、新建应用见3.2节，此处已完成名称为“测试”的应用新建。记下应用ID和密钥两个参数，用于后续步骤中，API调用时的鉴权
4、在权限管理中，选定应用为“测试”，开启基础数据接口分组中，[demo]Sql数据服务的权限。以保证该API可用
测试效果：
链接为：http://localhost:8075/webroot/decision/sp/client/api/sql/data。
其中http://localhost:8075/webroot/decision/sp/client/api/为固定链接部分，sql/data2和GET分别为API路径和API方法；
将应用ID和密钥写入Headers中，最后调用API，得出的结果如图所示
4.2 报表数据集服务
本Demo示例展示：如何将已经做好的模板内的数据集数据，向第三方进行提供。
需用到的接口实例是：[demo]报表数据集服务
具体步骤：
参考4.1节的配置内容
1、在API管理的基础数据接口中，点击[demo]报表数据集服务的编辑按钮，进行API信息的配置
2、（1）在基础页面，信息已默认写好，无需任何操作，此处只需记下API路径和API方法两个参数，用于后续步骤中，API调用时的链接填写
（2）在配置页面，有2个配置项，分别为：
report：数据集的来源（相对于reportlets）；dsName：数据集的名称
在这个示例中，我们的配置为：
report= GettingStarter.cpt ；dsName = ds1
3、在应用管理中，记下“测试”应用的应用ID和密钥两个参数，用于后续步骤中，API调用时的鉴权
4、在权限管理中，选定应用为“测试”，开启基础数据接口分组中，[demo]报表数据集服务。以保证该API可用
测试效果：
链接为：http://localhost:8075/webroot/decision/sp/client/api/ds/data。
ds/data和GET分别为API路径和API方法；将应用ID和密钥写入Headers中。
两种传参方式，一种是在Body中写入地区信息：{“地区”：“华北”}
另一种是在Params中，将地区和华北，分别写入KEY和VALUE下。此时在链接后缀，增加了参数值？地区=华北
两种方式得出的结果一致，如图所示
4.3 报表数据服务
本Demo示例展示：对于一些无法通过单个数据集简单取出的数据，可以通过制作成简单的报表的形式，输出数据服务。
需用到的接口实例是：[demo]报表数据服务
具体步骤：
1、在API管理的基础数据接口中，点击[demo]报表数据服务的编辑按钮，进行API信息的配置
2、（1）在基础页面，信息已默认写好，无需任何操作，此处只需记下API路径和API方法两个参数，用于后续步骤中，API调用时的链接填写
（2）在配置页面，有2个配置项，分别为：
report：数据来源的报表路径（相对于reportlets）；tag：数据来源的sheet名
在这个示例中，我们的配置为：
report =开放平台测试.cpt；tag =sheet1
模板下载：
注：（1）本模板的数据来自FRdemo数据库中，您可以下载后，直接使用；
（2）本接口不适用于复杂或大数据量模板
3、在应用管理中，记下“测试”应用的应用ID和密钥两个参数，用于后续步骤中，API调用时的鉴权
4、在权限管理中，选定应用为“测试”，开启基础数据接口分组中，[demo]报表数据服务。以保证该API可用
测试效果：
链接为：http://localhost:8075/webroot/decision/sp/client/list/report/data。
list/report/data和GET分别为API路径和API方法；将应用ID和密钥写入Headers中。
4.4 报表分组数据服务
本Demo示例展示：对于一些无法用单个数据集简单取出的数据，可以通过制作成简单的报表的形式，输出数据服务。
需用到的接口实例是：[demo]报表分组数据服务
具体步骤：
1、在API管理的基础数据接口中，点击[demo]报表分组数据服务的编辑按钮，进行API信息的配置
2、（1）在基础页面，信息已默认写好，无需任何操作，此处只需记下API路径和API方法两个参数，用于后续步骤中，API调用时的链接填写
（2）在配置页面，有2个配置项，分别为：
report：数据来源的报表路径（相对于reportlets）；tag：数据来源的sheet名
在这个示例中，我们的配置为：
report = 开放平台测试.cpt；tag =sheet1
3、在应用管理中，记下“测试”应用的应用ID和密钥两个参数，用于后续步骤中，API调用时的鉴权
4、在权限管理中，选定应用为“测试”，开启基础数据接口分组中，[demo]报表分组数据服务。以保证该API可用
测试效果：
链接为：http://localhost:8075/webroot/decision/sp/client/group/report/data。
group/report/data和GET分别为API路径和API方法；将应用ID和密钥写入Headers中。
从测试效果图可以看出，本接口与报表数据服务接口，输出的数据内容一致，只是在格式上有所不同。本接口输出的数据将报表内容，分为了“title”和“items”两部分。使用者可根据自身需求，选用不同的接口
注：与报表数据服务相同，本接口不适用于复杂或大数据量模板