传感器实时数据

接口说明

获取指定设备最近一次上报的传感器数据。

返回的是一个数组，每项对应一个传感器读数（空气温度、空气湿度、二氧化碳、土壤温度……）。每项都带 factor（因子缩写）、value（物理值）、unit（单位）与 dateTime（采集时间）。

注意域名

本接口在实时与控制域名 mqtt.iot.auto-control.com.cn 下，不是业务域名 yunshangwenshi.auto-control.com.cn。

请求地址

text

GET https://mqtt.iot.auto-control.com.cn/api/sensor-data

请求方法

GET

请求参数

参数名	类型	必填	说明	示例
`deviceCode`	String	是	设备编码，取自设备列表的 `code` 字段	`0010202606040002`

传错设备码不会报错，只会返回空数组

实测：传一个不存在的设备码，接口返回 code: 200 + data: []，不报错。

因此「返回空数组」不能证明接口调用成功，请先用设备列表核对设备码。

请求头

请求头	值	必填
`Authorization`	`Bearer <token>`	是

返回字段

顶层

字段名	类型	说明	示例
`code`	Int	状态码，`200` 为成功	`200`
`data`	Array	传感器读数数组	`[ {...} ]`
`message`	String	提示信息，成功时为 `SuccessCode`	`SuccessCode`
`device_timer`	String	设备时钟（设备本地时间，`yyyy-MM-dd HH:mm:ss`）	`2026-09-15 17:57:00`

device_timer 的用途

这是设备自身的时钟，与每条读数的 dateTime（数据采集时间）是两个概念。

可以用它判断设备时钟是否准确 —— 若 device_timer 与 dateTime 相差过大，说明设备时钟有偏差，需要校时。

传感器读数（`data[]`）

字段名	类型	说明	示例
`name`	String	传感器名称（中文）	`空气温度`
`order`	Int	同类传感器的序号	`0`
`factor`	String	传感器类型英文缩写，见因子对照表	`atc`
`value`	Number	物理值（已按因子换算）	`26.7`
`unit`	String	单位	`℃`
`dateTime`	String	该读数的采集时间	`2026-09-15 17:59:14`
`originValue`	Number	设备上报的原始计数	`583`
`isValid`	String	是否有效：`0` 无效 / `1` 有效	`1`
`isBreakdown`	String	是否故障：`0` 无故障 / `1` 故障	`0`
`isTarget`	String	是否是目标值：`0` 不是 / `1` 是	`0`
`isWeatherStation`	String	是否气象站：`0` 室内 / `1` 室外	`0`
`sensorType`	String	传感器类型序号（数字字符串）	`1`

value 异常值的判断

同一因子在不同设备上单位可能不同（例如 atc 在施肥机设备上返回过 1114.2℃）。 请结合 isValid / isBreakdown 判断数据可用性，不要只看数值本身。

实测的因子与单位

`factor`	`name`	实测 `unit`	出现的设备类型
`atc`	空气温度	`℃`	所有
`ahc`	空气湿度	`%`	控制器
`stc`	土壤温度	`℃`	控制器
`swc`	土壤湿度	`%`	控制器
`co2`	二氧化碳	`PPM`	控制器
`light`	光亮度	`klux`	控制器
`lp`	液位	`m`	施肥机（多路，用 `order` 区分，`1`~`4` 号）
`ecfii`	EC 注肥强度	`%`	施肥机
`phfii`	PH 注肥强度	`%`	施肥机

单位的大小写不统一

同一个因子（light）在本接口返回 klux（小写 k），在历史数据接口返回 Klux（大写 K）。

不要把单位当作枚举值做精确匹配；需要比较时请忽略大小写。

请求示例

curl

bash

curl 'https://mqtt.iot.auto-control.com.cn/api/sensor-data?deviceCode=0010202606040002' \
  -H "Authorization: Bearer <token>"

HTTP 报文

http

GET /api/sensor-data?deviceCode=0010202606040002 HTTP/1.1
Host: mqtt.iot.auto-control.com.cn
Authorization: Bearer <token>
Accept: application/json

Python

python

import requests

RT_HOST = "https://mqtt.iot.auto-control.com.cn"

FACTOR_CN = {
    "atc": "空气温度", "ahc": "空气湿度",
    "stc": "土壤温度", "swc": "土壤湿度",
    "co2": "二氧化碳", "light": "光照",
    "lp": "液位", "ecfii": "EC注肥强度", "phfii": "PH注肥强度",
}


