阿里云Quick BI智能商业分析对接配置完全指南：从数据源接入到嵌入式集成

apphuang2026年07月07日 15:15:187

1. Quick BI产品概述与对接场景

阿里云智能商业分析Quick BI是一款全场景数据消费式的BI平台，通过智能化的数据分析与可视化能力，帮助企业快速搭建数据门户、仪表板、电子表格等数据产品。Quick BI依托阿里巴巴集团在电商、物流、金融等多个领域的实战经验，以简单易用的可视化操作和灵活高效的多维分析能力，让精细化数据洞察为商业决策保驾护航。

在实际业务中，Quick BI的对接使用主要涵盖三个核心场景：数据源的接入与配置、报表与分析页面的嵌入式集成、以及通过OpenAPI实现自动化管理与数据交互。对于已经拥有业务系统的企业而言，将Quick BI的报表能力无缝嵌入到自有系统中，是实现数据驱动决策的关键步骤。

需要先登录阿里云控制台，点击：阿里云控制台

2. 数据源配置：打通Quick BI与业务数据

2.1 数据源创建入口

Quick BI提供了多种进入数据源创建界面的方式，用户可以根据操作习惯灵活选择。第一种方式是在空间外通过资源入口快速创建，适合初次配置数据源时使用；第二种方式是从空间内的数据源模块进入，这是最常用的路径；第三种方式是在空间内的资源列表上快速创建，适合在已有工作空间中快速添加数据源。无论通过哪种入口，新建数据源后都会跳转到连接配置界面，用户可以选择对应的数据源类型进行配置。

2.2 网络连通方案

数据源与Quick BI之间的网络连通是配置成功的前提。Quick BI支持公网和内网两种连接方式。通过公网连接时，需要将Quick BI的IP地址添加到数据库的白名单中，确保网络畅通。用户可以在数据源配置界面单击复制白名单获取Quick BI的公网IP列表。每个数据源连接页面的下方均展示了完整的白名单列表，点击复制白名单即可完整复制。通过内网连接时，如果数据库部署在阿里云的ECS上，可以通过阿里云VPC进行连接。此外，也可以搭建跳板机通过SSH隧道访问并登录数据库。对于VPC数据源，还需要配置购买者的AccessKey ID和AccessKey Secret，以及ECS实例ID和所在区域。

2.3 主流数据源配置示例

以自建MySQL数据源为例，Quick BI支持MySQL 5.5、5.6、5.7、8.0版本。配置时需要填写以下关键参数：显示名称（数据源配置列表中的标识）、数据库地址（IP或域名）、端口（默认3306）、数据库名称、用户名和密码。如果目标数据源已配置SSL，可以选中安全协议SSL来保护数据传输安全。对于需要通过跳板机访问的场景，可以开启SSH隧道并配置跳板机的IP、用户名、密码和端口。配置完成后，单击连接测试验证连通性，确认无误后即可保存数据源。

除了MySQL，Quick BI还支持ClickHouse、SelectDB、Apache Doris、GaussDB、IBM DB2 LUW、MaxCompute、AnalyticDB for PostgreSQL、StarRocks、TiDB、RedShift等多种数据源。对于MaxCompute数据源，需要从创建数据源入口进入创建数据源界面，选择Alibaba MaxCompute数据源类型，然后完成相应的配置参数。

2.4 跨数据源关联

Quick BI支持在数据集编辑页面将来自不同数据源的数据表进行关联分析。操作方式是在数据集编辑画布中，从目标数据库下拖拽数据表至画布，再切换数据源拖拽另一数据表，然后配置关联关系（支持左连接、右连接、内连接等）。这一能力使得企业可以将分散在不同数据库中的业务数据整合到同一份报表中进行综合分析。

3. 数据集创建与数据建模

3.1 数据集的创建方式

数据集是Quick BI中进行数据分析与可视化的基础单元。创建数据集时，可以在左侧操作栏中选择需要使用的数据源，并将目标数据源表拖拽至右侧画布中开始创建。用户也可以通过自定义编写SQL代码创建数据集，具体操作可通过自定义SQL实现。除API数据源和探索空间数据源外，其他数据集均支持使用自定义SQL创建。自定义SQL的长度限制为65536字节，支持占位符功能，允许用户定义变量并在SQL中使用，这些变量可以从仪表板筛选控件、全局参数等处传入，增强了动态查询能力。

