4.4 历史数据接口

历史数据通过 POST /web、cmd 为 data_hisload_list 获取。

先设存盘方式才有历史

数据点默认是「不存盘」，没设过存盘方式的点查不到任何历史数据。存盘方式在云平台「数据管理 → 实时数据库 → 存盘方式」里逐点设置，可选的存盘方式和它决定的可用时间粒度见云组态手册的历史数据源配置章节。

4.4.1 请求结构

注意查询参数都嵌在 data 对象里，不是平铺在顶层：

{
  "cmd": "data_hisload_list",
  "username": "linpan",
  "password": "你的密码",
  "data": {
    "project": "main",
    "name": "车间1/1号机/温度",
    "time_diff": "src",
    "time": "2026-08-14 23:59:59",
    "after": false,
    "limit": 50,
    "offset": 0
  }
}

字段	说明
project	项目名，一般为 main
name	数据点名
time_diff	时间粒度，见下表
time	查询基准时刻，格式 YYYY-MM-DD HH:mm:ss；留空表示以当前时间为基准
after	false = 查基准时刻之前的数据（往历史翻），true = 查之后的
limit	返回行数
offset	从第几行开始，用于翻页

4.4.2 时间粒度 time_diff

取值	含义	返回内容
src	原始值	按存盘记录的逐条数据
var_hours 或 hour	时统计	每小时的最大值 / 最小值 / 均值
var_days 或 day	天统计	每天的最大值 / 最小值 / 均值
var_months 或 month	月统计	每月的最大值 / 最小值 / 均值

可用的粒度取决于该点的存盘方式：

• 瞬时型（变化 / 每分钟存盘）→ 原始值 + 时 / 天 / 月统计都可查
• 瞬时型（每小时存盘）→ 原始值 + 天 / 月统计
• 瞬时型（每天存盘）→ 原始值 + 月统计
• 累积型 → 只有原始值，没有统计粒度

请求了该存盘方式不支持的粒度时会返回 noMore。

4.4.3 响应

{
  "cmdreq": "ok",
  "data": [ ... ]
}

src 粒度每行是时间 + 数据值；统计粒度每行是时间 + 最大值 + 最小值 + 均值。

没有更多数据时返回 {"cmdreq":"noMore"}，翻页时以此作为结束条件。

4.4.4 翻页拉取一段时间的数据

服务器接口是「以某个时刻为基准，往前/往后取 N 条」，不是「给定起止时间取全部」。要拉一整段时间，做法是：

1. 把 time 设为区间的结束时刻，after 设为 false
2. offset 从 0 开始，每次加 limit
3. 直到返回 noMore，或读到的时间已早于区间开始时刻就停止

import requests

URL = "http://192.168.1.100/web"
AUTH = {"username": "linpan", "password": "你的密码"}

def fetch_history(name, end_time, limit=200, max_rows=5000):
    rows, offset = [], 0
    while len(rows) < max_rows:
        r = requests.post(URL, json={
            "cmd": "data_hisload_list", **AUTH,
            "data": {"project": "main", "name": name, "time_diff": "src",
                     "time": end_time, "after": False,
                     "limit": limit, "offset": offset}
        }).json()
        if r.get("cmdreq") != "ok":
            break                      # noMore 或出错，结束
        batch = r.get("data") or []
        if not batch:
            break
        rows += batch
        offset += limit
    return rows

print(len(fetch_history("车间1/1号机/温度", "2026-08-14 23:59:59")))

4.4.5 存盘方式相关接口

读某个点当前的存盘方式：

{ "cmd": "real_get_mode", "username": "...", "password": "...",
  "project": "main", "name": "车间1/1号机/温度" }

设置存盘方式：

{ "cmd": "real_set_mode", "username": "...", "password": "...",
  "project": "main", "name": "车间1/1号机/温度", "mode": "瞬时型每分钟存盘" }

批量给新上报的数据点设存盘方式时用这个接口，比在页面上逐点设置效率更高。

4.4.6 注意

• 存盘方式改了只影响之后的数据，之前没存盘的时间段无法补齐
• 历史数据量大时不要一次请求数万行，应按 limit 分页获取
• 数据点改名（real_replace）会把历史数据一起迁移，不会丢失

---