设备

2025年2月22日大约 9 分钟

设备

查看设备列表

API 定义

GET /api/v1/devices?_page={page}&_limit={pageSize}

请求示例

GET /api/v1/devices?_page=1&_limit=10

成功响应

status 200

{
  "items": [
    {
      "IMEI": null, 
      "IMSI": null, 
      "authType": null, 
      "authTypeLabel": null, 
      "autoSub": null, 
      "blocked": 0, 
      "carrier": 1, 
      "cloudProtocol": 7, 
      "cloudProtocolLabel": "Modbus", 
      "createAt": "2018-10-26 11:27:56", 
      "description": null, 
      "deviceConsoleIP": null, 
      "deviceConsolePort": 22, 
      "deviceConsoleUsername": null, 
      "deviceID": "ea78e8af256d57b2a52dcda2f05282cf", 
      "deviceName": "modubs设备1", 
      "deviceStatus": 0, 
      "deviceStatusLabel": "离线", 
      "deviceType": 1, 
      "deviceTypeLabel": "终端", 
      "deviceUsername": "ea78e8af256d57b2a52dcda2f05282cf", 
      "gateway": 94, 
      "hardwareVersion": null, 
      "id": 95, 
      "latitude": null, 
      "location": null, 
      "longitude": null, 
      "lora": null, 
      "manufacturer": null, 
      "metaData": null, 
      "modBusIndex": 3, 
      "parentDevice": null, 
      "physicalNetwork": 1, 
      "productID": "4jMRrz", 
      "productIntID": 36, 
      "productName": "Modbus产品", 
      "scopes": [], 
      "serialNumber": null, 
      "softVersion": null, 
      "tenantID": "CkqVIYpeh", 
      "token": "da77cafead065dbf8ac1844f11db9d8c", 
      "upLinkSystem": 2, 
      "updateAt": null, 
      "userIntID": 6
    }
  ], 
  "meta": {
    "count": 1, 
    "limit": 10, 
    "page": 1
  }
}

查看设备详情

API 定义

GET /api/v1/devices/{deviceIntID}

请求示例

GET /api/v1/devices/46

成功响应

status 200

{
  "IMEI": null, 
  "IMSI": null, 
  "authType": null, 
  "authTypeLabel": null, 
  "autoSub": null, 
  "blocked": 0, 
  "carrier": 1, 
  "clientIP": null, 
  "cloudProtocol": 7, 
  "cloudProtocolLabel": "Modbus", 
  "connectedAt": null, 
  "createAt": "2018-10-26 11:27:56", 
  "createUser": "modbus", 
  "description": null, 
  "deviceConsoleIP": null, 
  "deviceConsolePort": 22, 
  "deviceConsoleUsername": null, 
  "deviceID": "ea78e8af256d57b2a52dcda2f05282cf", 
  "deviceName": "modubs设备1", 
  "deviceStatus": 0, 
  "deviceStatusLabel": "离线", 
  "deviceType": 1, 
  "deviceTypeLabel": "终端", 
  "deviceUsername": "ea78e8af256d57b2a52dcda2f05282cf", 
  "gateway": 94, 
  "gatewayName": "Modbus网关", 
  "hardwareVersion": null, 
  "id": 95, 
  "keepAlive": null, 
  "latitude": null, 
  "location": null, 
  "longitude": null, 
  "lora": null, 
  "manufacturer": null, 
  "metaData": null, 
  "modBusIndex": 3, 
  "parentDevice": null, 
  "parentDeviceName": null, 
  "physicalNetwork": 1, 
  "productID": "4jMRrz", 
  "productIntID": 36, 
  "productName": "Modbus产品", 
  "scopes": [], 
  "serialNumber": null, 
  "softVersion": null, 
  "tenantID": "CkqVIYpeh", 
  "token": "da77cafead065dbf8ac1844f11db9d8c", 
  "upLinkSystem": 2, 
  "updateAt": null, 
  "userIntID": 6
}

字段说明

