前言在企业数字化转型的浪潮中商业智能Business IntelligenceBI已经从独立的数据分析工具演变为深度嵌入企业业务流程的核心能力。传统的BI系统往往作为一个独立的数据分析平台存在用户需要专门登录访问。然而随着企业应用场景的复杂化和精细化越来越多的组织开始寻求将BI能力无缝集成到现有的业务系统中——无论是CRM、ERP、项目管理系统还是自定义开发的数据应用。这种需求催生了嵌入式BIEmbedded BI这一细分领域。嵌入式BI PaaS平台通过提供标准化的集成接口和灵活的嵌入机制让企业能够将数据分析能力直接嵌入到任何Web应用中实现“数据随业务走”的目标。本文将以衡石科技的BI PaaS平台为例深入剖析嵌入式BI的三种集成模式探讨其技术实现细节并为开发者提供详尽的集成指南。一、嵌入式BI PaaS概述1.1 什么是嵌入式BI PaaS嵌入式BI PaaSPlatform as a Service是一种专门用于帮助企业将BI能力嵌入到现有应用中的技术平台。与传统的BI工具不同嵌入式BI PaaS平台将复杂的报表制作、数据连接、权限管理等功能封装为可调用的服务/API开发者只需通过简单的集成操作即可在自己的应用中实现数据可视化功能。一个成熟的嵌入式BI PaaS平台通常具备以下核心特征特征描述零感知嵌入嵌入后的BI组件与宿主应用风格保持一致用户无需切换系统多粒度嵌入支持从单个图表到完整仪表盘的全方位嵌入灵活的权限体系与宿主应用的用户体系无缝对接API优先设计所有操作均可通过API驱动多租户支持满足SaaS服务商的差异化需求1.2 嵌入式BI的价值对于企业而言嵌入式BI带来了显著的商业价值用户体验提升用户无需离开当前工作上下文即可完成数据分析降低了使用门槛开发成本降低无需从零构建BI能力复用成熟平台的功能数据一致性统一的数据底座确保各业务系统使用同一套数据口径快速迭代借助平台能力快速响应业务变化缩短需求交付周期1.3 衡石科技BI PaaS平台简介衡石科技是国内领先的嵌入式BI PaaS平台提供商其平台具备以下技术优势集成友好的开放架构支持零代码整合嵌入精细化权限控制与主流身份认证系统无缝对接丰富的生态集成已服务WPP、宝马、广汽本田、阳狮集团、国药集团、亚马逊云科技等200家SaaS生态伙伴持续迭代的能力最新6.2版本增强了门户链接和仪表盘容器控件功能二、嵌入式BI PaaS的三种集成模式衡石科技BI PaaS平台提供了三种层次的集成模式从浅到深分别是分析成果嵌入、分析能力嵌入和深度集成定制。这三种模式对应着不同的业务场景和技术复杂度企业可以根据自身需求选择合适的集成深度。2.1 三种集成模式概览┌─────────────────────────────────────────────────────────────────────┐ │ 嵌入式BI PaaS集成层次 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 层次三深度集成定制Headless API │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ ▸ 自定义前端交互 │ │ │ │ ▸ 完全控制分析流程 │ │ │ │ ▸ 定制化数据处理管道 │ │ │ └─────────────────────────────────────────────────────────┘ │ │ ▲ │ │ 层次二分析能力嵌入模块化嵌入 │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ ▸ 数据集开发模块嵌入 │ │ │ │ ▸ 仪表盘创作模块嵌入 │ │ │ │ ▸ 多租户隔离创作空间 │ │ │ └─────────────────────────────────────────────────────────┘ │ │ ▲ │ │ 层次一分析成果嵌入组件化嵌入 │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ ▸ 完整仪表盘嵌入 │ │ │ │ ▸ 单图表/单控件嵌入 │ │ │ │ ▸ 灵活参数传递 │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘2.2 模式一分析成果嵌入2.2.1 模式概述分析成果嵌入是最基础的集成模式适用于将已经开发好的仪表盘、报表或图表嵌入到目标应用中。这种模式下BI平台侧的开发和配置工作已经完成宿主应用只需负责展示和数据范围控制。典型特征多粒度嵌入支持数据应用、完整仪表盘、单图表等多个层级灵活的参数传递支持数据参数过滤条件和UI参数样式配置外层系统控制宿主应用完全控制数据范围和展示样式零前端开发无需前端开发即可完成集成2.2.2 技术实现分析成果嵌入主要通过iframe嵌入或SDK嵌入两种方式实现。方式一iframe嵌入iframe嵌入是最简单直接的方式适用于对交互要求不高的场景2.3.5 适用场景分析能力嵌入模式适合以下业务场景场景描述典型用户自助BI工具为业务人员提供数据分析工具业务分析师、数据专员SaaS产品增强在SaaS产品中嵌入BI模块SaaS平台运营商行业解决方案垂直行业的定制化分析能力行业软件开发商企业内部平台构建统一的企业数据分析平台企业IT部门2.4 模式三深度集成定制2.4.1 模式概述当企业需要完全掌控分析前端的交互体验和业务流程时前两种模式就无法满足需求了。此时深度集成定制模式通过提供完整的API接口让开发者能够以衡石BI PaaS为分析底座从零构建完全定制化的前端应用。核心能力Headless API无头API支持任意前端框架完整的数据管道控制自定义数据处理流程灵活的交互定制打造独特的用户体验流程编排根据业务需求调整分析流程2.4.2 API架构设计┌─────────────────────────────────────────────────────────────────────┐ │ Headless BI API架构 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 定制前端应用 │ │ │ │ React / Vue / Angular / Solid / Svelte / 任意框架 │ │ │ └──────────────────────────┬──────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────▼──────────────────────────────────┐ │ │ │ BI API Gateway │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Auth │ │ Query │ │ Dataset │ │Dashboard│ │ │ │ │ │ API │ │ API │ │ API │ │ API │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ └──────────────────────────┬──────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────▼──────────────────────────────────┐ │ │ │ 衡石BI PaaS Core │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ 数据 │ │ 语义 │ │ 计算 │ │ 缓存 │ │ │ │ │ │ 连接器 │ │ 模型 │ │ 引擎 │ │ 引擎 │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ └───────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘2.4.3 核心API接口认证API// 认证相关API class BIAuthClient { constructor(baseUrl) { this.baseUrl baseUrl; } // SSO登录 (SAML2示例) async samlLogin(redirectUrl) { const response await fetch(${this.baseUrl}/api/v1/auth/saml/init, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ idp: authing, // 支持: teams, authing, okta等 redirectUrl }) }); const { samlUrl } await response.json(); window.location.href samlUrl; } // JWT Token验证 async validateJWT(token) { const response await fetch(${this.baseUrl}/api/v1/auth/jwt/validate, { method: POST, headers: { Authorization: Bearer ${token}, Content-Type: application/json } }); return await response.json(); } // 外部系统Token交换 async exchangeToken(externalToken) { const response await fetch(${this.baseUrl}/api/v1/auth/token/exchange, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ provider: external, token: externalToken, scope: [dashboard:read, data:query] }) }); return await response.json(); } }数据查询API// 数据查询API class BIQueryClient { constructor(baseUrl, accessToken) { this.baseUrl baseUrl; this.accessToken accessToken; } // 执行SQL查询 async executeQuery(sql, options {}) { const response await fetch(${this.baseUrl}/api/v1/query/sql, { method: POST, headers: { Authorization: Bearer ${this.accessToken}, Content-Type: application/json }, body: JSON.stringify({ sql, timeout: options.timeout || 30000, // 查询参数 params: options.params || {}, // 缓存策略 cache: { enabled: options.cache ! false, ttl: options.cacheTTL || 300 } }) }); if (!response.ok) { const error await response.json(); throw new Error(error.message); } return await response.json(); } // 通过语义模型查询 async queryFromModel(modelId, query) { const response await fetch(${this.baseUrl}/api/v1/query/model/${modelId}, { method: POST, headers: { Authorization: Bearer ${this.accessToken}, Content-Type: application/json }, body: JSON.stringify({ measures: query.measures || [], dimensions: query.dimensions || [], filters: query.filters || [], orders: query.orders || [], limit: query.limit || 1000 }) }); return await response.json(); } // 图表数据查询 async queryChartData(chartId, params {}) { const response await fetch( ${this.baseUrl}/api/v1/chart/${chartId}/data?${new URLSearchParams(params)}, { headers: { Authorization: Bearer ${this.accessToken} } } ); return await response.json(); } }仪表盘管理API// 仪表盘管理API class BIDashboardClient { constructor(baseUrl, accessToken) { this.baseUrl baseUrl; this.accessToken accessToken; } // 获取仪表盘列表 async listDashboards(options {}) { const params new URLSearchParams({ page: options.page || 1, pageSize: options.pageSize || 20, folderId: options.folderId || , tag: options.tag || }); const response await fetch( ${this.baseUrl}/api/v1/dashboards?${params}, { headers: { Authorization: Bearer ${this.accessToken} } } ); return await response.json(); } // 获取仪表盘详情 async getDashboard(dashboardId) { const response await fetch( ${this.baseUrl}/api/v1/dashboard/${dashboardId}, { headers: { Authorization: Bearer ${this.accessToken} } } ); return await response.json(); } // 创建仪表盘 async createDashboard(dashboard) { const response await fetch(${this.baseUrl}/api/v1/dashboard, { method: POST, headers: { Authorization: Bearer ${this.accessToken}, Content-Type: application/json }, body: JSON.stringify({ name: dashboard.name, description: dashboard.description, folderId: dashboard.folderId, layout: dashboard.layout, theme: dashboard.theme }) }); return await response.json(); } // 更新仪表盘 async updateDashboard(dashboardId, updates) { const response await fetch(${this.baseUrl}/api/v1/dashboard/${dashboardId}, { method: PATCH, headers: { Authorization: Bearer ${this.accessToken}, Content-Type: application/json }, body: JSON.stringify(updates) }); return await response.json(); } // 发布仪表盘 async publishDashboard(dashboardId) { const response await fetch( ${this.baseUrl}/api/v1/dashboard/${dashboardId}/publish, { method: POST, headers: { Authorization: Bearer ${this.accessToken} } } ); return await response.json(); } // 导出仪表盘 async exportDashboard(dashboardId) { const response await fetch( ${this.baseUrl}/api/v1/dashboard/${dashboardId}/export, { headers: { Authorization: Bearer ${this.accessToken} } } ); return await response.blob(); } }2.4.4 React集成示例以下是一个使用React和Headless API构建完全定制化BI前端的完整示例// React BI组件示例 import React, { useState, useEffect, useCallback } from react; // API客户端 import { BIAuthClient, BIQueryClient, BIDashboardClient } from ./bi-clients; // 自定义图表组件 import { CustomBarChart, CustomLineChart, CustomTable } from ./charts; // 主题配置 const theme { colors: [#1890ff, #52c41a, #faad14, #f5222d, #722ed1], fontFamily: PingFang SC, Microsoft YaHei, backgroundColor: #ffffff }; export const EmbeddedBI: React.FC { orgId: string; userToken: string; } ({ orgId, userToken }) { const [dashboards, setDashboards] useState([]); const [currentDashboard, setCurrentDashboard] useState(null); const [chartData, setChartData] useState({}); const [filters, setFilters] useState({}); // 初始化API客户端 const authClient new BIAuthClient(https://bi-platform.example.com); const queryClient new BIQueryClient(https://bi-platform.example.com, userToken); const dashboardClient new BIDashboardClient(https://bi-platform.example.com, userToken); // 加载仪表盘列表 useEffect(() { const loadDashboards async () { try { const result await dashboardClient.listDashboards({ folderId: orgId }); setDashboards(result.data); } catch (error) { console.error(加载仪表盘失败:, error); } }; loadDashboards(); }, [orgId]); // 加载仪表盘数据 const loadDashboardData useCallback(async (dashboardId: string) { try { const dashboard await dashboardClient.getDashboard(dashboardId); setCurrentDashboard(dashboard); // 为每个图表加载数据 const dataPromises dashboard.charts.map(async (chart) { const data await queryClient.queryChartData(chart.id, filters); return { [chart.id]: data }; }); const dataResults await Promise.all(dataPromises); const newChartData Object.assign({}, ...dataResults); setChartData(newChartData); } catch (error) { console.error(加载仪表盘数据失败:, error); } }, [filters]); // 处理筛选器变化 const handleFilterChange useCallback((filterName: string, value: any) { setFilters(prev ({ ...prev, [filterName]: value })); }, []); // 渲染图表 const renderChart (chart: any) { const data chartData[chart.id]; if (!data) return divLoading.../div; const props { data: data.result, theme, ...chart.config }; switch (chart.type) { case bar: return CustomBarChart {...props} /; case line: return CustomLineChart {...props} /; case table: return CustomTable {...props} /; default: return div不支持的图表类型/div; } }; return ( div classNameembedded-bi-container {/* 仪表盘选择器 */} div classNamedashboard-selector select onChange{(e) loadDashboardData(e.target.value)} value{currentDashboard?.id || } option value选择仪表盘/option {dashboards.map(d ( option key{d.id} value{d.id}{d.name}/option ))} /select /div {/* 筛选器区域 */} {currentDashboard?.filters ( div classNamefilters-panel {currentDashboard.filters.map(filter ( FilterComponent key{filter.id} filter{filter} value{filters[filter.paramName]} onChange{(value) handleFilterChange(filter.paramName, value)} / ))} /div )} {/* 图表网格 */} {currentDashboard ( div classNamechart-grid {currentDashboard.charts.map(chart ( div key{chart.id} classNamechart-item style{{ gridColumn: span ${chart.layout.cols || 1}, gridRow: span ${chart.layout.rows || 1} }} div classNamechart-header h3{chart.title}/h3 /div div classNamechart-body {renderChart(chart)} /div /div ))} /div )} /div ); };2.4.5 适用场景深度集成定制模式适合以下业务场景场景描述技术要求定制化BI应用从零构建独特的BI产品前端开发能力强嵌入式分析SDK封装为可分发的SDK架构设计能力流程驱动分析将分析嵌入业务流程业务理解能力强AI增强分析集成AI助手能力AI集成能力三、集成开放层技术要点无论选择哪种集成模式衡石BI PaaS平台都提供了完善的技术支持确保集成的稳定性和安全性。3.1 认证与权限体系3.1.1 SSO登录支持衡石BI PaaS支持多种SSO登录方式确保与宿主系统的身份体系无缝对接// SSO配置示例 const ssoConfig { // Microsoft Teams集成 teams: { enabled: true, tenantId: your-teams-tenant-id, clientId: your-app-client-id }, // Authing SAML2集成 authing: { enabled: true, domain: your-company.authing.cn, appId: your-app-id }, // JWT令牌验证 jwt: { enabled: true, issuer: your-auth-service, secretKey: your-secret-key, algorithms: [RS256] } };3.1.2 精细化权限控制┌─────────────────────────────────────────────────────────────────────┐ │ 权限控制层次 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 组织层 (Organization) │ │ ├── 组织管理员 │ │ └── 组织成员 │ │ │ │ │ ▼ │ │ 工作空间层 (Workspace) │ │ ├── 工作空间管理员 │ │ ├── 分析师 │ │ └── 查看者 │ │ │ │ │ ▼ │ │ 资源层 (Resource) │ │ ├── 仪表盘: 创建/编辑/查看/删除/导出 │ │ ├── 数据集: 创建/编辑/查看/删除 │ │ └── 数据源: 创建/编辑/查看/删除 │ │ │ └─────────────────────────────────────────────────────────────────────┘3.2 CORS配置跨域资源共享CORS是前端集成中的常见问题。衡石BI PaaS支持动态配置CORS// CORS配置 const corsConfig { allowedOrigins: [ https://app.example.com, https://portal.example.com, http://localhost:3000 // 开发环境 ], allowedMethods: [GET, POST, PUT, DELETE, OPTIONS], allowedHeaders: [ Content-Type, Authorization, X-Requested-With ], credentials: true, maxAge: 86400 // 预检请求缓存时间 };3.3 AI助手SDK衡石6.x版本提供了AI助手SDK支持在React应用中快速集成智能分析能力// AI助手集成示例 import { AIAssistant } from hengshi/ai-sdk-react; const App () { return ( BIProvider baseUrlhttps://bi-platform.example.com token{userToken} AIAssistant // AI助手配置 themedark positionbottom-right placeholder输入问题我来帮你分析... // 功能配置 capabilities{[ natural_language_query, // 自然语言查询 chart_recommendation, // 图表推荐 insight_generation, // 洞察生成 sql_assistant // SQL助手 ]} // 数据范围限制 dataScope{{ datasets: [sales_data, customer_data], restrictions: [region:华东] // 数据权限 }} // 回调函数 onQuery{handleQuery} onError{handleError} / /BIProvider ); };四、版本更新6.2版本集成增强衡石BI PaaS平台的6.2版本带来了重要的集成增强功能功能描述集成价值门户链接快速定位支持通过URL直接定位到发布目录简化导航提升用户体验仪表盘容器控件仪表盘可作为整体导入导出支持整体方案迁移和部署4.1 门户链接增强// 6.2版本门户链接支持 const portalUrl ${biBaseUrl}/portal/${orgId}/${folderId}; const dashboardUrl ${portalUrl}/dashboard/${dashboardId}; // 直接定位到特定目录 const folderUrl ${portalUrl}/folder/${folderId}?viewlist;4.2 仪表盘容器导入导出// 导出仪表盘包含容器 const exportPackage await dashboardClient.exportDashboard(dashboard-123, { includeContainer: true, // 包含容器样式 includeData: false, // 不包含数据 format: json }); // 导入仪表盘包 await dashboardClient.importDashboard({ package: exportPackage, targetFolder: new-folder-id, overwrite: false });五、总结与最佳实践5.1 三种集成模式对比维度分析成果嵌入分析能力嵌入深度集成定制集成复杂度低中高前端开发量无少大量定制灵活性低中高交付周期短中长适合场景快速上线产品增强独立产品技术要求基础Web技能前端开发能力全栈能力5.2 集成最佳实践从简单开始优先考虑分析成果嵌入根据业务需求逐步深入注重安全性始终通过后端获取访问令牌避免前端暴露敏感信息关注用户体验确保嵌入后的组件与宿主应用风格一致做好监控集成完成后监控API调用和性能指标版本管理关注BI平台的版本更新及时适配新特性5.3 生态伙伴案例衡石BI PaaS已经成功服务了众多行业领军企业包括汽车行业宝马、广汽本田广告传媒WPP、阳狮集团、蓝色光标医药健康国药集团科技企业亚马逊云科技消费品牌太太乐、元气森林同时平台已与200家SaaS生态伙伴建立合作包括菲尼克斯电气、中国航信、深信服、浪潮云、金蝶云、致远互联等知名企业。结语嵌入式BI PaaS正在成为企业数字化转型的重要基础设施。通过本文介绍的三种集成模式企业可以根据自身的技术能力和业务需求选择最适合的集成深度。衡石科技作为国内领先的嵌入式BI PaaS平台凭借其完善的API体系、灵活的嵌入机制和丰富的行业经验正在帮助越来越多的企业实现数据能力的敏捷交付。无论是需要快速嵌入现成仪表盘的初创企业还是希望打造完全定制化BI产品的大型组织衡石BI PaaS都能提供针对性的解决方案值得深入探索和实践。
嵌入式BI PaaS三种集成模式深度解析：从iframe嵌入到Headless API定制
前言在企业数字化转型的浪潮中商业智能Business IntelligenceBI已经从独立的数据分析工具演变为深度嵌入企业业务流程的核心能力。传统的BI系统往往作为一个独立的数据分析平台存在用户需要专门登录访问。然而随着企业应用场景的复杂化和精细化越来越多的组织开始寻求将BI能力无缝集成到现有的业务系统中——无论是CRM、ERP、项目管理系统还是自定义开发的数据应用。这种需求催生了嵌入式BIEmbedded BI这一细分领域。嵌入式BI PaaS平台通过提供标准化的集成接口和灵活的嵌入机制让企业能够将数据分析能力直接嵌入到任何Web应用中实现“数据随业务走”的目标。本文将以衡石科技的BI PaaS平台为例深入剖析嵌入式BI的三种集成模式探讨其技术实现细节并为开发者提供详尽的集成指南。一、嵌入式BI PaaS概述1.1 什么是嵌入式BI PaaS嵌入式BI PaaSPlatform as a Service是一种专门用于帮助企业将BI能力嵌入到现有应用中的技术平台。与传统的BI工具不同嵌入式BI PaaS平台将复杂的报表制作、数据连接、权限管理等功能封装为可调用的服务/API开发者只需通过简单的集成操作即可在自己的应用中实现数据可视化功能。一个成熟的嵌入式BI PaaS平台通常具备以下核心特征特征描述零感知嵌入嵌入后的BI组件与宿主应用风格保持一致用户无需切换系统多粒度嵌入支持从单个图表到完整仪表盘的全方位嵌入灵活的权限体系与宿主应用的用户体系无缝对接API优先设计所有操作均可通过API驱动多租户支持满足SaaS服务商的差异化需求1.2 嵌入式BI的价值对于企业而言嵌入式BI带来了显著的商业价值用户体验提升用户无需离开当前工作上下文即可完成数据分析降低了使用门槛开发成本降低无需从零构建BI能力复用成熟平台的功能数据一致性统一的数据底座确保各业务系统使用同一套数据口径快速迭代借助平台能力快速响应业务变化缩短需求交付周期1.3 衡石科技BI PaaS平台简介衡石科技是国内领先的嵌入式BI PaaS平台提供商其平台具备以下技术优势集成友好的开放架构支持零代码整合嵌入精细化权限控制与主流身份认证系统无缝对接丰富的生态集成已服务WPP、宝马、广汽本田、阳狮集团、国药集团、亚马逊云科技等200家SaaS生态伙伴持续迭代的能力最新6.2版本增强了门户链接和仪表盘容器控件功能二、嵌入式BI PaaS的三种集成模式衡石科技BI PaaS平台提供了三种层次的集成模式从浅到深分别是分析成果嵌入、分析能力嵌入和深度集成定制。这三种模式对应着不同的业务场景和技术复杂度企业可以根据自身需求选择合适的集成深度。2.1 三种集成模式概览┌─────────────────────────────────────────────────────────────────────┐ │ 嵌入式BI PaaS集成层次 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 层次三深度集成定制Headless API │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ ▸ 自定义前端交互 │ │ │ │ ▸ 完全控制分析流程 │ │ │ │ ▸ 定制化数据处理管道 │ │ │ └─────────────────────────────────────────────────────────┘ │ │ ▲ │ │ 层次二分析能力嵌入模块化嵌入 │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ ▸ 数据集开发模块嵌入 │ │ │ │ ▸ 仪表盘创作模块嵌入 │ │ │ │ ▸ 多租户隔离创作空间 │ │ │ └─────────────────────────────────────────────────────────┘ │ │ ▲ │ │ 层次一分析成果嵌入组件化嵌入 │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ ▸ 完整仪表盘嵌入 │ │ │ │ ▸ 单图表/单控件嵌入 │ │ │ │ ▸ 灵活参数传递 │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘2.2 模式一分析成果嵌入2.2.1 模式概述分析成果嵌入是最基础的集成模式适用于将已经开发好的仪表盘、报表或图表嵌入到目标应用中。这种模式下BI平台侧的开发和配置工作已经完成宿主应用只需负责展示和数据范围控制。典型特征多粒度嵌入支持数据应用、完整仪表盘、单图表等多个层级灵活的参数传递支持数据参数过滤条件和UI参数样式配置外层系统控制宿主应用完全控制数据范围和展示样式零前端开发无需前端开发即可完成集成2.2.2 技术实现分析成果嵌入主要通过iframe嵌入或SDK嵌入两种方式实现。方式一iframe嵌入iframe嵌入是最简单直接的方式适用于对交互要求不高的场景2.3.5 适用场景分析能力嵌入模式适合以下业务场景场景描述典型用户自助BI工具为业务人员提供数据分析工具业务分析师、数据专员SaaS产品增强在SaaS产品中嵌入BI模块SaaS平台运营商行业解决方案垂直行业的定制化分析能力行业软件开发商企业内部平台构建统一的企业数据分析平台企业IT部门2.4 模式三深度集成定制2.4.1 模式概述当企业需要完全掌控分析前端的交互体验和业务流程时前两种模式就无法满足需求了。此时深度集成定制模式通过提供完整的API接口让开发者能够以衡石BI PaaS为分析底座从零构建完全定制化的前端应用。核心能力Headless API无头API支持任意前端框架完整的数据管道控制自定义数据处理流程灵活的交互定制打造独特的用户体验流程编排根据业务需求调整分析流程2.4.2 API架构设计┌─────────────────────────────────────────────────────────────────────┐ │ Headless BI API架构 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 定制前端应用 │ │ │ │ React / Vue / Angular / Solid / Svelte / 任意框架 │ │ │ └──────────────────────────┬──────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────▼──────────────────────────────────┐ │ │ │ BI API Gateway │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Auth │ │ Query │ │ Dataset │ │Dashboard│ │ │ │ │ │ API │ │ API │ │ API │ │ API │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ └──────────────────────────┬──────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────▼──────────────────────────────────┐ │ │ │ 衡石BI PaaS Core │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ 数据 │ │ 语义 │ │ 计算 │ │ 缓存 │ │ │ │ │ │ 连接器 │ │ 模型 │ │ 引擎 │ │ 引擎 │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ └───────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘2.4.3 核心API接口认证API// 认证相关API class BIAuthClient { constructor(baseUrl) { this.baseUrl baseUrl; } // SSO登录 (SAML2示例) async samlLogin(redirectUrl) { const response await fetch(${this.baseUrl}/api/v1/auth/saml/init, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ idp: authing, // 支持: teams, authing, okta等 redirectUrl }) }); const { samlUrl } await response.json(); window.location.href samlUrl; } // JWT Token验证 async validateJWT(token) { const response await fetch(${this.baseUrl}/api/v1/auth/jwt/validate, { method: POST, headers: { Authorization: Bearer ${token}, Content-Type: application/json } }); return await response.json(); } // 外部系统Token交换 async exchangeToken(externalToken) { const response await fetch(${this.baseUrl}/api/v1/auth/token/exchange, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ provider: external, token: externalToken, scope: [dashboard:read, data:query] }) }); return await response.json(); } }数据查询API// 数据查询API class BIQueryClient { constructor(baseUrl, accessToken) { this.baseUrl baseUrl; this.accessToken accessToken; } // 执行SQL查询 async executeQuery(sql, options {}) { const response await fetch(${this.baseUrl}/api/v1/query/sql, { method: POST, headers: { Authorization: Bearer ${this.accessToken}, Content-Type: application/json }, body: JSON.stringify({ sql, timeout: options.timeout || 30000, // 查询参数 params: options.params || {}, // 缓存策略 cache: { enabled: options.cache ! false, ttl: options.cacheTTL || 300 } }) }); if (!response.ok) { const error await response.json(); throw new Error(error.message); } return await response.json(); } // 通过语义模型查询 async queryFromModel(modelId, query) { const response await fetch(${this.baseUrl}/api/v1/query/model/${modelId}, { method: POST, headers: { Authorization: Bearer ${this.accessToken}, Content-Type: application/json }, body: JSON.stringify({ measures: query.measures || [], dimensions: query.dimensions || [], filters: query.filters || [], orders: query.orders || [], limit: query.limit || 1000 }) }); return await response.json(); } // 图表数据查询 async queryChartData(chartId, params {}) { const response await fetch( ${this.baseUrl}/api/v1/chart/${chartId}/data?${new URLSearchParams(params)}, { headers: { Authorization: Bearer ${this.accessToken} } } ); return await response.json(); } }仪表盘管理API// 仪表盘管理API class BIDashboardClient { constructor(baseUrl, accessToken) { this.baseUrl baseUrl; this.accessToken accessToken; } // 获取仪表盘列表 async listDashboards(options {}) { const params new URLSearchParams({ page: options.page || 1, pageSize: options.pageSize || 20, folderId: options.folderId || , tag: options.tag || }); const response await fetch( ${this.baseUrl}/api/v1/dashboards?${params}, { headers: { Authorization: Bearer ${this.accessToken} } } ); return await response.json(); } // 获取仪表盘详情 async getDashboard(dashboardId) { const response await fetch( ${this.baseUrl}/api/v1/dashboard/${dashboardId}, { headers: { Authorization: Bearer ${this.accessToken} } } ); return await response.json(); } // 创建仪表盘 async createDashboard(dashboard) { const response await fetch(${this.baseUrl}/api/v1/dashboard, { method: POST, headers: { Authorization: Bearer ${this.accessToken}, Content-Type: application/json }, body: JSON.stringify({ name: dashboard.name, description: dashboard.description, folderId: dashboard.folderId, layout: dashboard.layout, theme: dashboard.theme }) }); return await response.json(); } // 更新仪表盘 async updateDashboard(dashboardId, updates) { const response await fetch(${this.baseUrl}/api/v1/dashboard/${dashboardId}, { method: PATCH, headers: { Authorization: Bearer ${this.accessToken}, Content-Type: application/json }, body: JSON.stringify(updates) }); return await response.json(); } // 发布仪表盘 async publishDashboard(dashboardId) { const response await fetch( ${this.baseUrl}/api/v1/dashboard/${dashboardId}/publish, { method: POST, headers: { Authorization: Bearer ${this.accessToken} } } ); return await response.json(); } // 导出仪表盘 async exportDashboard(dashboardId) { const response await fetch( ${this.baseUrl}/api/v1/dashboard/${dashboardId}/export, { headers: { Authorization: Bearer ${this.accessToken} } } ); return await response.blob(); } }2.4.4 React集成示例以下是一个使用React和Headless API构建完全定制化BI前端的完整示例// React BI组件示例 import React, { useState, useEffect, useCallback } from react; // API客户端 import { BIAuthClient, BIQueryClient, BIDashboardClient } from ./bi-clients; // 自定义图表组件 import { CustomBarChart, CustomLineChart, CustomTable } from ./charts; // 主题配置 const theme { colors: [#1890ff, #52c41a, #faad14, #f5222d, #722ed1], fontFamily: PingFang SC, Microsoft YaHei, backgroundColor: #ffffff }; export const EmbeddedBI: React.FC { orgId: string; userToken: string; } ({ orgId, userToken }) { const [dashboards, setDashboards] useState([]); const [currentDashboard, setCurrentDashboard] useState(null); const [chartData, setChartData] useState({}); const [filters, setFilters] useState({}); // 初始化API客户端 const authClient new BIAuthClient(https://bi-platform.example.com); const queryClient new BIQueryClient(https://bi-platform.example.com, userToken); const dashboardClient new BIDashboardClient(https://bi-platform.example.com, userToken); // 加载仪表盘列表 useEffect(() { const loadDashboards async () { try { const result await dashboardClient.listDashboards({ folderId: orgId }); setDashboards(result.data); } catch (error) { console.error(加载仪表盘失败:, error); } }; loadDashboards(); }, [orgId]); // 加载仪表盘数据 const loadDashboardData useCallback(async (dashboardId: string) { try { const dashboard await dashboardClient.getDashboard(dashboardId); setCurrentDashboard(dashboard); // 为每个图表加载数据 const dataPromises dashboard.charts.map(async (chart) { const data await queryClient.queryChartData(chart.id, filters); return { [chart.id]: data }; }); const dataResults await Promise.all(dataPromises); const newChartData Object.assign({}, ...dataResults); setChartData(newChartData); } catch (error) { console.error(加载仪表盘数据失败:, error); } }, [filters]); // 处理筛选器变化 const handleFilterChange useCallback((filterName: string, value: any) { setFilters(prev ({ ...prev, [filterName]: value })); }, []); // 渲染图表 const renderChart (chart: any) { const data chartData[chart.id]; if (!data) return divLoading.../div; const props { data: data.result, theme, ...chart.config }; switch (chart.type) { case bar: return CustomBarChart {...props} /; case line: return CustomLineChart {...props} /; case table: return CustomTable {...props} /; default: return div不支持的图表类型/div; } }; return ( div classNameembedded-bi-container {/* 仪表盘选择器 */} div classNamedashboard-selector select onChange{(e) loadDashboardData(e.target.value)} value{currentDashboard?.id || } option value选择仪表盘/option {dashboards.map(d ( option key{d.id} value{d.id}{d.name}/option ))} /select /div {/* 筛选器区域 */} {currentDashboard?.filters ( div classNamefilters-panel {currentDashboard.filters.map(filter ( FilterComponent key{filter.id} filter{filter} value{filters[filter.paramName]} onChange{(value) handleFilterChange(filter.paramName, value)} / ))} /div )} {/* 图表网格 */} {currentDashboard ( div classNamechart-grid {currentDashboard.charts.map(chart ( div key{chart.id} classNamechart-item style{{ gridColumn: span ${chart.layout.cols || 1}, gridRow: span ${chart.layout.rows || 1} }} div classNamechart-header h3{chart.title}/h3 /div div classNamechart-body {renderChart(chart)} /div /div ))} /div )} /div ); };2.4.5 适用场景深度集成定制模式适合以下业务场景场景描述技术要求定制化BI应用从零构建独特的BI产品前端开发能力强嵌入式分析SDK封装为可分发的SDK架构设计能力流程驱动分析将分析嵌入业务流程业务理解能力强AI增强分析集成AI助手能力AI集成能力三、集成开放层技术要点无论选择哪种集成模式衡石BI PaaS平台都提供了完善的技术支持确保集成的稳定性和安全性。3.1 认证与权限体系3.1.1 SSO登录支持衡石BI PaaS支持多种SSO登录方式确保与宿主系统的身份体系无缝对接// SSO配置示例 const ssoConfig { // Microsoft Teams集成 teams: { enabled: true, tenantId: your-teams-tenant-id, clientId: your-app-client-id }, // Authing SAML2集成 authing: { enabled: true, domain: your-company.authing.cn, appId: your-app-id }, // JWT令牌验证 jwt: { enabled: true, issuer: your-auth-service, secretKey: your-secret-key, algorithms: [RS256] } };3.1.2 精细化权限控制┌─────────────────────────────────────────────────────────────────────┐ │ 权限控制层次 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 组织层 (Organization) │ │ ├── 组织管理员 │ │ └── 组织成员 │ │ │ │ │ ▼ │ │ 工作空间层 (Workspace) │ │ ├── 工作空间管理员 │ │ ├── 分析师 │ │ └── 查看者 │ │ │ │ │ ▼ │ │ 资源层 (Resource) │ │ ├── 仪表盘: 创建/编辑/查看/删除/导出 │ │ ├── 数据集: 创建/编辑/查看/删除 │ │ └── 数据源: 创建/编辑/查看/删除 │ │ │ └─────────────────────────────────────────────────────────────────────┘3.2 CORS配置跨域资源共享CORS是前端集成中的常见问题。衡石BI PaaS支持动态配置CORS// CORS配置 const corsConfig { allowedOrigins: [ https://app.example.com, https://portal.example.com, http://localhost:3000 // 开发环境 ], allowedMethods: [GET, POST, PUT, DELETE, OPTIONS], allowedHeaders: [ Content-Type, Authorization, X-Requested-With ], credentials: true, maxAge: 86400 // 预检请求缓存时间 };3.3 AI助手SDK衡石6.x版本提供了AI助手SDK支持在React应用中快速集成智能分析能力// AI助手集成示例 import { AIAssistant } from hengshi/ai-sdk-react; const App () { return ( BIProvider baseUrlhttps://bi-platform.example.com token{userToken} AIAssistant // AI助手配置 themedark positionbottom-right placeholder输入问题我来帮你分析... // 功能配置 capabilities{[ natural_language_query, // 自然语言查询 chart_recommendation, // 图表推荐 insight_generation, // 洞察生成 sql_assistant // SQL助手 ]} // 数据范围限制 dataScope{{ datasets: [sales_data, customer_data], restrictions: [region:华东] // 数据权限 }} // 回调函数 onQuery{handleQuery} onError{handleError} / /BIProvider ); };四、版本更新6.2版本集成增强衡石BI PaaS平台的6.2版本带来了重要的集成增强功能功能描述集成价值门户链接快速定位支持通过URL直接定位到发布目录简化导航提升用户体验仪表盘容器控件仪表盘可作为整体导入导出支持整体方案迁移和部署4.1 门户链接增强// 6.2版本门户链接支持 const portalUrl ${biBaseUrl}/portal/${orgId}/${folderId}; const dashboardUrl ${portalUrl}/dashboard/${dashboardId}; // 直接定位到特定目录 const folderUrl ${portalUrl}/folder/${folderId}?viewlist;4.2 仪表盘容器导入导出// 导出仪表盘包含容器 const exportPackage await dashboardClient.exportDashboard(dashboard-123, { includeContainer: true, // 包含容器样式 includeData: false, // 不包含数据 format: json }); // 导入仪表盘包 await dashboardClient.importDashboard({ package: exportPackage, targetFolder: new-folder-id, overwrite: false });五、总结与最佳实践5.1 三种集成模式对比维度分析成果嵌入分析能力嵌入深度集成定制集成复杂度低中高前端开发量无少大量定制灵活性低中高交付周期短中长适合场景快速上线产品增强独立产品技术要求基础Web技能前端开发能力全栈能力5.2 集成最佳实践从简单开始优先考虑分析成果嵌入根据业务需求逐步深入注重安全性始终通过后端获取访问令牌避免前端暴露敏感信息关注用户体验确保嵌入后的组件与宿主应用风格一致做好监控集成完成后监控API调用和性能指标版本管理关注BI平台的版本更新及时适配新特性5.3 生态伙伴案例衡石BI PaaS已经成功服务了众多行业领军企业包括汽车行业宝马、广汽本田广告传媒WPP、阳狮集团、蓝色光标医药健康国药集团科技企业亚马逊云科技消费品牌太太乐、元气森林同时平台已与200家SaaS生态伙伴建立合作包括菲尼克斯电气、中国航信、深信服、浪潮云、金蝶云、致远互联等知名企业。结语嵌入式BI PaaS正在成为企业数字化转型的重要基础设施。通过本文介绍的三种集成模式企业可以根据自身的技术能力和业务需求选择最适合的集成深度。衡石科技作为国内领先的嵌入式BI PaaS平台凭借其完善的API体系、灵活的嵌入机制和丰富的行业经验正在帮助越来越多的企业实现数据能力的敏捷交付。无论是需要快速嵌入现成仪表盘的初创企业还是希望打造完全定制化BI产品的大型组织衡石BI PaaS都能提供针对性的解决方案值得深入探索和实践。
