运行时注入数据集

最后更新: 2026/9/29

由宿主系统在运行时通过接口推送数据的数据集：设计时定义字段，运行时用 token 传入数据。

概述

运行时注入数据集（后端类型 staged）用于第三方系统把已有的业务数据在渲染报表时推送给报表引擎，报表不需要连接数据库。设计时只定义字段结构，不保存数据；运行时由宿主系统先调用接口上传数据，拿到 token，再通过报表参数 _dataIds 传入。

功能入口

「新建SQL数据集」拆分按钮 >「运行时注入数据集」，打开「编辑运行时注入数据集」。

操作步骤

设计时

填写「数据集名称」，如 orders。
定义字段：手动添加，或点击「粘贴数据推断」从样例数据生成字段（只推断字段，不保存样例数据）。
保存后即可在报表中绑定字段，也可以添加计算字段。

设计时预览没有传入 _dataIds 时返回空数据。

运行时

宿主后端调用 POST /api/embed/staged-dataset/set，请求体：

{
  "signature": "<签名>",
  "reportId": "rpt_visit",
  "datasets": {
    "orders": [
      {"orderId": "ORD-001", "product": "输液器", "quantity": 10, "price": 99.5},
      {"orderId": "ORD-002", "product": "注射器", "quantity": 5, "price": 149.0}
    ]
  }
}

reportId 可省略。返回 {token, datasetNames}。

在嵌入地址的 parameters 中带上 token：

/embed.html?reportId=rpt_visit&_s=<签名>&parameters={"_dataIds":"<token>","year":2024}

导出 PDF 同理：/api/embed/export/pdf?fileId=...&_s=...&parameters=...。
可选：数据用完后调用 POST /api/embed/staged-dataset/clear，请求体 {signature, token}，须与上传时是同一个应用。

属性说明

字段定义

属性	说明	取值
字段名	与推送数据中的键一致	文本
类型	字段类型	字符串、数值、整数、浮点数、日期、日期时间、布尔
标签	字段显示名	文本

服务端配置

配置项	说明	默认值
`app.staged-dataset.max-payload-size`	单次上传数据大小上限	5MB
`app.staged-dataset.ttl-hours`	token 有效期	24 小时

每次调用 /set 都生成新的 token，不会追加到旧 token。签名使用 HMAC-SHA256，与嵌入报表的签名方式相同，签名的生成见应用集成。

示例

用 curl 上传一份订单数据（$SIG 为已生成的签名）：

curl -X POST https://report.example.com/api/embed/staged-dataset/set \
  -H "Content-Type: application/json" \
  -d '{"signature":"'$SIG'","datasets":{"orders":[{"orderId":"ORD-001","quantity":10}]}}'

返回的 token 填入嵌入地址的 parameters 中 _dataIds 字段即可。

注意事项

注意：数据不在设计时保存。没有传 _dataIds 的预览与浏览都是空数据。

注意：运行时注入数据集受非 SQL 数据集行数限制，超出时报错。

提示：单次上传默认上限 5MB，数据量大时先在宿主系统侧汇总，再推送。