数据云控对比图实战教程：用云递数据API搭建可视化对比面板

数据云控对比图总对不上？先看这个最小可运行例子

先说个扎心的现象：很多人做数据云控对比图，最后发现图上的数和实际数据对不上，排查半天，问题往往不在画图那一步，而在数据怎么进、怎么被取走。对比图这东西，本质是"同一时间点上多个数据集的快照并排展示"，只要有一个数据集读重了或者读漏了，图就废了。

所以别急着上框架。先用最小可运行的例子把链路跑通——推送、读取、打印。下面这段 curl，两台"设备"往同一个数据名里写值，然后按写入顺序读回来：

# 推送：设备A写一条
curl -X POST http://你的域名/api/push.php \
  -H "Content-Type: application/json" \
  -d '{"api_key":"你的APIKey","dataset":"sensor_A","data":{"temp":23.5,"ts":1710000000}}'

# 推送：设备B写一条
curl -X POST http://你的域名/api/push.php \
  -H "Content-Type: application/json" \
  -d '{"api_key":"你的APIKey","dataset":"sensor_B","data":{"temp":24.1,"ts":1710000000}}'

# 读取：按写入顺序取，取走即标记已读
curl -X POST http://你的域名/api/pull.php \
  -H "Content-Type: application/json" \
  -d '{"api_key":"你的APIKey","dataset":"sensor_A","page":1,"size":10}'

能跑通这三条，对比图的地基就有了。注意这里的 key 是 dataset，也就是"数据名"，它是对比图的天然分组维度——你有几个数据源，就开几个数据名，读的时候按名字分别拉，再并排画。很多人一开始把所有数据塞进一个数据名，结果画图时还得自己按字段过滤，纯属给自己找活干。

云递数据的推送与读取原理：队列式消费与哈希去重

云递数据的模型很简单，就两个接口：push.php 写，pull.php 读。但它的读不是"查"，是"消费"——按写入顺序 FIFO 取，取走即标记已读，不会重复下发。这点和传统数据库查询完全不一样，也是对比图能不能对上的关键。

打个比方：它更像一条传送带，而不是一个仓库货架。你从货架上拿东西，拿十次还是那件；但从传送带上拿走，它就走了。所以做对比图时，如果你是"实时刷新看当前状态"的用法，要清楚每次 pull 都会消耗掉数据。想反复看同一批数据，请自己在本地缓存或者落库。

另一个容易忽略的是哈希去重：写入时系统会自动规范化数据并计算哈希，内容完全相同只保留第一条。这意味着你反复推同一份 JSON，不会把队列撑爆，也不会让对比图出现一排一模一样的柱子。写进去的时候：

<?php
// push.php 的兼容写法：老程序可以直接发纯文本
$url = "http://你的域名/api/push.php?api_key=你的APIKey&dataset=legacy_log";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, "2024-03-10 12:00 温度=23.5");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resp = curl_exec($ch);
curl_close($ch);
echo $resp;

这种 ?api_key=xxx&dataset=yyy 加纯文本体的写法，是给易语言、按键精灵这类不爱拼 JSON 的老程序准备的。密钥也可以走 X-Api-Key 请求头，看你的工具链哪种顺手。

分步实现：推送数据、读取数据、绘制对比图

下面用 Python 走一遍完整流程。目标：两个数据名各推一组温度数据，读回来后画成并排对比图。先推：

import requests, json

BASE = "http://你的域名"
KEY  = "你的APIKey"

def push(dataset, payload):
    r = requests.post(f"{BASE}/api/push.php",
        headers={"X-Api-Key": KEY},
        json={"dataset": dataset, "data": payload})
    return r.json()

# 模拟两台设备，各推3个时间点
for i, t in enumerate([23.5, 23.8, 24.2]):
    push("sensor_A", {"temp": t, "ts": 1710000000 + i*60})
for i, t in enumerate([24.1, 24.0, 23.6]):
    push("sensor_B", {"temp": t, "ts": 1710000000 + i*60})

print("推送完成")

再读。注意 page 和 size 是分页参数，dataset 指定数据名，取走即标记已读：

import matplotlib.pyplot as plt

def pull(dataset, page=1, size=50):
    r = requests.post(f"{BASE}/api/pull.php",
        headers={"X-Api-Key": KEY},
        json={"dataset": dataset, "page": page, "size": size})
    return r.json()

def to_series(dataset):
    items = pull(dataset).get("data", [])
    temps = [it["data"]["temp"] for it in items]
    ts    = [it["data"]["ts"]   for it in items]
    return ts, temps

ts_a, temp_a = to_series("sensor_A")
ts_b, temp_b = to_series("sensor_B")

