环境与域名说明

平台对外提供两个调用域名，用途不同 —— 混用是最容易踩的坑。本页把每个域名的用途、对应哪些接口一次说清楚。

域名用途对照表

域名	用途	承载接口	是否需要 `Authorization`
`yunshangwenshi.auto-control.com.cn`	业务查询主入口 — 登录、站点、设备、历史与聚合数据、视频、全量在线状态	`/api/account/sign-in` `/api/station` `/api/device` `/api/weather-data/avg` `/api/weather-data/list` `/api/video-data/list` `/api/control/mqtt`	是（登录接口除外）
`mqtt.iot.auto-control.com.cn`	实时与控制入口 — 传感器实时数据、在线状态、控制参数读写、控制指令下发	`/api/sensor-data` `/api/mqtt-client-status` `/api/device_status` `/api/get-value` `/api/set-value/flush` `/api/set-value`	是
`mqtt.iot.auto-control.com.cn`（WebSocket）	实时推送入口 — 长连接推送控制参数与气象站数据	`/ws/device-status` `/ws/set-value` `/ws/sensor-data/weather-station-data/{deviceCode}`	是（携带方式见 WebSocket 接口）

两个域名的鉴权行为不一致

实测：

域名	不带 `Authorization` 时的行为
业务域名	HTTP 403 `{"error":"Forbidden","message":"Access Denied"}`
实时控制域名	正常返回数据（当前不校验凭证）

请始终按规范携带凭证。 规范实现可以保证平台开启校验后你的系统无需改动。详见使用凭证。

协议与端口

项	值
HTTP 协议	HTTPS（推荐，对外只暴露 443）
端口	443（HTTPS）、80（HTTP，建议仅用于跳转）
WebSocket 协议	`ws://` 或 `wss://`（生产建议 `wss://`）
字符编码	UTF-8
请求体格式	`application/json`（`POST` 接口）

各接口归属速查

text

POST   https://yunshangwenshi.auto-control.com.cn/api/account/sign-in
GET    https://yunshangwenshi.auto-control.com.cn/api/station
GET    https://yunshangwenshi.auto-control.com.cn/api/device
GET    https://yunshangwenshi.auto-control.com.cn/api/weather-data/avg
GET    https://yunshangwenshi.auto-control.com.cn/api/weather-data/list
GET    https://yunshangwenshi.auto-control.com.cn/api/video-data/list
GET    https://yunshangwenshi.auto-control.com.cn/api/control/mqtt

GET    https://mqtt.iot.auto-control.com.cn/api/sensor-data
GET    https://mqtt.iot.auto-control.com.cn/api/mqtt-client-status
GET    https://mqtt.iot.auto-control.com.cn/api/device_status
GET    https://mqtt.iot.auto-control.com.cn/api/get-value
GET    https://mqtt.iot.auto-control.com.cn/api/set-value/flush
POST   https://mqtt.iot.auto-control.com.cn/api/set-value

WS     ws://mqtt.iot.auto-control.com.cn/ws/device-status
WS     ws://mqtt.iot.auto-control.com.cn/ws/set-value
WS     ws://mqtt.iot.auto-control.com.cn/ws/sensor-data/weather-station-data/{deviceCode}

在代码里怎么组织

建议在配置里只写 两个 base URL，不要在每个调用点硬编码域名：

yaml

# config.yaml
iot:
  base-url:
    business: https://yunshangwenshi.auto-control.com.cn   # 业务查询
    realtime: https://mqtt.iot.auto-control.com.cn          # 实时与控制

java

// Java 版本
public final class IotEndpoint {
    public static final String BUSINESS = "https://yunshangwenshi.auto-control.com.cn";
    public static final String REALTIME = "https://mqtt.iot.auto-control.com.cn";
}

网络与出口要求

项	要求
出网方向	你的服务器/网关需要能主动访问上述域名的 443 端口
IP 白名单	如需白名单，请联系运营方登记你的出口 IP（暂未定义具体策略，请与运营方确认）
代理	若走企业代理，需允许 `CONNECT` 到 443，并允许 WebSocket 升级头 `Upgrade: websocket`
证书	使用标准公有 CA 证书，客户端无需额外导入根证书
超时建议	连接超时 5s / 读取超时 15s；控制类接口建议读取超时放宽到 30s

测试环境与生产环境

平台暂未说明独立的测试环境

接口文档没有区分测试/生产两套域名，文档中所有示例地址均为同一套域名。如需测试环境或测试账号，请直接与平台运营方确认，不要自行推测测试域名。

联调阶段的替代做法：

向运营方申请只读测试账号，限定可见的站点范围
联调控制类接口时，指定一台现场无生产任务的设备作为测试设备
所有写操作接口（/api/set-value）保持在人工确认后再调用

下一步

获取访问凭证 — 拿到 token
通用说明 — 统一返回格式与时间戳约定

环境与域名说明 ​

域名用途对照表 ​

协议与端口 ​

各接口归属速查 ​

网络与出口要求 ​

测试环境与生产环境 ​