报表集成

概述

第三方系统集成报表的标准方式是「服务端签名加前端 iframe 嵌入」：appSecret 只保存在第三方服务端，由服务端生成带签名的嵌入地址，前端用 iframe 或新窗口打开，用户不需要在报表系统二次登录，首次访问时平台自动创建对应的外部用户。

可以通过这条链路嵌入的对象：网格报表、单据模板、仪表盘（同一个嵌入入口 embed.html，按报表类型自动渲染）。

集成过程涉及四篇文档，本文是主线：

功能入口

• 管理后台 系统 > 「三方集成」：注册应用，「接入说明」按钮有各场景的代码示例。
• 嵌入入口：https://<平台地址>/embed.html。
• 第三方集成示例项目由独立仓库提供：https://github.com/Sight-Data/sight-report-integration-demo（包含后端签名样例、前端集成控制台和宿主 SDK sight-report-embed.js）。

操作步骤

1. 注册应用并生成签名

按 第三方应用管理 创建应用，保存 appSecret；按 嵌入签名与令牌 在服务端计算 _s，reportId 绑定要嵌入的报表 ID。

2. 拼装嵌入 URL

https://<平台地址>/embed.html?reportId=<报表ID>&_s=<签名串>

在此基础上可追加显示控制与查询参数，见下表。

3. 前端 iframe 嵌入

<iframe id="report"
        src="https://your-domain/embed.html?reportId=rpt_sales&_s=eyJhcHBJZCI6..."
        width="100%" height="600" frameborder="0"></iframe>

也可以用 window.open(url, '_blank') 在新窗口打开。

URL 参数说明

带查询参数的完整地址示例：

const params = { year: 2025, dept: '内科' };
const url = 'https://your-domain/embed.html?reportId=rpt_sales'
  + '&_s=' + encodeURIComponent(signature)
  + '&hideToolbar=true&showQueryForm=false&viewMode=all'
  + '&parameters=' + encodeURIComponent(JSON.stringify(params));
document.getElementById('report').src = url;

访问结果与常见页面提示

外部数据集（数据由第三方提供）

报表数据可以不来自平台数据源，而是由第三方在打开报表前把数据推送过来。数据集类型在设计器中选择「运行时注入数据集」，设计时只定义字段结构。

1. 第三方后端调用 POST /api/embed/staged-dataset/set，请求体带签名和数据集内容，返回 token。
2. 嵌入或导出时，在 parameters 中加入 "_dataIds": "<token>"。
3. 用完后调用 POST /api/embed/staged-dataset/clear 释放，未清除的数据 24 小时后过期。

curl -s -X POST "$BASE/api/embed/staged-dataset/set" \
  -H 'Content-Type: application/json' \
  -d "{\"signature\":\"$S\",\"reportId\":\"$REPORT\",
       \"datasets\":{\"ds_visits\":[{\"dept\":\"内科\",\"visits\":1200},{\"dept\":\"外科\",\"visits\":980}]}}"

响应的 data 为 {"token":"...","datasetNames":["ds_visits"]}。

注意：单次上传的数据集总大小上限默认 5 MB，数据保留时间默认 24 小时（配置项 app.staged-dataset.max-payload-size、app.staged-dataset.ttl-hours）。此接口用签名验证，签名的 reportId 可为空。

导出与目录查询

• 导出 PDF、Excel、Word、CSV、OFD 的服务端直连接口、报表目录与标签查询接口，见 嵌入接口清单。
• 仪表盘的嵌入访问会沿模板授权：其中「嵌入报表」区块和点击跳转到的报表，会自动放行（最多 3 层），不需要逐个加进白名单。

注意事项

注意：appSecret 只能在服务端使用。每次打开报表都应实时生成新的签名，不要缓存。

注意：/api/embed/** 按客户端 IP 限流，每分钟最多 120 次请求。

提示：外部用户的数据权限：嵌入会话只能访问签名中 reportId 绑定的报表（以及应用白名单、可达报表范围），不具备管理员权限。

提示：同一个页面里嵌入多个 iframe 时，每个 iframe 使用各自的签名地址；宿主事件也按 iframe 分别收发。

相关文档

• 第三方应用管理
• 嵌入签名与令牌
• 宿主事件与方法调用
• 嵌入接口清单
• 公开链接与访问密码
• 大屏集成