API 数据对接实战:把业务接口变成实时大屏只需 JSONPath
第一步:盘点接口
按大屏区块(而不是按系统)列一张表:每个区块需要哪些字段、来自哪个接口。优先复用移动端/小程序已经在用的聚合接口——它们通常已经做好了跨表聚合,比直接查数据库更稳。
盘点时确认三件事:接口是否跨域受限、返回结构是否稳定、是否有测试环境。跨域问题的正解是由大屏后端做统一代理转发,而不是让业务系统改 CORS。
第二步:数据源配置四要素
在 数据源面板 里创建一个数据源,只需四项:
{
"url": "https://api.biz.allinai5.com/v1/kpi", // 接口地址
"method": "GET", // 或 POST
"headers": { "Authorization": "Bearer xxx" }, // 鉴权头
"interval": 30 // 轮询间隔(秒)
}
轮询间隔按数据热度定:核心 KPI 30 秒,日报类 5 分钟,没必要全屏 1 秒刷新——既压接口也压浏览器。
第三步:JSONPath 字段映射
接口返回什么,组件就映射什么。以最常见的统一响应结构为例:
{ "code": 0, "message": "ok", "data": {
"todayOutput": 12864, // → 今日产量
"oee": 0.924, // → 稼动率(%)
"lines": [
{ "name": "一号产线", "value": 5120 },
{ "name": "二号产线", "value": 4380 }
]
}
}
// 映射(JSONPath):
// 今日产量 $.data.todayOutput
// 稼动率 $.data.oee
// 产线数据 $.data.lines[*] → 直接喂给柱状图
规则很简单:统一响应从 $.data 起步;数组用 [*] 整体取;嵌套字段一路点下去。配好后立刻能在组件上看到真实数据。
鉴权与安全
- Token/Bearer:直接放请求头,适合只读查询接口;
- API Key 签名:按供应商规则在 headers 里带 Key 与签名,平台侧只需配置不需要实现;
- 安全建议:为大屏单独申请只读账号/密钥,接口权限最小化;密钥只存在服务端数据源配置里,不要出现在前端代码。
五个最常见的坑
- 取值路径写错:code/message 包了一层,忘了从 $.data 起步——组件显示空白最先查这里;
- 时间格式不统一:后端给时间戳,图表要日期字符串,加一层转换配置;
- 空值没有兜底:接口偶发返回 null,组件配一个默认值避免"闪没";
- 轮询过密:几十个组件都 5 秒轮询,接口被打挂;合并成聚合接口 + 放宽间隔;
- 跨域硬扛:别让业务系统为大屏单独开 CORS,用大屏后端代理转发最干净。
对接前先把 模板里的模拟数据 跑通演示,接口对接放到第二阶段——项目节奏会从容很多。
内置 API 数据源与 JSONPath 映射,配完即实时刷新。
查看数据源功能 →