字段名	示例值	字段类型	说明
IMEI	"null"	String	设备IMEI
IMSI	"null"	String	设备IMSI
authType	1	Integer	认证方式可选参数: Token: 1, 证书: 2
authTypeLabel	"Token"	String	Token
autoSub	"null"	Integer	自动订阅，0:关闭，1:开启
blocked	"null"	Integer	是否允许访问 0:允许 1:禁止
carrier	1	Integer	运营商可选参数: 中国电信: 1, 中国移动: 2, 中国联通: 3, 其他: 4
clientIP	"null"	String	客户端 IP
cloudProtocol	1	Integer	云端协议可选参数: MQTT: 1, CoAP: 2, LwM2M: 3, LoRa: 4, HTTP: 5, WebSocket: 6, Modbus: 7
cloudProtocolLabel	"MQTT"	String	云端协议可选参数: MQTT: 1, CoAP: 2, LwM2M: 3, LoRa: 4, HTTP: 5, WebSocket: 6, Modbus: 7
connectedAt	"null"	String	连接时间
createAt	"2019-09-14 14:55:20"	Date	创建时间
createUser	"actorcloud"	String	创建用户
description	"ull..."	String	描述
deviceConsoleIP	"null"	String	控制台ip
deviceConsolePort	22	Integer	控制台端口
deviceConsoleUsername	"null"	String	控制台用户名
deviceID	"063da5117b8c5ea5a6b3441edbf99d03"	String	设备 ID
deviceName	"mqtt设备_1"	String	设备名称
deviceStatus	"null"	Integer	设备运行状态可选参数: 离线: 0, 在线: 1, 休眠: 2
deviceStatusLabel	"离线"	String	设备运行状态可选参数: 离线: 0, 在线: 1, 休眠: 2
deviceType	1	Integer	设备类型可选参数: 终端: 1, 智能手机: 3 与上联系统互斥：该处值为 `终端: 1` 时才能填写 `upLinkSystem` 字段
deviceTypeLabel	"终端"	String	设备类型可选参数: 终端: 1, 智能手机: 3
deviceUsername	"063da5117b8c5ea5a6b3441edbf99d03"	String	设备用户名，用于连接emq
gateway	"null"	Integer	所属网关当设备类型 `upLinkSystem` 为 `2 (网关)` 时必须填写网关 ID
gatewayName	"null"	String	网关名称
hardwareVersion	"null"	String	硬件版本
id	46	Integer	id
keepAlive	"null"	Integer	心跳时间
latitude	25.064918	Float	纬度
location	"云南省昆明市五华区丰宁街道金鼎科技园"	JSON	位置
longitude	102.678732	Float	经度
lora	"null"	JSON	是否 LoRa 协议
manufacturer	"null"	String	制造商
metaData	"null"	json	元数据
modBuxIndex	3	Integer	索引，所属产品是 `Modbus` 协议时，必须填写(0~255之间的数字，同级设备不能重复)
parentDevice	"null"	Integer	上联设备 ID，当上联系统选择 `设备` 时，必须填写
parentDeviceName	"null"	String	上联设备名称
physicalNetwork	1	Integer	物理网络可选参数: WIFI: 1, 2G: 2, 3G: 3, 4G: 4, NB-IOT: 5, BlueTooth: 6
productID	"2ioNzM"	String	产品 ID
productIntID	60	Integer	产品 ID
productName	"MQTT产品"	String	产品名称
scopes	[]	Array	围栏范围
serialNumber	"null"	String	序列号
softVersion	"null"	String	软件版本
tenantID	"C2xPah6mn"	String	租户 ID
token	"990afd1e9448584abfca5b7154f9bcba"	String	设备秘钥
upLinkSystem	1	Integer	上联系统可选参数: 云: 1, 网关: 2, 设备: 3
updateAt	"2018-10-12 09:39:52"	Date	更新时间
userIntID	2	Integer	用户 ID

创建设备

创建说明

字段约束

所属产品与索引：
所属产品 productID 为 Modbus 协议的产品时，必须携带索引 modBusIndex 字段。
设备类型与上联系统：
设备类型 deviceType 为 1 (终端) 时，必须携带上联系统 upLinkSystem 字段，否则 upLinkSystem 应当为空。
上联系统与所属网关：
上联系统 upLinkSystem 为 2 (网关) 时必须携带有效 gateway 网关 ID 字段。
上联系统与所属设备：
上线系统 upLinkSystem 为 3 (设备) 时必须携带有效 parentDevice 设备 ID 字段。

详细字段间约束请见设备字段说明，网关信息参考网关列表 API。

多种设备类型

请求参数根据所选产品的云端协议有所不同，除去基础信息之外，下表给出相关差异：