# 并排对比图
x = range(len(temp_a))
plt.plot(x, temp_a, marker="o", label="sensor_A")
plt.plot(x, temp_b, marker="s", label="sensor_B")
plt.xlabel("采样点")
plt.ylabel("温度 ℃")
plt.title("数据云控对比图")
plt.legend()
plt.savefig("compare.png")
print("对比图已生成 compare.png")

关键点：两个数据名分别 pull，各自返回自己的队列，天然对齐。如果你的两个数据集采样时间戳不完全一致，建议在绘图前按 ts 做一次归并，别硬按数组下标对齐，否则对比图会"错位"，看起来像数据源出问题，其实是画图逻辑的锅。控制台里能直接看到每个数据名的条数、容量、已读状态，先在那里核对数量，再去跑绘图脚本，能省掉大半调试时间。

运行效果：控制台可视化与对比图展示

数据推上去以后，云递数据控制台会以可视化的方式列出每个数据名的条数、占用容量和已读状态。这一步别跳过——它是你排查"对比图总对不上"的第一现场。如果 sensor_A 显示 3 条、sensor_B 显示 3 条，但你脚本里画出来是 2 条和 3 条，那基本可以断定是某次 pull 把数据取走没保存。

对比图本身没什么玄学，就是两条序列并排。下面这张表是常见的几种对比场景和对应的数据组织方式，照着选就行：

控制台里还能对数据做下载、编辑、清空、删除。做对比图之前，建议先把要用的数据下载一份留底，因为队列式消费一旦取走就标记已读，回头想复现图表就没原料了。

常见坑与注意事项

坑一：把 pull 当成"查询"反复调用。它不是查询，是消费。想反复画图，自己存一份。

坑二：忽略哈希去重。你推了两条"看起来不同"的数据，但规范化后哈希一致，第二条就被丢了，对比图里少一根柱子。检查字段顺序、空格、数字精度这些细节。

坑三：对比图时间轴没对齐。两组数据的采样节奏不一样时，硬按顺序画必然错位，按时间戳归并才靠谱。

坑四：密钥写死在客户端。API 密钥鉴权是有的，但密钥泄露等于数据被人随便推读。硬件设备接入时尽量走内网或做转发。

坑五：会员到期后接口暂停。数据不会被删，但推送和读取会停，续费即恢复。做长期采集的项目，记得留意会员状态，别采着采着断了还以为程序挂了。

常见问题

云递数据的数据云控对比图能实时更新吗？

可以做到接近实时，取决于你的刷新频率。因为 push 和 pull 都是普通 HTTP 接口，你写个定时任务每隔几秒推一次、拉一次再重绘，就能滚动更新。但要注意 pull 是队列式消费，每次拉都会把数据标记已读，所以"实时对比图"通常需要自己在本地留存一份历史，否则只能看到当前这一次拉到的数据。

推送数据时内容完全相同会被重复存储吗？

不会。写入时系统会自动规范化并计算哈希，内容完全相同只保留第一条。这个机制能避免重复推送把队列撑爆，但反过来也意味着你不能靠"推两次一样的"来制造两条记录做对比，需要让两次数据有实质差异。

读取接口支持分页和按数据名读取吗？

支持。pull.php 可以带上 dataset 指定数据名，也可以带 page 和 size 做分页。按写入顺序 FIFO 读取，取走即标记已读，不会重复下发。分页和按数据名组合使用，是做多数据源对比图最常用的方式。

会员到期后数据会被删除吗？

不会。会员到期后数据保留不删除，只是暂停推送和读取，续费后即恢复。新用户注册赠送 3 天会员免费试用，正式会员是月卡 19 元、年卡 99 元，卡密充值，多张可叠加、到期顺延。所以到期不必急着导出抢救，续上就行。

ESP8266等硬件设备如何接入云递数据？

只要设备能发 HTTP 请求就能接入，ESP8266/ESP32 用 HTTPClient POST 到 http://你的域名/api/push.php，把 api_key、dataset、data 拼成 JSON 发出去即可；读取同理请求 pull.php。硬件端算力有限的话，用 ?api_key=xxx&dataset=yyy 加纯文本体的兼容写法最省事，不用拼复杂 JSON。平台是 Nginx + PHP + MySQL，也支持私有化部署到自己的内网或公网服务器，数据自主可控。

开始使用

本文的代码示例都可以直接在云递数据上运行：注册后即可获得专属 APIKey，在 开发文档 中查看推送、读取接口的完整说明；需要长期使用可以在 会员中心 用卡密开通月卡或年卡；更多实战内容可以浏览技术博客的其他文章。