「IoT 设备模拟」是数据鱼API提供的物联网联调辅助接口,Base 路径 /api/iot-sim,共 4 个端点。它不连接真实硬件,而是按调用方给定的参数产出模拟数据:一条传感器读数、一份 MQTT 主题的合法性判定、一组心跳时间戳的分析结果。适合在设备尚未到货、网关尚未部署、或者需要构造边界数据时,让上层界面与数据管道先跑起来。
物联网项目的前端和规则引擎通常比硬件更早成形。界面上的仪表盘需要一条带单位、带时间戳的读数才有东西可渲染;消息路由需要一批结构正确的主题才能验证订阅规则;离线判定逻辑需要一段间隔不均的心跳序列才测得出抖动。这些输入如果只能等真机联调,整个开发节奏就会被硬件排期绑住。
接口的四个端点各管一件事:sensor 生成读数,topic 解析并校验主题,heartbeat 分析时间戳序列,ping 报告存活。所有端点为同步调用,返回 JSON,不建立长连接,也不推送消息——它模拟的是设备产生的数据形态,不是 MQTT broker 本身。数据鱼API把这个接口归在开发工具类,供测试与演示使用。
方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
GET | /api/iot-sim/ping | 健康检查,返回服务状态 | 否 |
GET | /api/iot-sim/sensor | 生成一条指定类型与区间的模拟传感器读数 | 是 |
GET | /api/iot-sim/topic | 校验 MQTT 主题并拆分层级、识别通配符 | 是 |
POST | /api/iot-sim/heartbeat | 分析一组心跳时间戳的间隔特征 | 是 |
X-API-Key 请求头或 ?api_key= 查询参数;缺失返回 4011,无效返回 4013。heartbeat 的 timestamps 是数组,必须用 POST 的 JSON body 提交,放在 query 里会被判为类型错误并返回 4002。{"code": 0, "msg": "success", "data": {...}}。heartbeat 对参数类型有强校验,错误信息会明确指出期望类型与实际类型;其余端点只做数值强转,不做取值域检查。按类型与数值区间生成一条带时间戳的模拟读数,用于填充仪表盘或测试阈值规则。
参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
type | string | 否 | temperature | 传感器类型标识,原样写入响应的 sensor_type |
min | number | 否 | 0 | 随机取值下界,按浮点解析 |
max | number | 否 | 100 | 随机取值上界,按浮点解析 |
返回字段:sensor_type 回显请求的类型;value 为落在区间内的数值;unit 为对应单位,类型无法识别时为 unknown;timestamp 为 Unix 秒级时间戳;iso_date 为带时区偏移的 ISO 8601 时间。
GET /api/iot-sim/sensor?type=temperature&min=18&max=26三次连续调用会得到三个不同的 value,除非区间上下界相等。数值不会越过给定区间,但接口不保证分布形态,也不做趋势或周期模拟。
判断一个主题字符串是否合法、是否含通配符,并按分隔符拆出层级。
参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
topic | string | 否 | home/living-room/temp | 待校验的主题字符串,按斜杠分层 |
返回字段:topic 为回显的主题;is_valid 为合法性布尔值;has_wildcards 表示是否包含 + 或 #;levels 为按 / 拆分后的层级数组。
GET /api/iot-sim/topic?topic=sensors/room1/temperature上例返回三个层级,is_valid 为 true,has_wildcards 为 false。验证订阅规则时,把带 + 与 # 的主题分别提交一次,即可确认服务端的通配符识别口径与你的路由实现是否一致。
接收一组时间戳,输出间隔特征,用于验证离线判定与抖动告警的阈值设置。
参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
timestamps | array | 否 | 空数组 | Unix 时间戳数组,必须通过 JSON body 提交 |
POST /api/iot-sim/heartbeat
Content-Type: application/json
{"timestamps": [1794508216, 1794508276, 1794508331, 1794508391]}数组元素按时间先后排列更利于阅读结果;传入空数组时返回空分析结果而不报错。API.md 未列出该端点的返回字段明细,接入时应以实际响应为准,不要按推测字段名写死解析。
无参数,返回 status 为 ok,免鉴权,适合作为探活路径。
sensor 的 value 每次调用重新生成,不可重现;做断言时应校验区间而非具体数值。type 会返回 unit 为 unknown,接口不报错。sensor 的 timestamp 为服务器当前时间的秒级值,iso_date 带 +08:00 时区偏移。topic 不做订阅匹配,只做格式校验与层级拆分;通配符是否可出现在某一层,以 is_valid 的返回为准。heartbeat 的参数必须为数组,字符串会被拒绝并返回 4002;其余三个端点的数值参数按浮点或整数强转。sensor 定时拉取读数,先把仪表盘、曲线图与阈值变色逻辑做完。topic 批量校验待订阅的主题格式,确认路由表里没有拼写错误或多余层级。heartbeat,观察分析结果,再确定超时阈值。heartbeat 的 timestamps 标为 string 且非必填,实际实现要求 array,传字符串直接返回 4002;正确做法是 POST JSON body。sensor_type 为 daily、unit 为 unknown,说明该示例是在传入非常规类型时采集的;默认类型是 temperature。topic 示例中主题为 CNY,与默认值 home/living-room/temp 不同,同样是探测时的入参,不要当成默认行为。sensor 不传参时区间为 0 到 100,与体温、室温等常见量程都不匹配,接入时应显式给定 min 与 max。min 大于 max 时接口不报错,取值行为未定义,调用侧应先保证区间有效。原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。