云端协议	必填项	锁定项
MQTT、CoAP、HTTP、WebSocket	认证方式：`authType`	--
LwM2M	接入 IEMI：`IMEI` 、自动订阅： `autoSub`	--
LoRa	LoRa 协议相关信息，入网方式：`lora.type` 、DevEUI：`deviceID`、AppEUI： `lora.appEUI`、AppKey： `lora.appKey` 、FCnt Check： `lora.fcntCheck`、允许加入：`lora.canJoin`	入网方式：`lora.type`等于 `otaa` 时
LoRa	LoRa 协议相关信息，入网方式：`lora.type` 、所属网关：`gateway`、DevAddr： `deviceID`、发射频率： `lora.region` 、NwkSKey： `lora.nwkSKey`、AppSKey：`lora.appSKey`、FCnt Up：`lora.fcntUp`、FCnt Down： `lora.fcntDown`、FCnt Check：`lora.fcntCheck`	入网方式：`lora.type`等于 `abp` 时
Modbus	索引：`modBuxIndex`、认证方式：`authType`	--

API 定义

POST /api/v1/devices

请求示例

POST /api/v1/devices

{
  "productID": "p3zZMy",
  "upLinkSystem": 1,
  "longitude": 120.124144,
  "latitude": 30.266682,
  "location": "浙江省杭州市西湖区灵隐街道浙江大学玉泉校区",
  "cloudProtocol": 1,
  "deviceType": 1,
  "carrier": 1,
  "physicalNetwork": 1,
  "deviceName": "智能锁",
  "IMEI": "101010101010101",
  "IMSI": "101010101010101",
  "manufacturer": "江南",
  "serialNumber": "1061f1a1f47",
  "softVersion": "v 1.2",
  "hardwareVersion": "v 1.0",
  "description": "智能锁",
  "deviceConsoleIP": "192.168.1.1",
  "deviceConsoleUsername": "root",
  "deviceConsolePort": 22,
  "authType": 1,
  "deviceID": "10c61f1a1f47",
  "deviceUsername": "10c61f1a1f47",
  "token": "10c61f1a1f47"
}

成功响应

status 201

{
  "IMEI": "101010101010101",
  "IMSI": "101010101010101",
  "authType": 1,
  "autoSub": null,
  "blocked": 0,
  "carrier": 1,
  "createAt": "2018-09-30 16:37:55",
  "description": "智能锁",
  "deviceConsoleIP": "192.168.1.1",
  "deviceConsolePort": 22,
  "deviceConsoleUsername": "root",
  "deviceID": "10c61f1a1f47",
  "deviceName": "智能锁",
  "deviceStatus": 0,
  "deviceType": 1,
  "deviceUsername": "10c61f1a1f47",
  "gateway": null,
  "hardwareVersion": "v 1.0",
  "id": 189,
  "latitude": 30.266682,
  "location": "浙江省杭州市西湖区灵隐街道浙江大学玉泉校区",
  "longitude": 120.124144,
  "lora": null,
  "manufacturer": "江南",
  "metaData": null, 
  "modBusIndex": null, 
  "parentDevice": null, 
  "parentDeviceName": null, 
  "physicalNetwork": 1,
  "productID": "p3zZMy",
  "scopes": [],
  "serialNumber": "1061f1a1f47",
  "softVersion": "v 1.2",
  "tenantID": "C1g8RWNwv",
  "token": "10c61f1a1f47",
  "upLinkSystem": 1,
  "updateAt": null,
  "userIntID": 23
}

编辑设备

API 定义

PUT /api/v1/devices/{deviceIntID}

请求示例

PUT /api/v1/devices/191

{
  "IMEI": "111111111111110",
  "IMSI": "111111111111110",
  "authType": 1,
  "autoSub": 1,
  "blocked": 0,
  "carrier": 1,
  "clientIP": null,
  "cloudProtocol": 3,
  "cloudProtocolLabel": "LwM2M",
  "connectedAt": null,
  "createAt": "2018-09-30 17:03:56",
  "createUser": "ActorCloud",
  "description": null,
  "deviceConsoleIP": null,
  "deviceConsolePort": 22,
  "deviceConsoleUsername": null,
  "deviceID": "111111111111110",
  "deviceName": "lw",
  "deviceStatus": 0,
  "deviceStatusLabel": "离线",
  "deviceType": 1,
  "deviceTypeLabel": "智能手机",
  "deviceUsername": "xxxxxxxx",
  "gateway": null,
  "gatewayName": null,
  "hardwareVersion": null,
  "id": 191,
  "keepAlive": null,
  "latitude": null,
  "location": null,
  "longitude": null,
  "manufacturer": null,
  "metaData": null, 
  "modBusIndex": null, 
  "parentDevice": null, 
  "parentDeviceName": null, 
  "physicalNetwork": 1,
  "productID": "Bwj2pn",
  "productIntID": 129,
  "productName": "LWM2M",
  "scopes": [],
  "serialNumber": null,
  "softVersion": null,
  "tenantID": "C1g8RWNwv",
  "token": "xxxxxxxx",
  "upLinkSystem": 1,
  "updateAt": null,
  "userIntID": 23
}

