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、用户名、密码和端口。配置完成后单击“连接测试”验证连通性确认无误后即可保存数据源。除了MySQLQuick 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专业版还提供了智能小QSmart 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专用SDKaliyun-java-sdk-quickbi-public。以下是一个完整的Java SDK调用示例演示如何调用组织用户管理相关的APIimport 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(userexample.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?workspaceIdxxxdashboardIdyyy¶m_area华东¶m_year2026在嵌入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 SDKquickbi/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的智能分析能力融入自有业务系统实现数据驱动的业务决策。常见问题解答问1Quick BI基础嵌入方案和Ticket增强方案有什么区别答基础方案仅支持仪表板和电子表格嵌入绑定报表Owner的权限每个Ticket最多10万次访问最大有效时长240分钟不支持水印、全局参数和区块嵌入。Ticket增强方案仅适用于专业版支持自定义绑定用户实现千人千面访问次数不限量支持水印、全局参数、区块嵌入和任意次数的跳转。问2如何通过全局参数实现同一份报表不同用户看不同数据答在报表中配置全局参数并关联到图表或查询控件的过滤条件然后在嵌入URL中通过参数传递不同的值。配合Ticket方案绑定不同用户的权限即可实现千人千面的数据展示。问3Quick 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免登方案规避登录态依赖。问5Quick BI API调用需要什么权限答调用API需要满足两个条件调用者的阿里云账户至少登录过一次Quick BI且被授予Quick BI组织管理员的权限。非管理员用户可由管理员在开放平台授予API调用权限。问6数据源连接失败如何排查答首先检查网络连通性——公网连接需确认Quick BI的IP已加入数据库白名单VPC连接需确认ECS实例配置正确。其次检查认证信息确认用户名、密码和AccessKey正确。最后检查数据库服务是否正常运行及防火墙规则是否正确。