3.2 自定义SQL的使用技巧

在使用自定义SQL创建数据集时，需要注意Quick BI会把自定义SQL进行部分处理后下发至数据库执行，包括占位符解析、limit语句限制数据行数以及增加SQL注释。因此，若自定义SQL语法不正确，底层数据库会抛出错误。对于需要实现占比计算等复杂逻辑的场景，可以通过参数SQL创建数据集来实现。

4. 仪表板开发与图表配置

4.1 仪表板的创建

仪表板是Quick BI中进行数据可视化分析的核心载体，采用平铺布局来交互式地可视化和分析报表数据。登录Quick BI控制台后，可以通过多种方式进入创建仪表板页面：一是在空间外资源入口快速创建，二是在空间内资源列表上快速创建。

4.2 图表配置与数据分析

创建图表后，可以进行数据筛选、调整布局和自定义外观等操作。Quick BI提供了丰富的图表类型，包括指标看板、交叉表、折线图、柱状图、饼图等，满足不同场景的数据展示需求。在数据建模方面，需要预先完成数据建模，并且所使用的数据集必须包含相应粒度的维度字段。

5. 全局参数配置与动态传参

5.1 全局参数的概念

全局参数是Quick BI提供的一种标准化参数注入机制，允许报表使用者在预览报表时通过URL参数动态改变图表和查询控件的过滤条件。全局参数的核心价值在于实现同一份报表在不同上下文中的差异化展示。全局参数的作用对象主要有两种：第一种是查询控件，全局参数会以注入的值作为查询控件的默认值；第二种是图表本身，全局参数会在图表查询SQL上拼接额外的过滤条件（例如`and area = '华北'`），用户无法更改这个结果。

5.2 全局参数的配置方法

全局参数的配置入口位于报表顶部，报表需要先保存后才会显示配置入口。配置时需要注意以下规则：参数名称长度不超过50个字符，仅支持英文、数字和下划线。关联查询控件时，全局参数的值类型必须与查询控件关联条件的展示类型匹配。关联图表时，全局参数会自动填充到图表的SQL查询中。如果同时关联多个数据集的字段，选中字段的类型和粒度必须保持一致。

5.3 嵌入场景下的参数传递

在报表嵌入场景中，全局参数通过在嵌入URL中附加参数的方式传递。以下是一个带全局参数的嵌入URL示例：

https://bi-cn-hongkong.data.aliyun.com/embed/dashboard?workspaceId=xxx&dashboardId=yyy&param_area=华东&param_year=2026

在嵌入URL中，`param_area`和`param_year`即为全局参数，报表内部配置了同名的全局参数后，会自动接收这些值并应用到对应的查询控件或图表中。对于需要传递多个值的场景，可以按照JSON数组格式进行传递：

