阿里云智能商业分析Quick BI对接使用完全指南
1. Quick BI产品概述与对接场景
阿里云智能商业分析Quick BI是一款全场景数据消费式的BI平台，它通过智能化的数据分析与可视化能力，帮助企业快速搭建数据门户、仪表板、电子表格等数据产品。在实际业务中，Quick BI的对接使用主要涵盖三个核心场景：数据源的接入与配置、报表与分析页面的嵌入式集成、以及通过OpenAPI实现自动化管理与数据交互。
对于已经拥有业务系统的企业而言，将Quick BI的报表能力无缝嵌入到自有系统中，是实现数据驱动决策的关键步骤。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数据源配置示例
以自建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等多种数据源。
2.4 跨数据源关联
Quick BI支持在数据集编辑页面将来自不同数据源的数据表进行关联分析。操作方式是在数据集编辑画布中，从目标数据库下拖拽数据表至画布，再切换数据源拖拽另一数据表，然后配置关联关系（支持左连接、右连接、内连接等）。这一能力使得企业可以将分散在不同数据库中的业务数据整合到同一份报表中进行综合分析。
3. 报表嵌入：将Quick BI能力集成到业务系统
3.1 嵌入方案概览
Quick BI支持将群空间中的报表嵌入到第三方系统中，实现业务一体化应用。根据版本和功能需求的不同，Quick BI提供了基础方案和增强方案两种嵌入模式。
基础方案适用于高级版和专业版，支持仪表板和电子表格的嵌入。在基础方案中，嵌入后的报表绑定的是报表Owner的权限，无法实现不同用户看到不同数据的效果。每个Ticket最多支持10万次访问，有效时长最大为240分钟，不支持水印、全局参数和区块嵌入。
增强方案（Ticket方案）仅适用于专业版，提供了更强大的安全管控和个性化能力。增强方案支持自定义绑定用户，实现千人千面的数据权限控制。访问次数不限量且支持自定义设置，支持水印（大屏除外）、全局参数、区块嵌入，以及任意次数的报表跳转。
3.2 基础方案实施步骤
实施基础方案的第一步是开通需要嵌入的报表。仅当报表处于发布状态时，才支持设置嵌入功能。在Quick BI产品首页进入开放平台，在嵌入报表页面选择目标工作空间和数据对象类型，选中目标报表后单击“开通嵌入”。
开通嵌入后，系统会生成嵌入用的URL或Iframe代码。在实际集成时，需要将生成的URL嵌入到第三方系统的页面中。需要注意的是，基础方案不支持在嵌入后区分数据权限，报表的行级权限功能无法生效，与报表作者的数据权限保持一致。
3.3 增强方案（Ticket方案）实施步骤
Ticket增强方案通过票据（Ticket）机制实现安全管控，有效防止链接被恶意分享导致的数据泄露。
步骤一：开通嵌入报表。与基础方案类似，在开放平台的嵌入报表页面选择目标报表并开通嵌入。在报表嵌入配置对话框中，可以选择嵌入页面整体或某个具体组件。
步骤二：通过API生成AccessTicket票据。调用Quick BI的OpenAPI生成报表嵌入所需的Ticket。生成Ticket时需要指定绑定用户、有效时长和访问次数等参数。绑定用户决定了嵌入后报表展示的数据权限范围。有效时长默认240分钟，最大不超过240分钟。访问次数默认为1次，最大支持9999次。
步骤三：拼接免登URL。将生成的Ticket拼接至Quick BI报表的访问URL中，形成完整的免登嵌入链接。用户访问该链接时无需再次登录Quick BI即可查看报表，且数据权限受Ticket绑定的用户权限控制。
3.4 智能小Q嵌入
Quick BI专业版还提供了智能小Q（Smart Q）的嵌入能力，支持将智能问答能力集成到第三方系统中。小Q嵌入同样采用Ticket票据认证机制，可实现链接、访问、问数等多场景一站式安全管控。
配置小Q嵌入时，需要在组织管理 > 小Q问数 > 嵌入管理页面创建嵌入模块。配置内容包括数据范围（按问数资源或按分析主题）、智能体信息（名称、昵称、图标）、模块外观（主题风格）、输入引导及欢迎区等。配置完成后，通过调用create4Copilot接口生成Ticket，拼接URL后即可嵌入使用。
4. OpenAPI与SDK调用
4.1 API概览与调用前提
Quick BI提供了丰富的OpenAPI接口，覆盖组织用户管理、角色管理、权限管理、资源管理等维度。API的Version版本为2022-01-01。调用API需要满足两个条件：调用者的阿里云账户至少登录过一次Quick BI，且被授予Quick BI组织管理员的权限。非管理员用户也可以通过开放平台首页被授予调用API的权限。
4.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”的错误。
4.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))4.4 流控说明
Quick BI的API接口有明确的流控限制。以组织用户管理类API为例，添加组织成员接口的QPS为50次/秒，超时时间为10秒。查询类接口如获取组织成员列表的QPS为30次/秒。在实际开发中需要合理控制调用频率，避免触发流控限制。
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¶m_area=华东¶m_year=2026在嵌入URL中，`param_area`和`param_year`即为全局参数，报表内部配置了同名的全局参数后，会自动接收这些值并应用到对应的查询控件或图表中。
对于需要传递多个值的场景，可以按照JSON数组格式进行传递：
[
{"paramKey": "region", "joinType": "and", "value": ["华北", "华东"]}
]5.4 权限控制与传参的结合
在增强方案中，全局参数可以与Ticket绑定用户配合使用，实现更精细的权限控制。例如，可以为不同部门的用户生成不同的Ticket，每个Ticket绑定对应的用户身份，同时在URL中注入部门维度的全局参数，从而实现同一份报表在不同用户视角下的数据隔离。
需要注意的是，全局参数关联到图表时，服务器端会直接在SQL层面拼接过滤条件，用户无法通过前端操作绕过。这一机制保证了数据权限的安全性。
6. 嵌入式JavaScript SDK开发
6.1 SDK概述
Quick BI提供了嵌入式JavaScript SDK（@quickbi/bi-embed-client-react），支持在React等前端框架中无缝嵌入Quick BI页面。通过JS SDK进行页面集成，开发者需要在自有系统内打通Quick BI的登录态，否则嵌入的页面会首先跳转到Quick BI的登录页。
6.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} />;
};6.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'
}
}
}}
/>
);
};6.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;
}
}}
/>
);
};7. 最佳实践与常见问题
7.1 版本选择建议
Quick BI的嵌入能力与版本密切相关。高级版仅支持基础嵌入方案，嵌入后无法区分数据权限，适合对数据权限要求不高的场景。专业版支持增强方案（Ticket方案），可实现千人千面的数据权限控制，适合对数据安全有严格要求的场景。专业版还支持智能小Q嵌入和完整的API调用能力。
7.2 安全注意事项
在使用Ticket嵌入方案时，需要注意Ticket的有效期和访问次数限制。默认有效时长为240分钟，建议根据业务场景设置合理的过期时间。访问次数默认为1次，对于需要长期展示的报表可以适当调大。
生成Ticket的账号如果在组织管理中被禁用，将无法生成新的Ticket，但已生成的Ticket仍可继续使用。如果账号被删除，则既无法生成新Ticket，已生成的Ticket也将失效。
对于跨域嵌入的场景，需要注意部分系统浏览器禁止非同源的iframe嵌入页面写入Cookie，可能导致电子表格填报功能异常。
7.3 性能优化建议
在数据源配置层面，建议优先使用内网（VPC）连接，避免公网连接带来的网络延迟和带宽费用。对于大数据量的报表，可以在数据集层面使用抽取加速功能，将数据预先抽取到Quick BI的加速引擎中，提升查询性能。
在嵌入层面，合理设置Ticket的访问次数和有效期，避免生成过多的无效Ticket占用系统资源。
7.4 常见故障排查
数据源连接失败时，首先检查网络连通性：公网连接需确认Quick BI的IP已加入数据库白名单；VPC连接需确认ECS实例的VPC配置正确。其次是认证信息，确认用户名、密码、AccessKey的正确性。
嵌入页面无法访问时，确认报表已发布且已开通嵌入功能。Ticket方案需确认Ticket未过期且访问次数未用完。跨域问题时，检查浏览器的跨域策略和目标系统的iframe配置。
8. 总结
阿里云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正确。最后检查数据库服务是否正常运行及防火墙规则是否正确。
