外观
设备在线状态
平台提供两个在线状态接口，分属不同域名，返回结构也不同：
| 接口 | 域名 | 用途 | 返回 |
|---|---|---|---|
GET /api/mqtt-client-status | mqtt.iot.auto-control.com.cn | 查单台设备是否在线 | data.status：0 离线 / 1 在线 |
GET /api/control/mqtt | yunshangwenshi.auto-control.com.cn | 查名下全部控制器在线状态 | 设备数组，每项带 online |
一、单设备在线状态
接口说明
查询指定设备当前是否与平台保持连接。
请求地址
text
GET https://mqtt.iot.auto-control.com.cn/api/mqtt-client-status1
请求方法
GET
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
deviceCode | String | 是 | 设备编码 | 0010202606040002 |
请求头
| 请求头 | 值 | 必填 |
|---|---|---|
Authorization | Bearer <token> | 是 |
返回字段
| 字段名 | 类型 | 说明 | 示例 |
|---|---|---|---|
code | Int | 状态码，200 为成功 | 200 |
data.status | Int | 在线状态：0 离线 / 1 在线 | 1 |
data.type | Int | 类型标识 | 1 |
data.version | Int | 接口版本号（在线时才返回） | 2 |
data.description | String | null | 描述（在线时为 null） | null |
data.latest_online_datetime | String | 最近在线时间（字符串） | "" |
message | String | Object | 提示信息，见下方警告 | "SuccessCode" |
message 可能是字符串，也可能是对象
设备在线时 —— message 是字符串：
json
{ "code": 200, "data": { "status": 1, "version": 2, "type": 1, "description": null, "latest_online_datetime": "" }, "message": "SuccessCode" }1
设备查不到（离线/不存在）时 —— message 变成对象，且 data 里少了 version 等字段：
json
{ "code": 200, "data": { "status": 0, "type": 1 }, "message": { "code": "CLIENTID_NOT_FOUND", "message": "Client ID not found" } }1
解析前必须先判断 message 的类型，否则序列化/转换会直接抛异常。
在多数编程语言里，把 message 声明为 String 会在第二种情况下反序列化失败。 建议声明为「字符串或对象」的联合类型（如 Java 的 JsonNode、Python 的 Any）。
设备不存在与设备离线返回相同结构
传一个不存在的设备码，返回的也是 status: 0 + CLIENTID_NOT_FOUND。 无法仅凭本接口区分「设备离线」和「设备不存在」 —— 请先用 设备列表 确认设备码有效。
请求示例
bash
curl 'https://mqtt.iot.auto-control.com.cn/api/mqtt-client-status?deviceCode=0010202606040002' \
-H "Authorization: Bearer <token>"1
2
2
http
GET /api/mqtt-client-status?deviceCode=0010202606040002 HTTP/1.1
Host: mqtt.iot.auto-control.com.cn
Authorization: Bearer <token>1
2
3
2
3
python
import requests
RT_HOST = "https://mqtt.iot.auto-control.com.cn"
def is_online(token: str, device_code: str) -> bool:
resp = requests.get(
f"{RT_HOST}/api/mqtt-client-status",
params={"deviceCode": device_code},
headers={"Authorization": f"Bearer {token}"},
timeout=10,
)
body = resp.json()
if body.get("code") != 200:
raise RuntimeError(f"查询失败: {body.get('code')} {body.get('message')}")
msg = body.get("message")
if isinstance(msg, dict): # 查不到客户端
print(f' {device_code}: {msg.get("code")}')
return False
return body.get("data", {}).get("status") == 11
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
返回示例
在线
json
{
"code": 200,
"data": {
"status": 1,
"version": 2,
"type": 1,
"description": null,
"latest_online_datetime": ""
},
"message": "SuccessCode"
}1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
离线 / 不存在
json
{
"code": 200,
"data": {
"status": 0,
"type": 1
},
"message": {
"code": "CLIENTID_NOT_FOUND",
"message": "Client ID not found"
}
}1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
二、全部控制器在线状态
接口说明
一次性返回当前账号名下全部控制器的在线状态，适合做批量掉线巡检。
请求地址
text
GET https://yunshangwenshi.auto-control.com.cn/api/control/mqtt1
请求方法
GET
请求参数
无。
请求头
| 请求头 | 值 | 必填 |
|---|---|---|
Authorization | Bearer <token> | 是 |
返回字段
风格 A 完整包装，data 为设备数组。 每项的字段与 设备列表 基本一致，额外带一个 online：
| 字段名 | 类型 | 说明 | 示例 |
|---|---|---|---|
data[].id | Int | 设备 ID | 20612 |
data[].code | String | 设备编码 | 0010202606040002 |
data[].name | String | 设备名称 | 吴琼触摸屏测试 |
data[].deviceTypeId | String | 设备类型编码 | C001 |
data[].deviceTypeName | String | 设备类型名称 | 日光温室控制器 |
data[].stationId | Int | 站点 ID | 12115 |
data[].stationName | String | 站点名称 | 吴琼触摸屏测试 |
data[].customerId | Long | 客户 ID | 1667372262 |
data[].deviceBrand | String | 设备品牌 | "" |
data[].hls | String | 视频流地址 | "" |
data[].channel / number / version | Int | 通道号 / 编号 / 版本 | 1 / 0 / 1 |
data[].tag / prefix / type | String | 扩展字段 | "" |
data[].online | Boolean | 在线状态：true 在线 / false 离线 | true |
两个接口的在线状态类型都不一样
| 接口 | 字段 | 类型 | 取值 |
|---|---|---|---|
/api/mqtt-client-status | data.status | Int | 0 / 1 |
/api/control/mqtt | data[].online | Boolean | true / false |
写公共解析函数时别搞混。
请求示例
bash
curl 'https://yunshangwenshi.auto-control.com.cn/api/control/mqtt' \
-H "Authorization: Bearer <token>"1
2
2
python
import requests
BIZ_HOST = "https://yunshangwenshi.auto-control.com.cn"
def list_offline_devices(token: str):
"""返回所有离线设备，用于告警。"""
resp = requests.get(
f"{BIZ_HOST}/api/control/mqtt",
headers={"Authorization": f"Bearer {token}"},
timeout=30,
)
body = resp.json()
if body.get("code") != 200:
raise RuntimeError(f"查询失败: {body.get('code')} {body.get('message')}")
devices = body.get("data") or []
offline = [d for d in devices if not d.get("online")]
print(f"共 {len(devices)} 台控制器，其中 {len(offline)} 台离线")
for d in offline[:10]:
print(f' 离线: {d["stationName"]} / {d["name"]} ({d["code"]})')
return offline1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
返回示例
json
{
"requestId": "aa5d935b-a5ec-4b23-8969-f6be9e21e40c",
"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": "",
"online": true
}
],
"timestamp": 1789466325,
"success": true
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
注意事项
在线 ≠ 数据新鲜
在线只代表连接未断，不代表刚上报过数据。 判断数据新鲜度请看 传感器实时数据 里每项的 dateTime。
巡检建议
- 单设备检查：进设备详情页时调
/api/mqtt-client-status - 批量巡检：定时（建议 5~10 分钟一次）调
/api/control/mqtt，只对离线的做告警 - 不要对全部设备逐个调
/api/mqtt-client-status—— 设备多时会产生大量请求
data 可能为空
账号下没有控制器时，data 会是空数组或 null，请判空后再遍历。