1. 概述编辑
1.1 版本
报表服务器版本 | 功能变更 |
---|---|
11.0 | - |
1.2 功能简介
FineReport 支持通过 GET 和 POST 两种方式调用接口数据,进行Web集成。
本文为你介绍 API 接口相关入门知识,便于后续使用 FineReport 进行Web集成。
2. 如何看接口文档编辑
API接口文档一般分为接口描述、接口地址、请求方法、请求参数、响应内容、错误代码、实例几个部分:
内容 | 说明 |
---|---|
接口简介 | 简单描述接口的逻辑和作用。例如说明这是一个发送消息的接口、查询天气的接口 |
接口URL | 这个url地址表示的是网络地址,我们需要调用接口url,获取响应内容 |
请求方法 | 常见的请求方法为 GET 和 POST,其他的方式见下图。 注:FineReport 支持GET和POST两种请求方式。 |
请求参数 | 用来传递信息的变量。 即需要请求的字段名的名称和规则:都是哪些字段,字段的类型是什么,是否必填字段等
|
响应内容 | 接口返回的字段名称和规则 |
错误代码 | 对接口的错误用代码进行归类,以便能快速找到错误原因,解决问题 |
实例 | 实际调用时的响应的内容 |
3. 请求参数编辑
3.1 GET请求
GET通常用于获取服务端数据:
GET方式在url后面拼接参数,只能以文本的形式传递参数;
传递的数据量小,4kb左右(不同浏览器会有差异);
安全性低,会将信息显示在地址栏;
速度快,通常用于对安全性要求不高的请求;
GET请求也可以有Headers参数
GET请求可以传递参数,一般的传递方式为 URL传参。
在GET请求中,遇到参数 / Params / Querys 均是以 URL传参的形式进行传递。
在POSTMAN中,可以直接用 URL传参形式,也可以在Params处填写KEY和VALUE,会自动进行拼接(演示)。
3.2 POST请求
post提交数据相对于get的安全性高一些。
传递数据量大,请求对数据长度没有要求;
用于密码等安全性要求高的场合,提交数据量较大的场合,如上传文件,发布文章等。
POST请求一般由Url 、 Headers 、 Body组成,如果在POST请求的接口文档里遇到 Params / Querys 则需以像GET请求一样使用URL参数传递参数,而POST请求的接口文档里面的参数一般指Body。
示例:
类型 | 说明 |
---|---|
application/json,JSON数据格式,一般使用raw-JSON | 最常见的格式,例如 {"name":"Roxy","password":"123"} 此时的请求头为: |
text/plain,纯文本格式,一般使用raw-Text | 例如:name:ziv,password:123 |
text/xml(了解),XML数据格式,一般使用raw-XML | 例如: <?xml version="1.0" encoding="UTF-8" ?> <name>ziv</name><password>123</password> |
multipart/form-data | 它会将表单的数据处理为一条消息,以标签为单元,用分隔符分开。由于有boundary隔离,所以multipart/form-data既可以上传文件,也可以上传键值对,它采用了键值对的方式,所以可以上传多个文件 |
application/x-www-from-urlencoded | 会将表单内的数据转换为键值对,&分隔。 |
4. 认证方式编辑
除了登录的接口之外,FineReport 所有的WEB API接口,都需要登录才能使用。
1)正式使用:建议配置单点登录,否则嵌入式集成后,需要反复登录。详情请参见:单点登录
2)测试阶段:先登录 FineReport,然后获取token参数,并在调试其他接口时,带上token参数。
本章将讲解两种获取和使用token参数的方法,任选其一即可。
4.1 fine_auth_token
1)用户登录数据决策系统。
2)F12,在「Network>Headers」下,获取fine_auth_token的值。如下图所示:
3)放在请求的queryString中,以?fine_auth_token=token的参数形式拼接到url上。
4.2 Authorization
1)用户登录 FineReport 系统。
2)F12,在「Network>Headers」下,获取Authorization中token的值。如下图所示:
3)放在请求的 header 中,以 key="Authorization",value="Bearer " + token的形式存放。
注意Bearer后面的空格,建议直接复制上文黄色高亮区域。
5. 其他接口编辑
5.1 跨域登录接口
作用:使用该接口可以登录数据决策系统。
URL:/login/cross/domain?fine_username=name&fine_password=password&validity=-1&callback=myfunction
请求方式:GET
5.2 获取完整目录树
作用:获取平台主页目录面板
URL:/v10/view/entry/tree
请求方式:GET
注:该接口需要携带 fine_auth_token 进行认证。
5.3 页面集成接口
很多用户为了统一门户,往往会把数据决策系统的后台管理页面集成到自己的系统中,本章提供 FineReport 支持的页面集成接口。
1)接口
支持单独页面集成的管理菜单范围如下表所示:
每个接口调用方法为访问:http://ip:端口/工程名/decision/接口调用
管理菜单 | 接口调用 | 备注 |
---|---|---|
目录管理 | /directory | - |
用户管理 | /user | - |
权限管理 | /privilege | - |
定时调度 | /timer | 无全局设置 |
2)示例
管理员登录数据决策系统,访问链接:http://localhost:8075/webroot/decision/directory,即可访问目录管理,如下图所示:
6. 常见问题编辑
6.1 没有页面访问权限
问题描述:
用户以非管理员身份进入数据决策系统后,访问:http://IP:Port/webroot/decision/接口调用 ,出现如下报错:
解决方案:
需要获得该页面的权限,请参考 分级权限分配
6.2 隐藏报表内置工具栏
问题描述:
在 Web 页面集成时,将报表嵌入到用户页面,会自动显示 FineReport 内置工具栏。
有时用户自定义了用户栏,如何隐藏 FineReport 内置工具栏呢?
解决方案 1:取消勾选「使用工具栏」。
使用设计器打开模板,在菜单栏上点击「模板>模板Web属性」,可对分页预览、填报预览、三种预览方式的工具栏进行设置。
以分页预览设置为例,选择「为该模板单独设置」,取消勾选「使用工具栏」即可隐藏报表内置工具栏,如下图所示:
解决方案 2:使用 URL 控制。
在预览模板的页面,URL 后面加上 &__showtoolbar__=false ,即可隐藏内置工具栏。
6.3 iframe集成模板报错
6.3.1 X-Frame-Options相关报错
问题描述:
通过 iframe 内嵌报表链接到应用内报错,报错信息如下所示:
通过 iframe 页面内嵌报表链接到其他应用内,页面报错:xxx拒绝了我们的连接请求
按 F12 键,或者单击鼠标右键点击检查,打开 Chrome 的控制台,报错信息为:Refused to display 'http://localhost:8080/webroot/decision/view/report?XXXXXXX' in a frame because it set 'X-Frame-Options' to 'sameorigin'
如下图所示:
原因分析:
X-Frame-Options 响应头是用来给浏览器指示是否允许一个页面在 <frame>, <iframe>, <embed> 或者 <object> 中展现的标记。站点可以通过确保网站没有被嵌入到别人的站点里面,从而避免 clickjacking 攻击。
X-Frame-Options 有三个可能的值:
deny:表示该页面不允许在 frame 中展示,即便是在相同域名的页面中嵌套也不允许。
sameorigin:表示该页面可以在相同域名页面的 frame 中展示。
allow-from uri:表示该页面可以在指定来源的 frame 中展示。
以上报错是因为X-Frame-Options 响应头的值为 sameorigin,而嵌入的地址并非相同域名,导致无法正常展现。
解决方案:
管理员进入平台,点击「管理系统>安全管理」,关闭点击挟持攻击防护按钮。如下图所示:
注:若方案不生效,那说明可能在Apache、nginx、IIS、HAProxy、Express中设置了 HTTP 头 X-Frame-Options,需要检查相关配置文件。
6.3.2 This request has been blocked; the content must be served over HTTPS
问题描述:
HTTPS 页面嵌入 HTTP 地址报错:This request has been blocked; the content must be served over HTTPS
原因分析:
HTTPS 是 HTTP over Secure Socket Layer,以安全为目标的 HTTP 通道,所以在 HTTPS 承载的页面上不允许出现 HTTP 请求,因此需要将加载的 HTTP 请求替换成 HTTPS 请求,才能正常显示。
解决方案:
方法一:
将 HTTP 页面配置 SSL 证书实现 https 访问,参考文档:配置SSL证书实现HTTPS访问,Nginx,Apache,IIS 都能做,但不是很方便,如果没有现成可用的 HTTPS 地址可用,建议使用方法二。
方法二:
注:只适用静态资源的加载,比如加载某一个静态图片。如果是决策平台或者报表嵌入到 HTTPS 的页面,这两个加载的时候,都不是一个静态资源的请求,嵌入到 HTTPS 页面的话,需要用方法一。
upgrade-insecure-requests CSP 指令的作用就是让浏览器自动升级请求,防止访问者访问不安全的内容。
在 iframe 所在页面(一般是 html、jsp)的head中加入 meta 头即可:
<meta http-equiv="Content-Security-Policy" content="upgrade-insecure-requests" />
例如在 jsp 页面的 head 部分增加 meta 头:
6.3.3 Uncaught DOMException: Blocked a frame with origin "xxx" from accessing a cross-origin frame
问题描述:
iframe 跨域访问报错:Uncaught DOMException: Blocked a frame with origin "xxx" from accessing a cross-origin frame
原因分析:
iframe 跨域访问时,如果访问了被嵌入的界面中的 dom 信息,则会出现该报错。
解决方案:
需要根据实际场景来寻找最合适的跨域解决办法,常用的是 postMessage(),可参考:跨域调用 JS
6.4 调用finereport.js报错
问题描述:
在将报表集成到您自己的页面中时,调用 finereport.js 内置方法时如调用 FR.doURLPDFPring() 方法,JS 会出现:$.support.boxModel 为空或不是对象的错误,如下图所示:
原因分析:
jQuery 版本冲突导致的,您使用的 jQuery 版本和 finereport.js 中使用的版本不同,我们内置的 jQuery 版本是 1.12.4 。
注:finereport.js 更多介绍请参见:FineReport内置方法
获取 jQuery 版本方法:
按 F12 键,或者单击鼠标右键点击检查,打开 Chrome 的控制台,使用命令jQuery.fn.jquery获取jquery版本,如下图所示:
解决方案:
将页面中调用的 finereport.js
<script type="text/javascript" src="/webroot/decision/view/report?op=emb&resource=finereport.js"></script>
的代码放置在调用您用 jQuery 写的代码之前即可解决。
6.5 返回错误码
在进行系统集成时,如果后台有错误,会返回错误码(errorCode),具体异常码定义可以参考 系统错误码说明 。