设备列表

接口说明

获取当前账号名下的全部设备，可按数据类型过滤。

返回的 code（设备编码）是实时数据、控制参数、控制指令等接口的核心入参； id（设备 ID）用于历史数据、聚合曲线、视频等查询类接口。请把两个值都存下来。

请求地址

GET https://yunshangwenshi.auto-control.com.cn/api/device

请求方法

GET

请求参数

参数名	类型	必填	说明	示例
dataType	String	否	数据类型过滤，取值 TEXT / STREAM。不传则返回全部	TEXT

TEXT / STREAM 的实际语义与直觉不同

实测一个账号的 14 台设备：

调用	返回条数
不传 dataType	14
dataType=TEXT	13
dataType=STREAM	3

13 + 3 = 16 > 14 —— 两个集合不互斥：有 2 台设备（视频类设备）同时出现在两个结果里。

而且 TEXT 的结果里不只有控制器，还包括视频类设备。

结论：

• dataType 不是「设备大类的互斥划分」，而是**「是否具备某种能力」的标记位**
• 想要「全部设备」就不要传 dataType
• 不要假设 TEXT + STREAM 等于全量，也不要用它来做去重

请求头

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

返回字段

顶层为风格 A 的完整包装，data 为设备对象数组。

设备对象字段

字段名	类型	说明	示例
id	Int	设备 ID，用于 deviceId 类参数	20612
code	String	设备编码，用于 deviceCode 类参数	0010202606040002
name	String	设备名称	吴琼触摸屏测试
deviceTypeId	String	设备类型编码，见 设备类型映射表	C001
deviceTypeName	String	设备类型名称	日光温室控制器
stationId	Int	所属站点 ID	12115
stationName	String	所属站点名称	吴琼触摸屏测试
customerId	Long	所属客户 ID	1667372262
sortOrder	Int	排序权重	1
deviceBrand	String	设备品牌，无值时为空串	海康威视
hls	String	视频流地址；非视频设备为空串	https://gbs.auto-control.com.cn/proxy/...
channel	Int	通道号	1
number	Int	编号	0
tag	String	标签，通常为空串	""
prefix	String	前缀，通常为空串	""
version	Int	版本号	1
type	String	扩展类型，通常为空串	""

不同设备的字段可能不同

上表是某账号全部设备的字段并集。单台设备不一定包含全部字段 （例如非视频设备的 hls 为空串、deviceBrand 可能缺失）。 反序列化时请按可选字段处理，不要用强类型 POJO 直接映射。

请求示例

curl

# 全部设备
curl 'https://yunshangwenshi.auto-control.com.cn/api/device' \
  -H "Authorization: Bearer <token>"

# 仅控制器
curl 'https://yunshangwenshi.auto-control.com.cn/api/device?dataType=TEXT' \
  -H "Authorization: Bearer <token>"

HTTP 报文

GET /api/device?dataType=TEXT HTTP/1.1
Host: yunshangwenshi.auto-control.com.cn
Authorization: Bearer <token>
Accept: application/json

Python

import requests

BIZ_HOST = "https://yunshangwenshi.auto-control.com.cn"


def list_devices(token: str, data_type: str | None = None):
    """获取设备列表。data_type 可为 'TEXT' / 'STREAM' / None（推荐用 None 取全量）。"""
    params = {"dataType": data_type} if data_type else {}
    resp = requests.get(
        f"{BIZ_HOST}/api/device",
        params=params,
        headers={"Authorization": f"Bearer {token}"},
        timeout=15,
    )
    body = resp.json()
    if body.get("code") != 200:
        raise RuntimeError(f"查询失败: {body.get('code')} {body.get('message')}")

    devices = body.get("data") or []
    by_station: dict[int, list[str]] = {}
    for d in devices:
        by_station.setdefault(d["stationId"], []).append(d["code"])
    return devices, by_station


if __name__ == "__main__":
    devices, _ = list_devices("<你的 token>")
    for d in devices[:5]:
        print(f'{d["id"]:>6}  {d["code"]:<22} {d["name"]:<16} {d["deviceTypeName"]}')

返回示例

{
  "requestId": "4a994407-96e3-4072-8c9c-744ef9616d2a",
  "code": 200,
  "data": [
    {
      "id": 20612,
      "customerId": 1667372262,
      "sortOrder": 1,
      "code": "0010202606040002",
      "name": "吴琼触摸屏测试",
      "deviceTypeId": "C001",
      "deviceTypeName": "日光温室控制器",
      "stationId": 12115,
      "stationName": "吴琼触摸屏测试",
      "deviceBrand": "",
      "hls": "",
      "tag": "",
      "number": 0,
      "channel": 1,
      "prefix": "",
      "version": 1,
      "type": ""
    },
    {
      "id": 9695,
      "customerId": 1667372262,
      "sortOrder": 1,
      "code": "34020000001320000015",
      "name": "摄像机#1",
      "deviceTypeId": "V008",
      "deviceTypeName": "GBS",
      "stationId": 5820,
      "stationName": "海康摄像测试",
      "deviceBrand": "海康威视",
      "hls": "https://gbs.auto-control.com.cn/proxy/sms/local/live/34020000001320000015_34020000001320000015.flv?expired=20251030144809",
      "tag": "",
      "number": 0,
      "channel": 1,
      "prefix": "",
      "version": 1,
      "type": ""
    }
  ],
  "timestamp": 1630550922261,
  "success": true
}

注意事项

id 和 code 用途不同，不要互换

参数	用哪个	出现在哪些接口
deviceId	id（Int）	/api/weather-data/list、/api/weather-data/avg、/api/video-data/list
deviceCode	code（String）	/api/sensor-data、/api/mqtt-client-status、/api/device_status、/api/get-value、/api/set-value*

传错会返回空数据或错误。

设备编码 code 不一定是纯数字

绝大多数控制器的 code 是 16 位数字（如 0010202606040002），以 0 开头， 反序列化时务必按字符串处理，转成数字会丢失前导 0。

但部分设备编码含字母，例如：

• IM_7M02800PAGE54CC（虫情监测）
• BK0F3CBPHAC3A70（大华云联）
• 34020000001320000015（GBS 摄像机）

所以千万不要对 code 做数字类型的假设。

本接口没有分页

一次性返回全部设备。设备多的账号请自行评估数据量， 并在本地建立缓存（设备清单变更频率低）。

建议的本地设备映射表

CREATE TABLE iot_device_map (
  device_id        BIGINT PRIMARY KEY,           -- 接口返回的 id
  device_code      VARCHAR(64) NOT NULL UNIQUE,  -- 接口返回的 code（字符串！含字母）
  device_name      VARCHAR(128),
  device_type_id   VARCHAR(32),                  -- 如 C001
  device_type_name VARCHAR(128),                 -- 如 日光温室控制器
  station_id       BIGINT,
  station_name     VARCHAR(128),
  updated_at       TIMESTAMP
);

下一步

• → 传感器实时数据：用 deviceCode 读实时数据
• → 设备在线状态：判断设备是否在线