报表集成

最后更新: 2026/7/30

三方集成报表的标准方式：注册外部应用拿 AppId/AppSecret，服务端用 AppSecret 签名生成带 _s 的嵌入 URL，前端 iframe 嵌入；含报表发现、导出、外部数据集接口与开源集成示例。

集成原理（三方如何集成）

第三方系统集成报表的标准方式：服务端签名 + 前端 iframe 嵌入。AppSecret 只放在服务端，由服务端签名生成嵌入 / 导出链接，前端嵌入展示。我们提供开源的「集成示例」（Sight-Data/sight-report-integration-demo）：一个可运行的集成控制台，按场景演示嵌入查看、接收事件、宿主调用、报表发现、服务端导出、外部数据集全链路，每个场景都附可直接复制的代码。

下文接口路径均以 /api 开头（平台对所有 REST 接口统一加 /api 前缀），请求地址形如 https://你的部署地址/api/embed/...。

第一步：注册外部应用

管理员在「外部应用」中注册，得到 AppId / AppSecret，并可限定：

允许的报表（allowedReportIds，多个用逗号分隔；留空表示不限制）
链接有效期（默认 60 分钟，最长 1440 分钟；签名请求的有效期超过上限时按上限截断）

管理接口：/api/admin/external-app（列表 / 详情 / 创建 / 更新 / 删除 / 重置 Secret）。

第二步：服务端生成签名

签名内容为五个字段用竖线连接，HMAC-SHA256 后再 Base64Url（无填充），作为查询参数 _s：

signContent = appId | account | userName | reportId | expireAt
signature   = HMAC-SHA256(signContent, appSecret)   // 小写十六进制
_s          = Base64Url(JSON{appId, account, userName, reportId, expireAt, signature})

expireAt 为 Unix 秒；account / userName 是你系统的当前登录人，平台会自动建号免登，账号形如 ext__{appId}__{account}。
查看报表建议绑定具体 reportId；报表发现接口通常留空以返回白名单内全部结果；服务端导出必须绑定且与请求参数 fileId 完全一致。
每次打开实时生成，建议 5~15 分钟，不要缓存 URL。

集成示例把这一步封装成 POST /api/demo/embed-url，直接返回可用的嵌入 URL；签名实现见仓库 backend-node/src/signature-service.js（约 40 行，另有 Java / Python 版）。

两种认证方式

拿到签名后有两种用法，按调用场景选一种即可（/api/embed/** 不走平台登录态，只认下面两者之一）：

方式	怎么带	适用
A. 一次性签名（无状态，推荐）	每次请求带查询参数 `_s`	嵌入 URL、报表发现接口、服务端导出。服务端不保存状态，签名到期即失效
B. 换取会话	`POST /api/embed/auth` 用签名换 `sessionToken`，之后请求带 Header `X-Embed-Session`	服务端要连续调多个接口时，省去每次重算签名；嵌入页面内部用的就是这条

POST /api/embed/auth
{"signature": "<_s 的值>", "reportId": "rpt_sales"}

→ {"code":0,"data":{"sessionToken":"...","userId":"...","userName":"...",
      "externalAccount":"ext__erp-system__u1001","appId":"erp-system",
      "reportId":"rpt_sales","expireAt":1735660800000}}

会话有效期取签名有效期与应用上限（默认 60 / 最长 1440 分钟）的较小值；可用 GET /api/embed/session/validate 校验、POST /api/embed/session/logout 主动失效。
会话模式下的报表访问范围仍受限：签名绑定了 reportId 就只能访问该报表，未绑定则按应用的报表白名单放行。
服务端导出用方式 A 时必须带 fileId，且与签名里的 reportId 完全一致。

第三步：前端 iframe 嵌入

<iframe src="https://你的部署地址/embed.html?reportId=rpt_sales&_s=<签名>"
        width="100%" height="600" frameborder="0"></iframe>

免登：签名里的 account / userName 标识业务用户，平台按 ext__{appId}__{account} 自动建号。嵌入页面会自行用 _s 换取会话并在内部请求中携带，你只需把带 _s 的 URL 交给 iframe。
参数：parameters 传查询条件（JSON 序列化后 URL 编码，对应报表参数 $param）。
呈现：hideToolbar=true 隐藏工具栏、showQueryForm=false 隐藏查询表单、viewMode=pagination|all 分页 / 全部数据。

接收报表事件与宿主调用

嵌入页面通过 postMessage 与宿主双向通信，信封统一为 {protocol:'sight-report', name, payload, source, timestamp}：

零配置直发：report:loaded、report:error，以及设计器里「单元格 → 链接 → 发送事件」配置的自定义单元格事件（payload 按点击行求值）。
订阅后才发：向 iframe 发一条 {protocol:'sight-report', type:'subscribe', events:[...]} 后，才会收到 report:query / report:query-done / report:export / report:print / report:resize。
宿主调用报表：type:'invoke' 通道支持 setParameters / query / reset / export / print / getState / setSheet / getCellValue(s)；集成示例里的 sight-report-embed.js（零依赖单文件）已封装好。

报表发现与导出接口

目录树：GET /api/embed/report/type-tree?_s=&fileType=（fileType 取 grid / document / datawall / mobile）。
标签列表：GET /api/embed/report/tag-list?_s=&tag=（tag 精确匹配）。
报表参数：GET /api/embed/report/parameters?_s=（可选 reportId）。
直接导出：GET /api/embed/export/{pdf|excel|word|csv|ofd}?_s=&fileId=，可带 parameters、fileName、pageIndex、sheetId（多页签报表指定页签）。
大数据量 Excel 走异步任务：POST /api/embed/export/excel 建任务 → GET /api/embed/export/excel/task/{taskId} 查进度 → GET /api/embed/export/excel/download/{taskId} 下载。

配置了报表白名单后，发现类接口会自动受限，第三方无需再做一次过滤。/api/embed/** 有速率限制：同一 IP 每分钟最多 120 次请求，超出返回 429。

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

POST /api/embed/staged-dataset/set 上传 datasets → 返回 token。
嵌入 / 导出时在 parameters 加 "_dataIds": "<token>"。
用完调 POST /api/embed/staged-dataset/clear 释放。

单次上传载荷上限 5 MB，数据默认保留 24 小时（可由 app.staged-dataset 配置调整）；每次 /set 生成新 token，不支持追加。报表设计时需先创建「外部数据集」并定义字段结构。

快速体验 demo

克隆集成示例仓库，复制 backend-node/.env.example 为 .env，填入产品地址与 AppId / AppSecret（环境变量前缀 SIGHT_REPORT_*）。
在 backend-node 下运行 npm install && npm start（需 Node.js 18+；Windows 可直接双击 start-demo.cmd）。
打开 http://localhost:3010/demo/，按场景依次体验：嵌入查看、接收事件、宿主调用、报表发现、服务端导出、外部数据集。