[{\"paramKey\": \"region\", \"joinType\": \"and\", \"value\": [\"华北\", \"华东\"]}]

6. 报表嵌入：将Quick BI能力集成到业务系统

6.1 嵌入方案概览

Quick BI支持将群空间中的报表嵌入到第三方系统中，实现业务一体化应用。根据版本和功能需求的不同，Quick BI提供了基础方案和增强方案两种嵌入模式。

基础方案适用于高级版和专业版，支持仪表板和电子表格的嵌入。在基础方案中，嵌入后的报表绑定的是报表Owner的权限，无法实现不同用户看到不同数据的效果。每个Ticket最多支持10万次访问，有效时长最大为240分钟，不支持水印、全局参数和区块嵌入。

增强方案（Ticket方案）仅适用于专业版，提供了更强大的安全管控和个性化能力。增强方案支持自定义绑定用户，实现千人千面的数据权限控制。访问次数不限量且支持自定义设置，支持水印（大屏除外）、全局参数、区块嵌入，以及任意次数的报表跳转。

6.2 基础方案实施步骤

实施基础方案的第一步是开通需要嵌入的报表。仅当报表处于发布状态时，才支持设置嵌入功能。在Quick BI产品首页进入开放平台，在嵌入报表页面选择目标工作空间和数据对象类型，选中目标报表后单击开通嵌入。开通嵌入后，系统会生成嵌入用的URL或Iframe代码。在实际集成时，需要将生成的URL嵌入到第三方系统的页面中。需要注意的是，基础方案不支持在嵌入后区分数据权限，报表的行级权限功能无法生效，与报表作者的数据权限保持一致。

6.3 增强方案（Ticket方案）实施步骤

Ticket增强方案通过票据机制实现安全管控，有效防止链接被恶意分享导致的数据泄露。

步骤一：开通嵌入报表。与基础方案类似，在开放平台的嵌入报表页面选择目标报表并开通嵌入。在报表嵌入配置对话框中，可以选择嵌入页面整体或某个具体组件。

步骤二：通过API生成AccessTicket票据。调用Quick BI的OpenAPI生成报表嵌入所需的Ticket。生成Ticket时需要指定绑定用户、有效时长和访问次数等参数。绑定用户决定了嵌入后报表展示的数据权限范围。有效时长默认240分钟，最大不超过240分钟。访问次数默认为1次，最大支持9999次。

步骤三：拼接免登URL。将生成的Ticket拼接至Quick BI报表的访问URL中，形成完整的免登嵌入链接。用户访问该链接时无需再次登录Quick BI即可查看报表，且数据权限受Ticket绑定的用户权限控制。

6.4 智能小Q嵌入

Quick BI专业版还提供了智能小Q的嵌入能力，支持将智能问答能力集成到第三方系统中。小Q嵌入同样采用Ticket票据认证机制，可实现链接、访问、问数等多场景一站式安全管控。配置小Q嵌入时，需要在组织管理 > 小Q问数 > 嵌入管理页面创建嵌入模块。配置内容包括数据范围（按问数资源或按分析主题）、智能体信息（名称、昵称、图标）、模块外观（主题风格）、输入引导及欢迎区等。配置完成后，通过调用create4Copilot接口生成Ticket，拼接URL后即可嵌入使用。

7. OpenAPI与SDK调用

7.1 API概览与调用前提

Quick BI提供了丰富的OpenAPI接口，覆盖组织用户管理、角色管理、权限管理、资源管理等维度。API的Version版本为2022-01-01。调用API需要满足两个条件：调用者的阿里云账户至少登录过一次Quick BI，且被授予Quick BI组织管理员的权限。非管理员用户也可以通过开放平台首页被授予调用API的权限。

7.2 Java SDK调用示例

使用Java SDK需要同时安装阿里云核心库（aliyun-java-sdk-core）和Quick BI专用SDK（aliyun-java-sdk-quickbi-public）。以下是一个完整的Java SDK调用示例，演示如何调用组织用户管理相关的API：

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.quickbi_public.model.v20220101.AddUserRequest;
import com.aliyuncs.quickbi_public.model.v20220101.AddUserResponse;

public class QuickBIDemo {
    public static void main(String[] args) {
        // 1. 创建Profile并设置Region
        DefaultProfile profile = DefaultProfile.getProfile(
            \"cn-hangzhou\",
            \"your-access-key-id\",
            \"your-access-key-secret\"
        );
        IAcsClient client = new DefaultAcsClient(profile);
        
        // 2. 构造请求对象
        AddUserRequest request = new AddUserRequest();
        request.setAccountName(\"user@example.com\");
        request.setAccountType(1); // 1表示RAM子账号
        request.setAdminUser(false);
        request.setAuthAdminUser(false);
        request.setNickName(\"数据分析师\");
        request.setUserType(1); // 1表示开发者
        
        try {
            // 3. 发起调用
            AddUserResponse response = client.getAcsResponse(request);
            System.out.println(\"用户ID: \" + response.getResult());
        } catch (ServerException e) {
            System.out.println(\"服务端错误: \" + e.getErrCode() + \" - \" + e.getErrMsg());
        } catch (ClientException e) {
            System.out.println(\"客户端错误: \" + e.getErrCode() + \" - \" + e.getErrMsg());
        }
    }
}

调用时需要注意使用正确的AccessKey ID和AccessKey Secret，否则会出现Specified access key is not found的错误。

7.3 Python SDK调用示例

Quick BI同样支持Python语言的SDK调用。以下是一个使用Python SDK查询组织成员列表的示例：

from aliyunsdkcore.client import AcsClient
from aliyunsdkquickbi_public.request.v20220101 import QueryUserListRequest

# 1. 创建客户端
client = AcsClient(
    'your-access-key-id',
    'your-access-key-secret',
    'cn-hangzhou'
)

# 2. 构造请求
request = QueryUserListRequest.QueryUserListRequest()
request.set_accept_format('json')

# 3. 发起调用并处理响应
try:
    response = client.do_action_with_exception(request)
    print(response.decode('utf-8'))
except Exception as e:
    print('调用失败:', str(e))

7.4 流控说明

Quick BI的API接口有明确的流控限制。以组织用户管理类API为例，添加组织成员接口的QPS为50次/秒，超时时间为10秒。查询类接口如获取组织成员列表的QPS为30次/秒。在实际开发中需要合理控制调用频率，避免触发流控限制。

8. 嵌入式JavaScript SDK开发

8.1 SDK概述

Quick BI提供了嵌入式JavaScript SDK（@quickbi/bi-embed-client-react），支持在React等前端框架中无缝嵌入Quick BI页面。通过JS SDK进行页面集成，开发者需要在自有系统内打通Quick BI的登录态，否则嵌入的页面会首先跳转到Quick BI的登录页。

8.2 React框架嵌入示例

以下是在React框架中嵌入Quick BI工作空间页面的完整示例：

import { EmbedComponent, EmbedRouteKey } from \"@quickbi/bi-embed-client-react\";

export const MyPage: React.FC = () => {
    const src = {
        origin: 'https://your-quickbi-domain.com',
        page: EmbedRouteKey.workspace,
        search: { workspaceId: 'your-workspace-id' }
    };
    return <EmbedComponent src={src} />;
};

8.3 页面定制与特性配置

SDK提供了丰富的特性配置能力，允许开发者对嵌入页面进行定制。以下示例展示了如何隐藏嵌入页面的头部导航栏：

export const SdkDemo: React.FC = () => {
    return (
        <EmbedComponent
            src={src}
            feature={{
                [EmbedRouteKey.homeRoot]: { header: { show: false } }
            }}
        />
    );
};

更复杂的定制场景包括调整按钮位置和显示状态。以下示例展示了如何隐藏发布、下线、分享按钮，同时将另存为按钮设置为保存按钮之后的主按钮：

export const SdkDemo: React.FC = () => {
    return (
        <EmbedComponent
            src={src}
            feature={{
                [EmbedRouteKey.dashboardEdit]: {
                    publish: { show: false },
                    offline: { show: false },
                    share: { show: false },
                    saveAs: { group: 'state', order: 3, type: 'primary' }
                }
            }}
        />
    );
};

8.4 路由跳转事件处理

在嵌入场景中，当用户在Quick BI页面内点击跳转（如从仪表板列表进入编辑页）时，默认会新开页面，脱离宿主环境。为了解决这个问题，SDK提供了事件监听机制，可以在路由跳转发生时阻止默认行为并在当前页重新渲染：

export const SingleSdk: React.FC = () => {
    return (
        <EmbedComponent
            src={src}
            feature={{ ... }}
            events={{
                [EmbedEventType[\"before-page-change-event\"]]: async (message: any) => {
                    // 更新EmbedComponent的src属性，重新渲染跳转后的页面
                    setSrc(message.payload.src);
                    // 阻止Quick BI的默认路由跳转逻辑
                    return false;
                }
            }}
        />
    );
};

9. 权限管理与数据安全

9.1 行级权限概述

Quick BI的行级权限功能通过条件组合授权和用户标签授权两种模式，实现了灵活、精细的数据权限控制。条件组合授权适用于多规则配合场景，如不同部门仅能看到自身产品线数据；用户标签授权则适合大规模个性化权限管理，如按地区限制数据可见性。

9.2 条件组合授权

进入Quick BI控制台后，可以在工作台或数据集编辑页设置数据集行级权限。具体操作是：单击顶部工具栏里的高级配置，选择权限管控 > 行级权限。打开启用行级权限。在行级权限配置页面选择条件组合授权，单击添加规则并配置授权方式和内容等。例如，可以选择受限用户（如某区域经理），并设置可见内容筛选条件（如区域=东北），完成后保存规则。

9.3 用户标签授权

用户标签授权需要在用户标签管理页面为用户提前配置好标签。例如某个用户负责东北地区，可以为其配置东北这个标签。在行级权限配置页面选择用户标签管理授权并设置关联条件。用户标签字段可以自定义扩展，扩展列名称以tag_开头。如果标签项对应多个权限，采用英文逗号分隔填写。

9.4 安全注意事项

在使用Ticket嵌入方案时，需要注意Ticket的有效期和访问次数限制。默认有效时长为240分钟，建议根据业务场景设置合理的过期时间。访问次数默认为1次，对于需要长期展示的报表可以适当调大。生成Ticket的账号如果在组织管理中被禁用，将无法生成新的Ticket，但已生成的Ticket仍可继续使用。如果账号被删除，则既无法生成新Ticket，已生成的Ticket也将失效。对于跨域嵌入的场景，需要注意部分系统浏览器禁止非同源的iframe嵌入页面写入Cookie，可能导致电子表格填报功能异常。

10. 最佳实践与常见问题

10.1 版本选择建议

Quick BI的嵌入能力与版本密切相关。高级版仅支持基础嵌入方案，嵌入后无法区分数据权限，适合对数据权限要求不高的场景。专业版支持增强方案（Ticket方案），可实现千人千面的数据权限控制，适合对数据安全有严格要求的场景。专业版还支持智能小Q嵌入和完整的API调用能力。

10.2 性能优化建议

在数据源配置层面，建议优先使用内网（VPC）连接，避免公网连接带来的网络延迟和带宽费用。对于大数据量的报表，可以在数据集层面使用抽取加速功能，将数据预先抽取到Quick BI的加速引擎中，提升查询性能。在嵌入层面，合理设置Ticket的访问次数和有效期，避免生成过多的无效Ticket占用系统资源。

10.3 常见故障排查

数据源连接失败时，首先检查网络连通性：公网连接需确认Quick BI的IP已加入数据库白名单；VPC连接需确认ECS实例的VPC配置正确。其次是认证信息，确认用户名、密码、AccessKey的正确性。嵌入页面无法访问时，确认报表已发布且已开通嵌入功能。Ticket方案需确认Ticket未过期且访问次数未用完。跨域问题时，检查浏览器的跨域策略和目标系统的iframe配置。

11. 总结

阿里云Quick BI提供了从数据接入、报表开发到系统集成的完整能力体系。在对接使用方面，核心要掌握三个层面的技能：数据源配置层面，需要根据数据库类型和网络环境选择合适的连接方式；报表嵌入层面，需要根据版本和能力需求选择基础方案或Ticket增强方案；API与SDK层面，需要掌握Java、Python等语言的SDK调用方法以及嵌入式JavaScript SDK的使用。全局参数的灵活运用可以帮助实现同一份报表在不同业务场景下的个性化展示，是提升嵌入方案价值的关键能力。通过合理规划版本选择、安全配置和性能优化，企业可以快速将Quick BI的智能分析能力融入自有业务系统，实现数据驱动的业务决策。

常见问题解答

问1：Quick BI基础嵌入方案和Ticket增强方案有什么区别？

答：基础方案仅支持仪表板和电子表格嵌入，绑定报表Owner的权限，每个Ticket最多10万次访问，最大有效时长240分钟，不支持水印、全局参数和区块嵌入。Ticket增强方案仅适用于专业版，支持自定义绑定用户实现千人千面，访问次数不限量，支持水印、全局参数、区块嵌入和任意次数的跳转。

问2：如何通过全局参数实现同一份报表不同用户看不同数据？

答：在报表中配置全局参数并关联到图表或查询控件的过滤条件，然后在嵌入URL中通过参数传递不同的值。配合Ticket方案绑定不同用户的权限，即可实现千人千面的数据展示。

问3：Quick BI支持哪些编程语言的SDK？

答：Quick BI支持Java、Python、C#等多种开发语言的SDK。以Java为例，需要同时安装aliyun-java-sdk-core和aliyun-java-sdk-quickbi-public两个依赖包。

问4：嵌入Quick BI报表时如何解决跨域Cookie问题？

答：部分系统浏览器（如iOS企业微信内置浏览器）禁止非同源的iframe写入Cookie，可能导致电子表格填报提交失败。建议直接通过Quick BI平台使用填报功能，或使用Ticket免登方案规避登录态依赖。

问5：Quick BI API调用需要什么权限？

答：调用API需要满足两个条件：调用者的阿里云账户至少登录过一次Quick BI，且被授予Quick BI组织管理员的权限。非管理员用户可由管理员在开放平台授予API调用权限。

问6：数据源连接失败如何排查？

答：首先检查网络连通性——公网连接需确认Quick BI的IP已加入数据库白名单，VPC连接需确认ECS实例配置正确。其次检查认证信息，确认用户名、密码和AccessKey正确。最后检查数据库服务是否正常运行及防火墙规则是否正确。