成功响应

status 200

{
  "IMEI": "111111111111110",
  "IMSI": "111111111111110",
  "authType": 1,
  "autoSub": 1,
  "blocked": 0,
  "carrier": 1,
  "createAt": "2018-09-30 17:03:56",
  "description": null,
  "deviceConsoleIP": null,
  "deviceConsolePort": 22,
  "deviceConsoleUsername": null,
  "deviceID": "111111111111110",
  "deviceName": "lw",
  "deviceStatus": 0,
  "deviceType": 1,
  "deviceUsername": "xxxxxxxx",
  "gateway": null,
  "hardwareVersion": null,
  "id": 191,
  "latitude": null,
  "location": null,
  "longitude": null,
  "lora": null,
  "manufacturer": null,
  "metaData": null, 
  "modBusIndex": null, 
  "parentDevice": null, 
  "parentDeviceName": null, 
  "physicalNetwork": 1,
  "productID": "Bwj2pn",
  "scopes": [],
  "serialNumber": null,
  "softVersion": null,
  "tenantID": "C1g8RWNwv",
  "token": "xxxxxxxx",
  "upLinkSystem": 1,
  "updateAt": "2018-09-30 17:06:10",
  "userIntID": 23
}

删除设备

API 定义

DELETE /api/v1/devices?ids={deviceIntIDS}

请求示例

DELETE /api/v1/devices?ids=190

成功响应

status 204

""

导出设备

API 定义

GET /api/v1/devices_export

请求示例

GET /api/v1/devices_export

成功响应

status 202

{
  "statusUrl": "/task_status/2bcfc5eb-9ccb-487b-94aa-612f64dae53c"
}

字段说明

字段名	示例值	字段类型	说明
statusUrl	"/task_status/2bcfc5eb-9ccb-487b-94aa-612f64dae53c"	String	任务回调地址

导入设备

API 定义

POST /api/v1/devices_import

请求示例

POST /api/v1/devices_import

成功响应

status 202

{
  "statusUrl": "/task_status/90bfe9e1-250d-481f-8700-9047219b4f59"
}

查看子设备列表

API 定义

GET /api/v1/devices?parentDevice={deviceIntID}&_page={page}&_limit={pageSize}

请求示例

GET /api/v1/devices?parentDevice=95&_page=1&_limit=10

成功响应

status 200

{
  "items": [
    {
      "IMEI": null, 
      "IMSI": null, 
      "authType": 1, 
      "authTypeLabel": "Token", 
      "autoSub": null, 
      "blocked": 0, 
      "carrier": 1, 
      "cloudProtocol": 7, 
      "cloudProtocolLabel": "Modbus", 
      "createAt": "2018-10-29 14:48:37", 
      "description": null, 
      "deviceConsoleIP": null, 
      "deviceConsolePort": 22, 
      "deviceConsoleUsername": null, 
      "deviceID": "A_0573be62c1565f7dbe636765ae46af1a_1", 
      "deviceName": "modbus设备2", 
      "deviceStatus": 0, 
      "deviceStatusLabel": "离线", 
      "deviceType": 1, 
      "deviceTypeLabel": "终端", 
      "deviceUsername": "0573be62c1565f7dbe636765ae46af1a", 
      "gateway": null, 
      "hardwareVersion": null, 
      "id": 99, 
      "latitude": null, 
      "location": null, 
      "longitude": null, 
      "lora": null, 
      "manufacturer": null, 
      "metaData": null, 
      "modBusIndex": 5, 
      "parentDevice": 95, 
      "physicalNetwork": 1, 
      "productID": "4jMRrz", 
      "productIntID": 36, 
      "productName": "Modbus产品", 
      "scopes": [], 
      "serialNumber": null, 
      "softVersion": null, 
      "tenantID": "CkqVIYpeh", 
      "token": "88823fd94f0c5fcab1de844821a0810b", 
      "upLinkSystem": 3, 
      "updateAt": null, 
      "userIntID": 6
    }
  ], 
  "meta": {
    "count": 1, 
    "limit": 10, 
    "page": 1
  }
}

子设备的创建、编辑

与普通设备的创建、编辑类似，唯一不同的地方是 parentDevice 必填，且必须是上联设备的 ID

子设备删除

参考普通设备的删除接口

设备事件

API 定义

