嵌入式BI开发指南：如何通过衡石API将分析能力集成到业务系统？

在数字化转型的浪潮下，企业越来越依赖数据驱动决策。然而，传统BI工具往往需要用户在不同系统间切换，导致分析效率低下。嵌入式BI 的出现，让企业能够在现有业务系统（如CRM、ERP、OA）中直接集成数据分析能力，无需跳转即可查看实时报表。

本文将基于衡石科技的嵌入式BI解决方案，详细介绍如何通过其开放API，将BI能力无缝集成到业务系统中，并提供关键代码示例和最佳实践。

1. 什么是嵌入式BI？

嵌入式BI是指将数据分析、可视化、仪表盘等功能直接嵌入到企业现有的业务应用程序中，使终端用户在不离开系统的情况下完成数据探索和决策支持。

核心优势

✅ 无缝集成：无需跳转至独立BI平台，提升用户体验。
✅ 降低开发成本：复用现有BI能力，避免重复造轮子。
✅ 数据实时性：直接对接企业数据源，确保分析结果最新。
✅ 权限管控：与业务系统权限体系对接，保障数据安全。

衡石科技的嵌入式BI解决方案提供完整的API和SDK支持，适用于Java、Python、JavaScript等主流开发语言，可快速实现深度集成。

2. 衡石嵌入式BI的核心API能力

衡石科技提供了一套完整的RESTful API和JavaScript SDK，支持以下核心功能：

API类别	功能说明
仪表板嵌入	将预定义的可视化看板（Dashboard）嵌入到业务系统页面中，支持动态参数传递。
自助分析嵌入	允许用户在业务系统内直接进行自助数据分析，如拖拽式查询、筛选、下钻等操作。
单图表嵌入	单独嵌入某个图表（如折线图、柱状图），适用于需要在业务表单中展示关键指标的场景。
数据权限控制	通过API动态设置行级/列级数据权限，确保用户仅能看到权限范围内的数据。
事件交互	支持BI组件与业务系统的双向通信，例如点击图表触发业务逻辑，或业务数据更新后刷新报表。

3. 实战：通过衡石API嵌入BI到业务系统

3.1 前置准备

获取API Key：在衡石科技管理后台申请开发者权限，获取API Key和Access Token。
确定嵌入方式：
- iframe嵌入（简单快捷，适合基础场景）
- JavaScript SDK（更高灵活性，支持深度交互）
- RESTful API（适用于后端集成，如权限控制、数据预加载）

3.2 示例1：使用iframe快速嵌入仪表板

适用于需要快速集成的场景，只需几行HTML代码即可完成：

html

<iframesrc="https://api.hengshi.com/embed/dashboard/{DASHBOARD_ID}?token={ACCESS_TOKEN}"width="100%"height="600px"frameborder="0"
></iframe>

参数说明：

DASHBOARD_ID：衡石平台上的仪表板ID
ACCESS_TOKEN：衡石API鉴权Token（建议后端动态生成，避免泄露）

3.3 示例2：使用JavaScript SDK实现深度交互

如果需要更灵活的交互（如动态传参、事件监听），可使用衡石提供的HSBI SDK：

javascript

// 1. 引入SDK
<script src="https://cdn.hengshi.com/sdk/hsbi-embed.js"></script>// 2. 初始化BI组件
const embed = new HSBI.Embed({container: document.getElementById("bi-container"), // 挂载DOM节点dashboardId: "DASHBOARD_ID",accessToken: "API_ACCESS_TOKEN",filters: {  // 动态传参（如按部门筛选数据）department: "sales"}
});// 3. 监听BI事件（如用户点击图表）
embed.on("chartClick", (event) => {console.log("用户点击图表数据：", event.data);// 可触发业务系统逻辑，如跳转至详情页
});

3.4 示例3：后端动态控制数据权限（Python示例）

衡石API支持通过后端代码动态设置数据权限，确保用户仅能看到自己的数据：

python

import requests# 获取嵌入Token（带权限参数）
def get_embed_token(user_id):url = "https://api.hengshi.com/v1/embed/token"headers = {"Authorization": "Bearer YOUR_API_KEY"}payload = {"dashboard_id": "DASHBOARD_ID","user_id": user_id,"row_filters": {  # 行级权限：限制用户只能看到自己的销售数据"sales_data": f"sales_rep_id = '{user_id}'"}}response = requests.post(url, json=payload, headers=headers)return response.json()["access_token"]