工业历史趋势图为什么会误导人?用三条数据检查倒序、缺测和截断
适合读者:趋势图、看板与历史查询开发者。
读完可以做什么:用三条数据检查升序绘图、null断线和hasMore提示,避免把缺测画成正常运行。
IndustrialSphere开发实战 · 第2篇,共3篇
选择“今天”,接口返回1000条数据,折线也画出来了。这张图是否真的代表今天?如果返回的是最近1000条记录,页面却仍标着全天,读者看到的范围就可能与实际数据范围不一致。
另外两类问题也容易藏在正常渲染的折线里:时间顺序反了,或通讯中断被连成一段平滑曲线。本文使用EdgeHub历史接口,给出查询、转换和判断方法,示例点位为Demo_Temperature。
同一份历史,为什么需要两种使用方式
现场人员排查一次故障,需要看原始变化和异常时段;管理看板回顾一周,需要合适粒度的趋势。IndustrialSphere既提供EdgeHub原始历史接口,也为已配置的集成应用提供按间隔聚合的历史能力。选择哪条路径,应由问题决定。
| 需求 | 合理的数据路径 | 不应忽略的信息 |
|---|---|---|
| 查一次温度突变前后 | 原始历史查询 | 时间、质量、缺测与截断 |
| 看一周温度走势 | 按明确间隔的聚合趋势 | 聚合算法、间隔与样本有效性 |
| 算累计电量的区间用量 | 依据累计量与业务规则的计算 | 起止边界、复位、倍率、异常 |
| 分析状态持续时间 | 按状态变化和时间的业务处理 | 区间边界、状态语义、未知时段 |
不能把所有点都按平均值处理。温度小时均值可以帮助观察趋势,累计电量的小时均值却不是该小时用电量。平台提供查询和显示的基础,项目负责为每类数据选择合适的解释方式。
先确认历史已经产生
历史接口不会根据当前值生成过去的数据。开始之前,应确认测试点位已经启用所需归档、历史存储可用,并在网关侧查看到实际记录。
如果没有记录,先检查归档配置与存储状态,再检查查询时间。接口返回空集合与历史库连接失败是不同情况,页面也应分别表达。
明确查询时区和范围
以下示例查询一个带明确时区的小时区间。日期只是请求格式示例,使用时应换成测试环境确有历史记录的时间。
POST /api/v1/edgehub/history
Authorization: Bearer {{token}}
Content-Type: application/json
{
"tagNames": ["Demo_Temperature"],
"from": "2026-11-16T08:00:00+08:00",
"to": "2026-11-16T09:00:00+08:00",
"limit": 1000
}
令牌取得方式见上一篇。时间使用带时区的ISO格式,页面显示时再转换到目标时区。不要通过简单增加八小时、删除时区等方式修正读数,否则跨环境时容易出现重复转换。
当前接口单次最多查询50个变量,时间跨度不超过31天,单点返回数量上限为10000。项目仍应按实际点数、采样密度与页面用途选择更小的合理范围。
读取结果时检查完整性
响应包含data和hasMore。data按变量名称组织数据点,每个点包含timestamp、value和quality;hasMore按点位提示查询结果是否存在截断。
当前接口按时间倒序返回记录。绘图前应按实际时间升序整理,再把数值字符串转换为有限数字。质量异常的状态记录可能以空值表达,空值不能转换为零。
如果hasMore.Demo_Temperature为真,这批数据就不能代表完整查询区间。页面应明确提示,并缩小时间范围或分段获取。相邻查询边界可能重复包含同一记录,合并时需处理重复边界,不能把重复样本用于二次统计。
缺测不要自动连成正常曲线