GET /api/v1/devices/{deviceIntID}/events?_page={page}&_limit={pageSize}

请求示例

GET /api/v1/devices/189/events?_page=1&_limit=10

成功响应

status 200

{
  "items": [
    {
      "IP": null,
      "createAt": "2018-09-30 16:55:31",
      "deviceID": "10c61f1a1f47",
      "deviceName": "智能锁",
      "id": 7623,
      "msgTime": "2018-09-30 16:55:31",
      "payload": "{ \"x\": 33.2, \"y\": 31.4 }",
      "topic": "topic",
      "updateAt": null
    },
    {
      "IP": null,
      "createAt": "2018-09-30 16:55:30",
      "deviceID": "10c61f1a1f47",
      "deviceName": "智能锁",
      "id": 7622,
      "msgTime": "2018-09-30 16:55:30",
      "payload": "{ \"x\": 33.2, \"y\": 31.4 }",
      "topic": "topic",
      "updateAt": null
    }
  ],
  "meta": {
    "count": 6,
    "limit": 10,
    "page": 1
  }
}

查看设备原始数据

API 定义

GET /api/v1/original_data?deviceID={deviceID}&metricType=2&time_unit=day

请求示例

GET /api/v1/original_data?deviceID=063da5117b8c5ea5a6b3441edbf99d03&metricType=2&time_unit=day

成功响应

status 200

[
  {
    "dataPointIntID": 1,
    "dataPointName": "温度",
    "originalData": {
      "time": [],
      "value": []
    }
  },
  {
    "dataPointIntID": 2,
    "dataPointName": "湿度",
    "originalData": {
      "time": [],
      "value": []
    }
  }
]

字段说明

字段名	示例值	字段类型	说明
dataPointIntID	1	Integer	功能点 ID
dataPointName	"温度"	String	功能点名称
originalData		Object	原始数据

查看设备指标数据

API 定义

GET /api/v1/metrics_data?deviceID={deviceID}&metricType=1

请求示例

GET /api/v1/metrics_data?deviceID=063da5117b8c5ea5a6b3441edbf99d03&metricType=1

成功响应

status 200

[
  {
    "aggregateData": null,
    "aggregateType": 1,
    "chartType": 1,
    "createAt": "2018-10-12 17:49:42",
    "dataPointIntID": 1,
    "expressions": "currentValue - lastValue",
    "id": 13,
    "isShow": 1,
    "metricData": {
      "time": [],
      "value": []
    },
    "metricName": "111",
    "metricType": 1,
    "productID": "2ioNzM",
    "productItemIntID": null,
    "remark": null,
    "updateAt": null
  }
]

字段说明

字段名	示例值	字段类型	说明
aggregateData	"null"	String	聚合数据
aggregateType	1	Integer	聚合方式可选参数: 最大值: 1, 最小值: 2, 平均值: 3, 累计值: 4
chartType	1	Integer	展示图表类型可选参数: 折线图: 1, 柱状图: 2
createAt	"2018-10-12 17:49:42"	Date	创建时间
dataPointIntID	1	Integer	功能点 ID
expressions	"currentValue - lastValue"	String	计算公式
id	13	Integer	id
isShow	1	Integer	是否显示在设备详情页面: 0否 1是
metricData		Object	指标数据
metricName	"111"	String	指标名称
metricType	1	Number	指标类型可选参数：公式指标：1，聚合指标：2
productID	"2ioNzM"	String	产品 ID
productItemIntID	"null"	Integer	产品 Item
remark	"null"	String	备注
updateAt	"null"	Date	更新时间

设备控制

API 定义

POST /api/v1/device_publish

请求示例

POST /api/v1/device_publish

{
  "deviceID": "10c61f1a1f47",
  "deviceIntID": 189,
  "payload": "{\"message\":\"Hello\"}",
  "topic": "topic"
}

成功响应

status 201

{
  "publishStatus": "successful"
}

新建设备定时任务

API 定义

POST /api/v1/device_schedule_publish

请求示例

POST /api/v1/device_schedule_publish

{
  "deviceID": "10c61f1a1f47",
  "deviceIntID": 189,
  "payload": "{\"message\":\"Hello\"}",
  "topic": "topic",
  "scheduleName": "默认定时",
  "IntervalMinute": "37",
  "scheduleType": 1
}

成功响应

status 201

""

删除设备定时任务

API 定义

DELETE /api/v1/device_schedule_publish?ids={scheduleIDS}

请求示例

DELETE /api/v1/device_schedule_publish?ids=28

成功响应

status 204

""