Web页面集成常见问题

1.1 版本

1.2 功能简介

FineBI支持通过 GET 和 POST 两种方式调用接口数据，进行Web集成。

本文为你介绍 API 接口相关入门知识，便于后续使用FineBI进行Web集成。

API接口文档一般分为接口描述、接口地址、请求方法、请求参数、响应内容、错误代码、实例几个部分：

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。

示例：

除了登录的接口之外，FineBI所有的WEB API接口，都需要登录才能使用。

1）正式使用：建议配置单点登录，否则嵌入式集成后，需要反复登录。详情请参见：单点登录

2）测试阶段：先登录FineBI，然后获取token参数，并在调试其他接口时，带上token参数。

本章将讲解两种获取和使用token参数的方法，任选其一即可。

4.1 fine_auth_token

1）用户登录FineBI系统。

2）F12，在「Network>Headers」下，获取fine_auth_token的值。如下图所示：

3）放在请求的queryString中，以?fine_auth_token=token的参数形式拼接到url上

4.2 Authorization

1）用户登录FineBI系统。

2）F12，在「Network>Headers」下，获取Authorization中token的值。如下图所示：

3）放在请求的 header 中，以 key="Authorization"，value="Bearer " + token的形式存放。

注意Bearer后面的空格，建议直接复制上文黄色高亮区域。

有些接口的参数值，需要通过其他接口获取。但是在调试时，有时需要单个测试接口，此时如何获取这些ID值呢？

5.1 分组ID

分组ID，groupId，存储在finedb的fine_conf_entity表中，字段以GroupConfig.groupHolder开头。

5.2 业务包ID

业务包ID，packageId，存储在finedb的fine_conf_entity表中，字段以DirectPackageConfStore.mapHolder开头

5.3 表ID

表ID，tableId，存储在finedb的fine_conf_entity表中，字段以DirectEntryConfStore.mapHolder开头。

6.1 跨域登录接口

作用：使用该接口可以登录 BI 系统。

URL：/login/cross/domain?fine_username=name&fine_password=password&validity=-1&callback=myfunction

请求方式：GET

6.2 导出之前自定义

作用：从 BI 的组件导出或者全局导出导出excel时，在导出操作之前，加入一些自定义操作，可以用这个接口实现。比如导出的文件进行自定义加密；

接口：ExportHandleProvider

package com.finebi.stable.fun;
 
import com.fr.stable.fun.mark.Mutable;
 
import java.io.OutputStream;
 
/**
 * Created by Hiram on 2018/11/14.
 */
public interface ExportHandleProvider extends Mutable {
    String XML_TAG = "ExportHandleProvider";
 
    int CURRENT_LEVEL = 1;
 
    /**
     *
     * @param originalOutputStream  原始导出流
     * @param type  导出类型
     * @return 处理后的流
     */
    OutputStream handleStream(OutputStream originalOutputStream, ExportType type);
}

示例源码：

下面的示例源码简单的统计一下导出文件的大小，输出在日志里面。写一个拦截处理的CountExportHandle，返回一个CountOutputStream，在write时计数，最后在close的时候输出大小。

CountExportHandle：

import com.finebi.stable.fun.ExportType;
import com.finebi.stable.fun.impl.AbstractExportHandleProvider;
import java.io.OutputStream;
public class CountExportHandle extends AbstractExportHandleProvider {
    @Override
    public OutputStream handleStream(OutputStream originalOutputStream, ExportType type) {
        return new CountOutputStream(originalOutputStream);
    }
 
}

CountOutputStream：

import com.fr.log.FineLoggerFactory;
import java.io.IOException;
import java.io.OutputStream;
 
 
public class CountOutputStream extends OutputStream {
 
    private OutputStream out;
 
    private int count;
 
    public CountOutputStream(OutputStream out) {
        this.out = out;
    }
 
    @Override
    public void write(int b) throws IOException {
        count++;
        out.write(b);
    }
 
    @Override
    public void write(byte[] b) throws IOException {
        count += b.length;
        out.write(b);
    }
 
    @Override
    public void write(byte[] b, int off, int len) throws IOException {
        count += len;
        out.write(b, off, len);
    }
 
    @Override
    public void flush() throws IOException {
        out.flush();
    }
 
    @Override
    public void close() throws IOException {
        FineLoggerFactory.getLogger().info("===== export length: {}  ======", count);
        out.close();
    }
}

注：该接口使用需要二次开发。

6.3 页面集成接口

很多用户为了统一门户，往往会把 FineBI 的后台管理页面集成到自己的系统中，本章提供 FineBI 支持的页面集成接口。

1）接口

支持单独页面集成的管理菜单范围如下表所示：

每个接口调用方法为访问：http://ip:端口/工程名/decision/接口调用

2）示例

管理员登录数据决策系统，访问链接：http://localhost:37799/webroot/decision/directory，即可访问目录管理，如下图所示：

7.1 没有页面访问权限

问题描述：

用户以非管理员身份进入数据决策系统后，访问：http://IP:Port/webroot/decision/接口调用 ，出现如下报错：

解决方案：

需要获得该页面的权限，请参考 分级权限分配

7.2 拒绝了我们的连接请求

问题描述：

FineBI 通过 iframe 页面嵌入到其他页面中报错：xxx拒绝了我们的连接请求，如下图所示：

原因分析：

由于平台安全限制，FineBI 在集成时需要将「管理系统>安全管理>安全防护」中的 Security Headers 关闭才可跨域。 

解决方案：

管理员登录数据决策系统，点击「管理系统>安全管理>安全防护」，关闭「Security Headers」设置，如下图所示：

7.3 服务器不支持 JSON 下的 URL

因为 FineBI 中 URL 传递 JSON 对像，若有些服务器不支持 JSON 的 URL ，就需要把 JSON 类型的 URL 参数值先进行编码encodeURIComponent()。

编码前：dir={"name":"新建仪表板12","catalog":[]}

编码：encodeURIComponent(JSON.stringify({"name":"新建仪表板12","catalog":[]}))

编码结果：dir=%7B%22name%22%3A%22%E6%96%B0%E5%BB%BA%E4%BB%AA%E8%A1%A8%E6%9D%BF12%22%2C%22catalog%22%3A%5B%5D%7D

7.4 返回错误码

在进行系统集成时，如果后台有错误，会返回错误码（errorCode），具体异常码定义可以参考 系统错误码说明