IoT API 文档
物联网平台提供完整的 RESTful API，支持设备管理、数据查询、远程控制、规则配置等功能。
产品管理
创建产品
POST /v1/iot/products请求体：
{
"name": "智能温控器",
"category": "环境监控",
"protocol": "mqtt",
"dataFormat": "json",
"description": "支持温湿度监测和远程控制的智能温控器",
"thingModel": {
"properties": [
{
"id": "temperature",
"name": "当前温度",
"dataType": "float",
"accessMode": "r",
"unit": "°C",
"min": -20,
"max": 50
},
{
"id": "targetTemp",
"name": "目标温度",
"dataType": "float",
"accessMode": "rw",
"unit": "°C",
"min": 16,
"max": 30
}
],
"services": [
{
"id": "setSchedule",
"name": "设置定时",
"inputParams": [
{ "id": "time", "name": "时间", "dataType": "string" },
{ "id": "action", "name": "动作", "dataType": "string" }
]
}
],
"events": [
{
"id": "tempAlert",
"name": "温度告警",
"type": "alert",
"outputParams": [
{ "id": "temperature", "dataType": "float" }
]
}
]
}
}响应：
{
"code": 0,
"data": {
"id": "prod_001",
"name": "智能温控器",
"productKey": "a1b2c3d4e5",
"productSecret": "xxxxxxxxxxxxxxxx",
"createdAt": "2024-01-15T10:00:00Z"
}
}获取产品列表
GET /v1/iot/products?page=1&pageSize=20&category=环境监控获取产品详情
GET /v1/iot/products/{productId}更新产品
PUT /v1/iot/products/{productId}删除产品
DELETE /v1/iot/products/{productId}设备管理
注册设备
POST /v1/iot/devices请求体：
{
"productId": "prod_001",
"deviceName": "温控器-001",
"nickname": "会议室温控器",
"description": "3楼大会议室",
"tags": ["3楼", "会议室"],
"location": {
"building": "总部大楼",
"floor": "3F",
"room": "会议室A"
}
}响应：
{
"code": 0,
"data": {
"id": "dev_001",
"deviceName": "温控器-001",
"deviceKey": "device_key_xxx",
"deviceSecret": "device_secret_xxx",
"status": "inactive",
"createdAt": "2024-01-15T10:00:00Z"
}
}批量注册设备
POST /v1/iot/devices/batch请求体：
{
"productId": "prod_001",
"devices": [
{ "deviceName": "温控器-001", "nickname": "1楼大堂" },
{ "deviceName": "温控器-002", "nickname": "2楼办公区" },
{ "deviceName": "温控器-003", "nickname": "3楼会议室" }
]
}获取设备列表
GET /v1/iot/devices?productId=prod_001&status=online&page=1&pageSize=20查询参数：
| 参数 | 类型 | 说明 |
|---|---|---|
| productId | string | 产品 ID |
| status | string | 状态：online/offline/inactive |
| groupId | string | 分组 ID |
| tags | string | 标签，逗号分隔 |
| search | string | 搜索设备名称 |
响应：
{
"code": 0,
"data": {
"items": [
{
"id": "dev_001",
"deviceName": "温控器-001",
"nickname": "会议室温控器",
"productId": "prod_001",
"productName": "智能温控器",
"status": "online",
"lastOnlineTime": "2024-01-15T10:30:00Z",
"properties": {
"temperature": 25.5,
"humidity": 60,
"power": true
}
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 100
}
}
}获取设备详情
GET /v1/iot/devices/{deviceId}获取设备状态
GET /v1/iot/devices/{deviceId}/status响应：
{
"code": 0,
"data": {
"deviceId": "dev_001",
"status": "online",
"lastOnlineTime": "2024-01-15T10:30:00Z",
"uptime": 86400,
"signalStrength": -65,
"firmware": "1.2.0",
"ip": "192.168.1.100"
}
}更新设备
PUT /v1/iot/devices/{deviceId}删除设备
DELETE /v1/iot/devices/{deviceId}启用/禁用设备
POST /v1/iot/devices/{deviceId}/enable
POST /v1/iot/devices/{deviceId}/disable设备属性
获取设备属性
GET /v1/iot/devices/{deviceId}/properties响应：
{
"code": 0,
"data": {
"temperature": {
"value": 25.5,
"timestamp": "2024-01-15T10:30:00Z"
},
"humidity": {
"value": 60,
"timestamp": "2024-01-15T10:30:00Z"
},
"power": {
"value": true,
"timestamp": "2024-01-15T10:25:00Z"
}
}
}设置设备属性
POST /v1/iot/devices/{deviceId}/properties请求体：
{
"targetTemp": 26,
"mode": "cooling",
"fanSpeed": "auto"
}响应：
{
"code": 0,
"data": {
"messageId": "msg_001",
"status": "sent",
"timestamp": "2024-01-15T10:30:00Z"
}
}获取属性历史
GET /v1/iot/devices/{deviceId}/properties/history查询参数：
| 参数 | 类型 | 说明 |
|---|---|---|
| properties | string | 属性 ID，逗号分隔 |
| startTime | string | 开始时间 (ISO 8601) |
| endTime | string | 结束时间 (ISO 8601) |
| interval | string | 聚合间隔：1m/5m/1h/1d |
| aggregation | string | 聚合方式：avg/max/min/sum/count |
示例：
GET /v1/iot/devices/dev_001/properties/history?properties=temperature,humidity&startTime=2024-01-14T00:00:00Z&endTime=2024-01-15T00:00:00Z&interval=1h&aggregation=avg响应：
{
"code": 0,
"data": {
"temperature": [
{ "time": "2024-01-14T00:00:00Z", "value": 24.5 },
{ "time": "2024-01-14T01:00:00Z", "value": 24.2 },
{ "time": "2024-01-14T02:00:00Z", "value": 23.8 }
],
"humidity": [
{ "time": "2024-01-14T00:00:00Z", "value": 55 },
{ "time": "2024-01-14T01:00:00Z", "value": 56 },
{ "time": "2024-01-14T02:00:00Z", "value": 58 }
]
}
}设备控制
调用设备服务
POST /v1/iot/devices/{deviceId}/services/{serviceId}请求体：
{
"params": {
"time": "08:00",
"action": "turnOn",
"temperature": 24
}
}响应：
{
"code": 0,
"data": {
"messageId": "msg_002",
"status": "sent",
"timestamp": "2024-01-15T10:30:00Z"
}
}批量控制设备
POST /v1/iot/devices/batch/control请求体：
{
"deviceIds": ["dev_001", "dev_002", "dev_003"],
"command": {
"type": "property",
"data": {
"power": true,
"targetTemp": 24
}
}
}按分组控制
POST /v1/iot/groups/{groupId}/control请求体：
{
"command": {
"type": "property",
"data": {
"power": false
}
}
}设备事件
获取设备事件
GET /v1/iot/devices/{deviceId}/events查询参数：
| 参数 | 类型 | 说明 |
|---|---|---|
| eventType | string | 事件类型 |
| level | string | 事件级别：info/warning/error |
| startTime | string | 开始时间 |
| endTime | string | 结束时间 |
响应：
{
"code": 0,
"data": {
"items": [
{
"id": "evt_001",
"eventType": "tempAlert",
"level": "warning",
"data": {
"temperature": 38.5,
"threshold": 35
},
"timestamp": "2024-01-15T10:30:00Z"
}
]
}
}设备分组
创建分组
POST /v1/iot/groups请求体：
{
"name": "3楼设备",
"parentId": "group_001",
"description": "3楼所有智能设备"
}获取分组树
GET /v1/iot/groups/tree响应：
{
"code": 0,
"data": [
{
"id": "group_001",
"name": "总部大楼",
"deviceCount": 150,
"children": [
{
"id": "group_002",
"name": "1楼",
"deviceCount": 30,
"children": []
},
{
"id": "group_003",
"name": "2楼",
"deviceCount": 45,
"children": []
}
]
}
]
}添加设备到分组
POST /v1/iot/groups/{groupId}/devices请求体：
{
"deviceIds": ["dev_001", "dev_002", "dev_003"]
}从分组移除设备
DELETE /v1/iot/groups/{groupId}/devices请求体：
{
"deviceIds": ["dev_001"]
}规则引擎
创建规则
POST /v1/iot/rules请求体：
{
"name": "高温告警",
"description": "当温度超过35度时发送告警",
"enabled": true,
"trigger": {
"type": "property",
"productId": "prod_001",
"deviceId": "*",
"property": "temperature"
},
"conditions": [
{
"field": "temperature",
"operator": ">",
"value": 35
}
],
"actions": [
{
"type": "alert",
"config": {
"level": "warning",
"message": "设备 ${deviceName} 温度过高: ${temperature}°C"
}
},
{
"type": "notify",
"config": {
"channels": ["email", "sms"],
"recipients": ["admin@company.com", "13800138000"]
}
},
{
"type": "deviceCommand",
"config": {
"targetDevice": "${deviceId}",
"command": "setFanSpeed",
"params": { "speed": "high" }
}
}
]
}获取规则列表
GET /v1/iot/rules?enabled=true&page=1&pageSize=20启用/禁用规则
POST /v1/iot/rules/{ruleId}/enable
POST /v1/iot/rules/{ruleId}/disable测试规则
POST /v1/iot/rules/{ruleId}/test请求体：
{
"mockData": {
"deviceId": "dev_001",
"deviceName": "温控器-001",
"temperature": 38
}
}场景联动
创建场景
POST /v1/iot/scenes请求体：
{
"name": "回家模式",
"icon": "home",
"triggers": [
{
"type": "manual"
},
{
"type": "geofence",
"config": {
"location": "home",
"action": "enter"
}
}
],
"conditions": [
{
"type": "timeRange",
"config": {
"start": "17:00",
"end": "23:00"
}
}
],
"actions": [
{
"deviceId": "dev_light_001",
"command": "turnOn",
"params": { "brightness": 80 },
"delay": 0
},
{
"deviceId": "dev_ac_001",
"command": "turnOn",
"params": { "mode": "auto", "temperature": 24 },
"delay": 0
}
]
}执行场景
POST /v1/iot/scenes/{sceneId}/execute获取场景执行日志
GET /v1/iot/scenes/{sceneId}/logs固件升级
上传固件
POST /v1/iot/firmware
Content-Type: multipart/form-data创建升级任务
POST /v1/iot/firmware/upgrade-tasks请求体：
{
"firmwareId": "fw_001",
"targetDevices": {
"type": "specific",
"deviceIds": ["dev_001", "dev_002"]
},
"schedule": {
"type": "immediate"
},
"policy": {
"retryCount": 3,
"timeout": 600
}
}获取升级进度
GET /v1/iot/firmware/upgrade-tasks/{taskId}/progress数据统计
设备统计
GET /v1/iot/statistics/devices响应：
{
"code": 0,
"data": {
"total": 1000,
"online": 850,
"offline": 130,
"inactive": 20,
"onlineRate": 85.0,
"byProduct": [
{ "productId": "prod_001", "productName": "智能温控器", "count": 300 },
{ "productId": "prod_002", "productName": "智能灯具", "count": 500 }
]
}
}消息统计
GET /v1/iot/statistics/messages?startTime=2024-01-01&endTime=2024-01-15&interval=1d响应：
{
"code": 0,
"data": {
"total": 10000000,
"byType": {
"property": 8000000,
"event": 1500000,
"service": 500000
},
"trend": [
{ "date": "2024-01-01", "count": 650000 },
{ "date": "2024-01-02", "count": 680000 }
]
}
}