首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API接口详解:IoT 设备模拟

数据鱼API接口详解:IoT 设备模拟

原创
作者头像
用户12862874
发布于 2026-11-21 22:02:52
发布于 2026-11-21 22:02:52
340
举报

接口简介

「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。
  • 参数传递:前三个端点用 GET 加 query 参数;heartbeat 的 timestamps 是数组,必须用 POST 的 JSON body 提交,放在 query 里会被判为类型错误并返回 4002。
  • 响应结构:统一为 {"code": 0, "msg": "success", "data": {...}}。
  • 类型校验:heartbeat 对参数类型有强校验,错误信息会明确指出期望类型与实际类型;其余端点只做数值强转,不做取值域检查。
  • 上游依赖不可用时返回 5031 或 5032,不返回编造数据;本接口为本地计算,正常不会触发。

核心端点详解

传感器读数 sensor

按类型与数值区间生成一条带时间戳的模拟读数,用于填充仪表盘或测试阈值规则。

参数

类型

必填

默认值

说明

type

string

否

temperature

传感器类型标识,原样写入响应的 sensor_type

min

number

否

0

随机取值下界,按浮点解析

max

number

否

100

随机取值上界,按浮点解析

返回字段:sensor_type 回显请求的类型;value 为落在区间内的数值;unit 为对应单位,类型无法识别时为 unknown;timestamp 为 Unix 秒级时间戳;iso_date 为带时区偏移的 ISO 8601 时间。

代码语言:javascript
复制
GET /api/iot-sim/sensor?type=temperature&min=18&max=26

三次连续调用会得到三个不同的 value,除非区间上下界相等。数值不会越过给定区间,但接口不保证分布形态,也不做趋势或周期模拟。

MQTT 主题校验 topic

判断一个主题字符串是否合法、是否含通配符,并按分隔符拆出层级。

参数

类型

必填

默认值

说明

topic

string

否

home/living-room/temp

待校验的主题字符串,按斜杠分层

返回字段:topic 为回显的主题;is_valid 为合法性布尔值;has_wildcards 表示是否包含 + 或 #;levels 为按 / 拆分后的层级数组。

代码语言:javascript
复制
GET /api/iot-sim/topic?topic=sensors/room1/temperature

上例返回三个层级,is_valid 为 true,has_wildcards 为 false。验证订阅规则时,把带 + 与 # 的主题分别提交一次,即可确认服务端的通配符识别口径与你的路由实现是否一致。

心跳分析 heartbeat

接收一组时间戳,输出间隔特征,用于验证离线判定与抖动告警的阈值设置。

参数

类型

必填

默认值

说明

timestamps

array

否

空数组

Unix 时间戳数组,必须通过 JSON body 提交

代码语言:javascript
复制
POST /api/iot-sim/heartbeat
Content-Type: application/json

{"timestamps": [1794508216, 1794508276, 1794508331, 1794508391]}

数组元素按时间先后排列更利于阅读结果;传入空数组时返回空分析结果而不报错。API.md 未列出该端点的返回字段明细,接入时应以实际响应为准,不要按推测字段名写死解析。

健康检查 ping

无参数,返回 status 为 ok,免鉴权,适合作为探活路径。

数据与限制

  • 随机性:sensor 的 value 每次调用重新生成,不可重现;做断言时应校验区间而非具体数值。
  • 单位映射:仅常见类型有单位,未识别的 type 会返回 unit 为 unknown,接口不报错。
  • 时间戳:sensor 的 timestamp 为服务器当前时间的秒级值,iso_date 带 +08:00 时区偏移。
  • topic 不做订阅匹配,只做格式校验与层级拆分;通配符是否可出现在某一层,以 is_valid 的返回为准。
  • heartbeat 的参数必须为数组,字符串会被拒绝并返回 4002;其余三个端点的数值参数按浮点或整数强转。
  • 无状态、无缓存,接口不保存任何模拟数据,也不维护设备注册表。

典型使用场景

  • 前端联调:硬件未到货时,用 sensor 定时拉取读数,先把仪表盘、曲线图与阈值变色逻辑做完。
  • 消息路由测试:用 topic 批量校验待订阅的主题格式,确认路由表里没有拼写错误或多余层级。
  • 离线判定调参:构造间隔递增的心跳序列提交给 heartbeat,观察分析结果,再确定超时阈值。
  • 演示环境:向客户展示系统时用模拟读数替代真机,避免现场网络与设备状态影响演示。

注意事项

  • 文档与实现差异:API.md 把 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 时接口不报错,取值行为未定义,调用侧应先保证区间有效。
  • 数据鱼API的模拟数据只用于开发与演示,不能作为真实设备状态的依据;上线前必须切换到真实数据源。
  • 该接口不建立 MQTT 连接,也不验证 broker 的 ACL 与 QoS 行为,主题合法不等于可订阅。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 传感器读数 sensor
    • MQTT 主题校验 topic
    • 心跳分析 heartbeat
    • 健康检查 ping
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档