def get_realtime(token: str, device_code: str):
    """读取设备最近一次上报。返回 (读数列表, 设备时钟)。"""
    resp = requests.get(
        f"{RT_HOST}/api/sensor-data",
        params={"deviceCode": device_code},
        headers={"Authorization": f"Bearer {token}"},
        timeout=15,
    )
    body = resp.json()
    if body.get("code") != 200:
        raise RuntimeError(f"查询失败: {body.get('code')} {body.get('message')}")

    readings = []
    for item in body.get("data") or []:
        # 过滤无效 / 故障 / 目标值
        if item.get("isValid") != "1":        continue
        if item.get("isBreakdown") != "0":    continue
        if item.get("isTarget") == "1":       continue
        readings.append(item)

    return readings, body.get("device_timer")


if __name__ == "__main__":
    readings, timer = get_realtime("<你的 token>", "0010202606040002")
    print(f"设备时钟: {timer}")
    for r in readings:
        cn = FACTOR_CN.get(r["factor"], r["factor"])
        # 多路因子（如液位）用 order 区分
        idx = f'#{r["order"]}' if r.get("order") else ""
        print(f'{cn}{idx}: {r["value"]} {r["unit"]}  采集于 {r["dateTime"]}')

返回示例

json

{
  "code": 200,
  "data": [
    {
      "name": "空气温度",
      "order": 0,
      "isBreakdown": "0",
      "isTarget": "0",
      "isValid": "1",
      "isWeatherStation": "0",
      "originValue": 583,
      "value": 18.3,
      "unit": "℃",
      "factor": "atc",
      "dateTime": "2026-09-15 17:59:03",
      "sensorType": "1"
    },
    {
      "name": "空气湿度",
      "order": 0,
      "isBreakdown": "0",
      "isTarget": "0",
      "isValid": "1",
      "isWeatherStation": "0",
      "originValue": 480,
      "value": 48.0,
      "unit": "%",
      "factor": "ahc",
      "dateTime": "2026-09-15 17:59:03",
      "sensorType": "2"
    },
    {
      "name": "光亮度",
      "order": 0,
      "isBreakdown": "0",
      "isTarget": "0",
      "isValid": "1",
      "isWeatherStation": "1",
      "originValue": 3,
      "value": 0.3,
      "unit": "klux",
      "factor": "light",
      "dateTime": "2026-09-15 17:59:03",
      "sensorType": "4"
    }
  ],
  "message": "SuccessCode",
  "device_timer": "2026-09-15 17:57:00"
}

多路因子的返回形态（施肥机的液位，用 order 区分第几路）：

json

{
  "code": 200,
  "data": [
    { "name": "液位", "order": 1, "factor": "lp", "value": 3.33, "unit": "m", "sensorType": "60",
      "isValid": "1", "isBreakdown": "0", "isTarget": "0", "isWeatherStation": "0",
      "originValue": 333, "dateTime": "2026-09-15 17:59:13" },
    { "name": "液位", "order": 2, "factor": "lp", "value": 4.44, "unit": "m", "sensorType": "60",
      "isValid": "1", "isBreakdown": "0", "isTarget": "0", "isWeatherStation": "0",
      "originValue": 444, "dateTime": "2026-09-15 17:59:13" }
  ],
  "message": "SuccessCode",
  "device_timer": "2026-09-15 17:59:00"
}

注意事项

返回的是「最近一次上报」，不是「此刻的实时值」

设备按自己的周期上报（实测部分控制器约 5 分钟一次）。如果设备 5 分钟上报一次，你在第 3 分钟调用拿到的就是 3 分钟前的数据。

请用每项的 dateTime 判断数据新鲜度，不要假设它是秒级实时值。

同名因子可能有多路，请用 order 区分

同一因子可能出现多条（如液位的 1#/2#/3#/4#）。 请用 name + order（或 sensorType）作为唯一键，不要只用 factor。

过滤三类「不是实测值」的读数

对接业务系统时建议至少过滤掉：

isValid != "1" —— 无效读数
isBreakdown != "0" —— 传感器故障
isTarget == "1" —— 目标值（设定值），不是实测值

高频调用会拿到重复数据

重复调用只会返回同一条数据。需要更高实时性时，建议改用 WebSocket 推送，或把轮询周期设为 ≥ 30 秒。

数据为空怎么办

用单设备在线状态确认设备在线（data.status 为 1）
核对 deviceCode 取自 /api/device 的 code
设备刚恢复在线时，需要等一个上报周期

下一步

→ 历史数据：查某个时间段的历史读数
→ 聚合数据（曲线）：按小时/天/月聚合

传感器实时数据 ​

接口说明 ​

请求地址 ​

请求方法 ​

请求参数 ​

请求头 ​

返回字段 ​

顶层 ​

传感器读数（data[]） ​

实测的因子与单位 ​

请求示例 ​

curl ​

HTTP 报文 ​

Python ​

返回示例 ​

注意事项 ​

下一步 ​