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. 跨域登录接口
作用：使用该接口可以登录数据决策系统。
URL：/login/cross/domain?fine_username=name&fine_password=password&validity=-1&callback=myfunction
请求方式：GET
注：接口参数请参考：前台单点登录接口 。
6. 获取完整目录树
作用：获取平台主页目录面板
URL：/v10/view/entry/tree
请求方式：GET
注：该接口需要携带 fine_auth_token 进行认证。
返回值示例：
| 返回值 | 说明 | 示例 |
|---|---|---|
| id | 目录ID | 0e792bba-ef9b-4d78-a4ff-a2c8b5b2c483 |
| pId | 父节点ID | 6ada650f-50ea-437c-a748-06982f2e1e0e |
| text | 目录名称 | 销售额市场分析 |
| path | 目录对应的模板路径 | demo/analytics/marketing/销售额市场分析.frm |
| description | 节点描述 | - |
| deviceType | 展示终端 1：PC 2：平板 4：手机 同时包含多场景相加即可 例如7，表示三种都支持 | 3 |
| entryType | 挂载类型 | 102 |
| mobileNodeIcon | 图标的attach_id | null |
| sortIndex | 排序序号 | 2 |
| isParent | 是否目录节点 | false |
| open | 是否展开 | false |
| privilegeDetailBeanList | 权限明细 | null |
| cover | 封面ID，可选 | null |
| icon | 节点图标 | null |
| fullParentName | 父节点名称 | null |
| parentNames | 父节点完整路径 | [ "管理驾驶舱", "角色多维度", "市场主管" ] |
| parentDeviceType | 父节点展示终端 0：无 1：PC 2：平板 4：手机 同时包含多场景相加即可 例如7，表示三种都支持 | 3 |
| showType | 模板预览类型 0：填报 1：分页 2：预览 3：表单 | 3 |
| parameters | - | [] |
7. 页面集成接口
很多用户为了统一门户，往往会把数据决策系统的后台管理页面集成到自己的系统中，本章提供 FineReport 支持的页面集成接口。
1）接口
支持单独页面集成的管理菜单范围如下表所示：
每个接口调用方法为访问：http://ip:端口/工程名/decision/接口调用
| 管理菜单 | 接口调用 | 备注 |
|---|---|---|
| 目录管理 | /directory | - |
| 用户管理 | /user | - |
| 权限管理 | /privilege | - |
| 定时调度 | /timer | 无全局设置 |
2）示例
管理员登录数据决策系统，访问链接：http://localhost:8075/webroot/decision/directory，即可访问目录管理，如下图所示：
注：非管理员身份访问链接，若无目录权限，会出现访问失败的情况，请参考：Web页面集成常见问题 解决。
上一篇：Web页面集成