图:人工数据样例:按时间升序显示,异常空值保留断点,同时检查查询是否截断。图示为说明示例。
可以用下面三条示例数据检查自己的图表。这是用于页面验证的人工样例,按接口返回的时间倒序排列。
| 返回顺序 | 数据时间 | value | quality |
|---|---|---|---|
| 1 | 08:02 | "27" |
192,正常 |
| 2 | 08:01 | null |
0,异常 |
| 3 | 08:00 | "25" |
192,正常 |
绘图前先按时间升序整理。08:01应保留为空值断点:把null转成0,会制造一次不存在的温度骤降;删除这一条再连接两端,又会掩盖中间的异常。图表需要保留缺口,并关闭跨空值连线等不符合当前需求的选项。
趋势应利用质量异常记录显示断点;对于没有显式异常记录的长间隔,还要结合项目的采样与归档规则判断是否构成缺口。按变化保存的数据,连续相同值可能不会不断新增记录,因此不能仅凭时间间隔做统一推断。
页面还可以分开显示“请求范围”和“实际返回范围”。当hasMore为真时,提示“当前结果已截断,请缩小范围”,比只展示一条填满画布的曲线更便于判断。悬停时显示原始时间、数值和质量,方便工程人员核对记录。
实时曲线、历史查询和统计结果分开设计
实时卡片适合当前快照;历史趋势读取已归档记录;日均值、峰值等统计则需要明确有效样本与时间口径。
如果只取最近1000条记录再计算“全天平均值”,即使折线能够显示,也可能得到错误的日统计。用于报表的计算应覆盖约定区间,并明确缺测处理,不能直接把绘图采样结果当作完整统计依据。
IndustrialSphere提供两种实施入口:采用BI已有的EdgeHub历史趋势绑定,或由自己的应用调用历史接口。前者适合先完成平台内展示,后者便于把曲线嵌入已有业务流程;两种方式都需要确认数据覆盖范围与统计口径。
用几种可解释的数据检查页面
建议在测试环境分别检查数值上升、数值稳定、通讯异常、没有历史和返回截断。核对图表左右端时间、单位、断点及提示是否符合预期。
一条可用的工业趋势,应该帮助读者判断实际发生了什么,也清楚表达哪些时间没有足够依据。
把三条记录转成图表数据,而不掩盖缺测
下面的函数面向单个数值点位,输出常见图表库可使用的“时间—值”数组。所有记录都是人工样例;函数是应用层示例,不是平台内置SDK。调用者仍需设置图表库的断点选项,例如关闭跨null连线。
function toTrendPoints(rows) {
return rows.map(row => {
const time = Date.parse(row.timestamp);
if (!Number.isFinite(time)) throw new Error("历史时间无效");
const quality = Number(row.quality);
const good = Number.isInteger(quality) && (quality & 0xC0) === 0xC0;
const raw = row.value;
const value = typeof raw === "number" ? raw
: typeof raw === "string" && raw.trim() !== "" ? Number(raw) : NaN;
return [time, good && Number.isFinite(value) ? value : null];
}).sort((a, b) => a[0] - b[0]);
}
const sample = [
{ timestamp: "2026-11-16T08:02:00+08:00", value: "27", quality: 192 },
{ timestamp: "2026-11-16T08:01:00+08:00", value: null, quality: 0 },
{ timestamp: "2026-11-16T08:00:00+08:00", value: "25", quality: 192 }
];
const points = toTrendPoints(sample); // 时间升序,数值为25、null、27
这里保留null的意义,是让08:01成为明确的未知,而不是0℃或自动连接的26℃。若通讯期间完全没有任何记录,仅保留已返回的null还不够;还要根据项目约定识别长时间空档,并用中断标记、分段曲线或区间背景表达。不能宣称这段函数已经检测所有缺测。
同样,函数排序并未解决不同来源在同一时刻出现冲突值的问题。合并分段查询时应处理重复边界;合并多节点数据时应保留来源。选择“最后一条”或“平均一下”之前,需要确认它们究竟是重复记录还是不同观测。
用查询规模说明为何要区分原始记录与聚合
假设一个点每秒归档一条,一天会有86400条记录,三天会有259200条。这是记录数量演算,不是任何设备的实际采样记录。对单点上限10000的查询而言,一次请求显然无法返回完整三天原始数据。
可以缩小区间并处理分页或分段边界,也可以在问题允许时查询聚合结果。例如按5分钟一个时间段,一天有288个时间段。较少的数据点更适合概览,但平均值可能隐藏短时尖峰,所以故障排查仍需回到对应原始时段。
IndustrialSphere集成历史接口/api/integrations/industrialsphere/history使用自己的请求结构和认证方式,支持按指定间隔形成趋势结果。它与前文/api/v1/edgehub/history不是同一个接口;不能把前者的tags和intervalSeconds直接复制给后者。配置BI的EdgeHub历史趋势数据源时,应按对应集成路径准备权限与点位。
自己开发趋势,还是用BI配置趋势
如果趋势需要嵌入已有MES工单页,自己调用API并控制交互通常更贴合产品。若需求是公辅运行驾驶舱、设备参数概览,IndustrialSphere BI可以通过EdgeHub点位数据源选择历史趋势,再按画布组织组件。

图:既有演示大屏,展示趋势与指标的配置成果。读数与曲线为演示,不作为现场稳定性、节能或性能证据。
两条路线可以并存。平台的价值在于已有历史和数据接口能服务不同应用:实施人员配置管理展示,软件人员开发业务交互。无论采用哪条路线,都应检查时间范围、点位质量、数据完整性和统计含义,避免把界面完成度误当成数据正确性。
延伸阅读与交流
上一篇:通过API读取实时数据;下一篇:从写入请求到回读确认。BI介绍说明现成的趋势与报表能力。
可以把上面的三条样例放进自己的绘图逻辑,观察时间顺序、断点和空值处理,再核对一次截断提示。欢迎带上脱敏后的返回数据和页面表现,到IndustrialSphere技术交流群(QQ群:1128988613)交流趋势页面的实现。
相关阅读:
浙公网安备 33010602011771号