设备管理 API

概述

主要包含对物联网产品和设备等基础信息的管理.

本文定义的接口主要供应用程序调用.

系统前缀

API:

https://{domain-name}/v2/device/

版本

V3.1

作者

ChengZhen (zhen_cheng@sae.com.hk)

修改历史

2019/5/21

• 重写固件 API
• 添加事物模板 API

2018/10/13

• 重新定义产品的 manifest 属性

2018/8/2

• 基本属性添加最大长度列

设备类型

关于事物和事物描述的具体定义请参考 事物描述 一章。

系统内置了一些常用的物联网设备的描述信息，通过下面的接口可以访问这些信息。

事物模板

系统提供标准事物描述模板，创建产品时可以通过 type 属性引用相关的标准事物描述模板，这样这个产品就自动继承了这个标准事物的所有属性，方法以及事件等。同时产品也可以在标准事物的基础上添加自定义属性, 方法和事件等。

事物描述基本属性:

NAME	SORTABLE	TYPE	DESCRIPTION
name	yes	String	事物名称, 仅字母和数字等组成
title	yes	String	事物显示标题
titles	-	Object	中文显示标题
description	-	String	描述信息
descriptions	-	Object	中文描述信息
properties	-	Property	属性列表
actions	-	Action	操作列表
events	-	Event	事件列表

事物名称:

采用驼峰命名法，由字母组成，可选包含数字，首字母大写，如：

• WeatherStation
• WaterSensor

查询事物列表

GET /schema/list

返回结果:

返回系统定义的所有标准事物描述及其定义

{
    "total": Number,
    "schemas": [{
        "name": String,
        "title": String,
        "properties": {},
        "actions": {},
        "events": {}
    }]
}

查询指定名称的事物

GET /schema/get

返回结果:

返回指定名称的标准事物描述及其定义

{
    "name": String,
    "title": String,
    "properties": {},
    "actions": {},
    "events": {}
}

事物操作模板

事物操作基本属性:

NAME	SORTABLE	TYPE	DESCRIPTION
name	yes	String	操作名称
title	yes	String	显示名称
titles	-	Object	中文显示名称
description	-	String	描述信息
descriptions	-	Object	中文描述信息
input	-	DataSchema	输入参数类型, 具体请参考 WoT 事物描述
output	-	DataSchema	输出参数类型, 具体请参考 WoT 事物描述

查询操作列表

GET /schema/action/list

返回结果:

返回系统定义的所有标准操作及其定义

{
    "total": Number,
    "actions": [{
        "name": String,
        "title": String,
        "input": {},
        "output": {}
    }]
}

事物事件模板

事物事件基本属性:

NAME	SORTABLE	TYPE	DESCRIPTION
name	yes	String	事件名称
title	-	String	显示名称
titles	-	Object	中文显示名称
description	-	String	描述信息
descriptions	-	Object	中文描述信息
data	-	DataSchema	事件数据类型, 具体请参考 WoT 事物描述

查询事件列表

GET /schema/event/list

返回结果:

返回系统定义的所有标准事件及其定义

{
    "total": Number,
    "events": [{
        "name": String,
        "title": String,
        "data": {}
    }]
}

事物属性模板

事物属性基本属性:

NAME	SORTABLE	TYPE	DESCRIPTION
name	yes	String	属性名称
title	yes	String	显示名称
titles	-	Object	中文显示名称
description	-	String	描述信息
descriptions	-	Object	中文描述信息
type	yes	String	数据类型
maximum	yes	Number	最大值 (仅数值类型有效)
minimum	yes	Number	最小值 (仅数值类型有效)
unit	yes	String	单位

查询属性类型列表

GET /schema/property/types

返回结果

{
    "types": [String]
}

查询属性列表

关于属性的定义请参考 事物描述 一文

GET /schema/property/list

返回结果:

返回系统定义的所有标准属性及其定义

{
    "total": Number,
    "properties": [{
        "name": String,
        "title": String,
        "titles": {
            "zh-CN": String
        },
        "description": String,
        "descriptions": {
            "zh-CN": String
        },
        "type": String,
        "maximum": Number,
        "minimum": Number,
        "unit": String
    }]
}

故障代码表

NAME	TYPE	DESCRIPTION
name	String	故障名称
level	Number	故障级别
code	String|Number	故障代码
index	Number	故障索引
reason	String	故障原因
type	String	故障类型

查询故障列表

关于属性的定义请参考 事物描述 一文

GET /schema/fault/list

返回结果:

返回系统定义的所有标准属性及其定义

{
    "total": Number,
    "faults": [{
        "name": String,
        "level": Number,
        "code": String|Number,
        "index": Number,
        "reason": String,
        "type": String
    }]
}

产品

产品是某一类物联网设备的集合, 该类设备具有同样属性和功能. 您可以根据产品批量管理对应设备。

属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	yes	ObjectId	-	产品 ID，系统生成
brand	yes	String	32	品牌
config	-	Object	-	产品公共配置参数
created	yes	Date	-	创建时间，系统生成
description	-	String	200	方便人读的简要描述信息
protocol	yes	String	32	接入协议类型，由字母和数字组成
isPublic	yes	Boolean	-	指出是否公开这个产品给所有人使用
key	yes	String	32	产品编号, 用于标识一个产品，由字母和数字组成
manifest	-	Object	-	产品定义, 包含属性,方法,事件等事物描述信息
name	yes	String	32	方便人读的产品名称
metadata	-	Object	-	产品元数据，键值对
model	yes	String	32	产品型号
secret	-	String	64	产品密钥，由字母和数字组成
updated	yes	Date	-	最后更新时间，系统生成
type	yes	String	32	产品类型，由字母和数字组成

属性详细描述

产品类型

type

即标准事物名称，如果不存在相关的标准事物，也可以使用下面的名称

• 设备: device，指普通设备, 可以直连云端也可以做为子设备连接到网关
• 网关: gateway，具有边缘节点管理模块, 可以管理子设备, 并直连到云端
• 传感器: sensor，专用于采集数据
• 定位器: tracker，主要用于采集定位数据
• 控制器: controller， 主要用于控制设备

产品编号

key

在系统内具有唯一性, 可以使用产品的型号做为产品编号

命名规则: 采用驼峰命名法，由字母组成，可选包含数字，首字母小写，如 ledLight

产品密钥

secret

用于批量注册设备，默认没有启用

接入协议

protocol

• modbus Modbus/485 工业总线, 二进制数据格式, 最大消息大小不通超过 260B
• bluetooth 低功耗蓝牙, 二进制数据格式, 最大消息大小不通超过 200B
• coap CoAP/UDP 协议，JSON 数据格式，最大消息大小不能超过 1KB
• mqtt MQTT/TCP 协议，JSON 数据格式，最大消息大小建议不要超过 4KB
• http HTTP/TCP 协议，JSON 数据格式, 不能主动下发数据

产品元数据

metadata

产品的 metadata 中包含了产品的元数据, 常用来定义技术参数等信息, 常用的属性有:

NAME	TYPE	DESCRIPTION
model	String	型号, 1-32 个字符
updated	Date	产品元数据最后更新时间

产品配置信息

config

产品的 config 中包含了产品的全局配置信息, 具体内容和具体的产品相关, 常用的属性有:

NAME	TYPE	DESCRIPTION
updated	Date	产品属性最后一次修改时间

产品事物描述

manifest

系统使用 Manifest JSON 来描述一个设备, 它将包括如下的内容:

{
    "manifest": {
        "properties": {},
        "actions": {},
        "events": {}
    }
}

属性定义 (具体请参考 WoT 事物描述):

NAME	TYPE	DESCRIPTION
properties	Object	事物属性
actions	Object	事物操作
events	Object	事物事件

阈值设置

{
    "manifest": {
        "properties": {
            "<foo>": {
                "ranks": [{
                    "rank": Number,
                    "threshold": Number,
                    "title": String
                }]
            }
        }
    }
}

• ranks 阈值等级
  • rank 阈值级别, -5 ~ -1, 以及 1 ~ 5, 不包括 0, 分别表示最优，正常，轻度，中度，重度，严重
  • threshold 阈值
  • title 可选标题

创建一个新的产品

POST /product/add

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
description	-	String	描述
name	true	String	名称
key	-	String	产品编码
model	-	String	产品型号
type	-	String	产品类型
protocol	-	String	接入协议
brand	-	String	产品品牌
isPublic	-	Boolean	是否公开
secret	-	String	产品密钥

响应结果:

返回创建的产品的信息

{
    "id": String,
    "key": String,
    "name": String,
    "type": String,
    "protocol": String,
    "isPublic": Boolean,
    "description": String
}

查询指定产品

GET /product/get

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	产品 ID

响应结果:

返回指定产品的详细信息

{
    "id": String,
    "key": String,
    "name": String,
    "type": String,
    "protocol": String,
    "isPublic": Boolean,
    "description": String,
    "metadata": {
        "model": String,
        "version": String,
        "updated": Date
    },
    "config": {
        "updated": Date
    },
    "manifest": {
        "@context": String,
        "@type": String,
        "properties": {},
        "actions": {},
        "events": {}       
    }
}

修改产品属性

POST /product/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	产品 ID
brand	-	String	产品品牌
description	-	String	简要描述
key	-	String	产品编码
name	-	String	产品名称
type	-	String	产品类型
secret	-	String	产品密钥
metadata	-	String	产品元数据, JSON 字符串
manifest	-	String	产品定义, JSON 字符串
model	-	String	产品型号
config	-	String	产品配置信息, JSON 字符串
protocol	-	String	接入协议
isPublic	-	Boolean	是否公开

响应结果:

返回修改后的产品的信息

{
    "id": String,
    "key": String,
    "name": String,
    "type": String,    
    "protocol": String,
    "isPublic": Boolean,
    "description": String,
    "metadata": {},
    "manifest": {},
    "config": {}
}

删除一个产品

POST /product/del

• 不能删除包含有设备的产品
• 删除产品的同时需要删除产品的属性, 定义, 配置, 固件等相关信息

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	产品 ID

响应结果:

返回删除后的产品的信息

{
    "id": String,
    "key": String,
    "name": String,
    "type": String,
    "protocol": String,
    "isPublic": Boolean,
    "description": String,
    "metadata": {},
    "manifest": {},
    "config": {}
}

查询产品列表

GET /product/list (GET /product/)

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	String	0	开始返回的记录的索引
limit	String	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
select	String	-	选择要返回的字段，多个字段用空格或 +分隔
q	String	-	搜索条件字符串
q.name	String	-	模糊搜索产品名
q.key	String	-	模糊搜索产品编号
type	String	-	产品类型过滤条件

示例:

GET /product/list?q=name~=test

响应结果:

返回包含产品信息的列表

{
    "total": Number,
    "products": [{
        "id": String,
        "key": String,
        "name": String,
        "type": String,
        "protocol": String,
        "isPublic": Boolean,
        "description": String,
        "metadata": {},
        "manifest": {},
        "config": {}
    }]
}

固件

固件属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	yes	ObjectId	-	设备 ID
created	yes	Date	-	创建时间
name	yes	String	32	固件名称
productId	-	ObjectId	-	所属的产品 ID
size	yes	Number	-	固件大小
md5sum	-	String	36	MD5 摘要
version	yes	String	32	固件版本
url	-	String	255	文件 URL 下载地址
description	-	String	200	方便人读的简介
updated	yes	Date	-	最后修改时间

添加一个新的固件

POST /firmware/add

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
productId	yes	ObjectId	产品 ID
name	-	String	固件名称
version	yes	String	固件版本号
url	-	String	固件文件下载路径
md5sum	-	String	固件文件 MD5 Hash 值
size	-	Number	固件大小
description	-	String	固件简介

{
    "id": String,
    "version": String,      // 固件版本号
    "created": Number,
    "updated": Number,      // 最后修改时间, Unix 时间戳, 单位为秒
    "md5sum": String,         // 固件文件 etag 值, 一般取固件的 md5 hash 值
    "size": Number,         // 固件文件大小, 单位为字节
    "url": String,
    "name": String,
    "description": String
}

上传固件文件

POST /upload/firmware

请求格式:

采用 multipart/form-data 消息体格式

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
file	true	File	固件文件的内容
type	true	String	总是为 firmware
id	true	ObjectId	固件的 ID
description	-	String	固件简介

• 上传固件最大不能超过 10MB

响应结果:

返回上传的固件的信息

{
    "updated": Number,      // 最后修改时间, Unix 时间戳, 单位为秒
    "etag": String,         // 固件文件 etag 值, 一般取固件的 md5 hash 值
    "size": Number,         // 固件文件大小, 单位为字节
    "mimetype": String,
    "url": String,
    "name": String,
    "description": String
}

修改固件信息

POST /firmware/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	yes	String	产品 ID
name	-	String	固件名称
version	-	String	固件版本号
url	-	String	固件文件下载路径
md5sum	-	String	固件文件 MD5 Hash 值
size	-	Number	固件大小
description	-	String	固件简介

响应结果:

返回修改后的固件的信息

{
    "id": String,
    "version": String,
    "created": Date,
    "updated": Date, 
    "md5sum": String, 
    "size": Number, 
    "url": String,
    "name": String,
    "description": String
}

查询固件列表

GET /firmware/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	Number	0	开始返回的记录的索引
limit	Number	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
select	String	-	选择要返回的字段，多个字段用空格或 +分隔
q	String	-	搜索条件字符串
q.name	String	-	模糊搜索名称
productId	ObjectId	-	产品 ID

响应结果:

返回包含固件信息的列表

{
    "total": Number,
    "firmwares": [{
        "id": String,
        "version": String,      // 固件版本号
        "created": Number,
        "updated": Number,      // 最后修改时间, Unix 时间戳, 单位为秒
        "md5sum": String,         // 固件文件 etag 值, 一般取固件的 md5 hash 值
        "size": Number,         // 固件文件大小, 单位为字节
        "url": String,
        "name": String,
        "description": String
    }]
}

查询指定固件信息

GET /firmware/get

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	String	固件 ID

响应结果:

返回指定的固件的信息

{
    "id": String,
    "version": String,
    "created": Date,
    "updated": Date, 
    "md5sum": String, 
    "size": Number, 
    "url": String,
    "name": String,
    "description": String
}

查询指定设备固件信息

GET /firmware/

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
did	true	String	设备 ID

响应结果:

返回指定的设备最新的固件的信息

{
    "id": String,
    "version": String,
    "created": Date,
    "updated": Date, 
    "md5sum": String, 
    "size": Number, 
    "url": String,
    "name": String,
    "description": String
}

下载固件文件

GET /firmware/file

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
did	true	String	设备 ID

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	String	固件 ID

响应结果:

返回指定的设备最新的固件的文件的内容

<bin data>

删除固件

POST /firmware/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	固件 ID

响应结果:

返回删除的固件的信息

{
    "id": String,
    "version": String,
    "created": Date,
    "updated": Date, 
    "md5sum": String, 
    "size": Number, 
    "url": String,
    "name": String,
    "description": String
}

更新固件

固件验证

上传固件后, 可以选择单个设备下载并升级固件, 验证上传的固件能成功升级, 并能正常运行.

批量升级

验证通过后, 在产品管理中发起批量升级操作命令, 让产品的所有设备都自动升级到最新固件.

可以在设备管理界面查看固件升级状态.

重新升级

对于已升级过的, 或升级失败的设备, 可以发起重新升级命令.

设备

设备属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	yes	ObjectId	-	设备 ID
created	yes	Date	-	创建时间
config	-	Object	-	配置参数
description	-	String	200	描述
ownerId	-	ObjectId	-	这个设备所属的公司账号 ID
floor	-	Object	-	楼层
floorId	-	ObjectId	-	楼层 ID
room	-	Object	-	房间
roomId	-	ObjectId	-	房间 ID
did	-	String	32	设备 ID
name	yes	String	32	设备名
position	-	Object	-	设备在楼层的具体位置
properties	-	Object	-	设备属性
forms	-	Object	-	设备访问参数
product	-	Object	-	产品
productId	-	ObjectId	-	产品 ID
shadow	-	Object	-	设备影子信息
shadowId	-	ObjectId	-	设备影子 ID
secret	-	String	32	设备密钥
updated	yes	Date	-	最后修改时间

属性详细描述

did 设备 ID

每一个设备都有一个唯一用户分配的 ID，也称为 DID

主设备 ID

当一个设备属性一个主设备的一部分时，可以指定主设备 ID，方便在界面上关联显示等

网关设备 ID

指这个设备相关的网关设备的 ID

secret 设备密钥

用于验证设备注册消息 的密钥

设备影子 ID

当设备注册以及和平台通信后，平台会自动为其创建设备的影子，用来记录设备的最后状态等信息

公司账号 ID

当用户添加新的设备时，将自动关联到用户所属的公司

设备访问参数

• address 访问地址或 URL
• username 访问用户名
• password 访问密码
• channel 通道号
• protocol 通信协议
• format 数据格式
• type 访问接口类型
• encoding 字符编码格式

设备属性

• brand 品牌
• model 型号
• sn 序列号
• mac MAC 地址
• image 图片

创建一个新的设备

POST /device/add

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
name	true	String	设备名
did	true	String	设备 ID
description	-	String	描述
secret	-	String	密钥
x	-	Number	位置 (设备在楼层的 x 坐标)
y	-	Number	位置 (设备在楼层的 y 坐标)
floorId	-	ObjectId	楼层 ID
productId	true	ObjectId	产品 ID

响应结果:

返回添加的设备的信息

{
    "id": String,
    "mac": String,
    "did": String,
    "name": String,
    "secret": String,
    "description": String,
    "x": Number,
    "y": Number,
    "productId": String,
    "floorId": String,
}

获取指定设备信息

GET /device/get

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	设备 ID

响应结果:

返回指定的设备的详细信息

{
    "id": String,
    "name": String,
    "mac": String,
    "description": String,
    "x": Number,
    "y": Number,
    "floor": {
        "id": String,
        "name": String,
        "building": {
            "id": String,
            "name": String
        }
    },
    "location": String,
    "product": {
        "id": String,
        "name": String
    },
    "status": {
        "online": Boolean,
        "lastSeenOn": Date
    },
    "shadow": {

    }
}

修改设备属性

POST /device/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	设备 ID
master	-	String	主设备 ID
name	-	String	设备名
description	-	String	描述
x	-	Number	位置 (x坐标)
y	-	Number	位置 (y坐标)
properties	-	Object	设备属性
forms	-	Object	设备访问参数
floorId	-	ObjectId	楼层 ID
productId	-	ObjectId	产品 ID

响应结果:

返回修改后的设备的信息

{
    "id": String,
    "mac": String,
    "name": String,
    "description": String,
    "x": Number,
    "y": Number,
    "productId": String,
    "floorId": String,
}

删除一个设备

POST /device/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	设备 ID

响应结果:

返回删除的设备的信息

{
    "id": String,
    "name": String,
    "mac": String,
    "description": String,
    "x": Number,
    "y": Number,
    "productId": String,
    "floorId": String,
}

查询设备列表

GET /device/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	Number	0	开始返回的记录的索引
limit	Number	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
select	String	-	选择要返回的字段，多个字段用空格或 +分隔
q	String	-	搜索条件字符串
floorId	ObjectId	-	楼层 ID
productId	ObjectId	-	产品 ID
did	String|Array	-	设备 ID
expand	String	-	是否展开

示例:

GET /device/list?floorId=12345678&did=4567890&q=name~=test

响应结果:

返回包含设备信息的列表

{
    "total": Number,
    "offset": Number,
    "limit": Number,
    "devices": [{
        "id": String,
        "mac": String,
        "name": String,
        "description": String,
        "location": String,
        "x": Number,
        "y": Number,
        "product": {
            "id": String,
            "key": String,
            "name": String
        },
        "floor": {
            "id": String,
            "name": String,
            "building": {
                "id": String,
                "name": String
            }
        },
        "status": {
            "online": Boolean,
            "lastSeenOn": Date
        }
    }]
}

设备统计

统计所有设备

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
ownerId	String	-	要统计的企业账号 ID, @all 表示统计所有子账号

响应结果

返回设备模块统计信息

{
    "online": Number,  // 总共在线的设备
    "total": Number,   // 总共设备数
    "fault": Number,   // 故障设备数
    "products": [
        {
            "id": String,     // 产品 ID
            "name": String,   // 产品名
            "online": Number, // 在线设备数
            "total": Number   // 总共设备数         
        }
    ]
}

实时状态

GET /device/stat

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
type	String	-	要统计的设备类型
ownerId	String	-	要统计的企业账号 ID, @all 表示统计所有子账号

响应结果

返回设备模块统计信息

{
    "online": Number,  // 在线的设备
    "total": Number,   // 总共设备数
    "fault": Number,   // 故障设备数
    "charging": Number // 状态为 charging 的设备数量
}

活跃设备数

GET /device/stat

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
productId	String	-	产品 ID
duration	String	7d	统计时间段

响应结果

返回活跃设备统计信息

{
    "data": [{
        "start": Number,
        "end": Number,
        "online": Number,    // 活跃的设备数
        "total": Number    // 总共设备数
    }]
}

设备影子

事物是物理设备在平台的影子，也称设备影子。事物除了包含设备的信息外，还包含设备实时属性，在线状态等等信息

事物属性

NAME	TYPE	DESCRIPTION
id	String	设备影子 ID
alert	Object	事物相关的报警状态
actions	Object	事物相关的 Action 的状态
building	Object	事物相关的建筑物信息
config	Object	事物相关的配置信息
device	Object	事物相关的设备
did	String	设备 ID
events	Object	事物相关的事件的状态
fault	Object	事物相关的故障信息
floor	Object	事物相关的楼层信息
gateway	String	绑定的网关的设备 ID
key	String	产品编码
manifest	Object	事物能力描述
metadata	Object	事物相关的元数据
product	Object	事物相关的产品
properties	Object	事物相关的属性的状态
register	Object	事物相关的注册信息
room	Object	事物相关的房间区域信息
status	Object	事物当前状态 (系统属性)
telemetry	Object	事物相关的遥测信息
type	String	产品类型

报警信息 - alert

shadow.alert

• level 报警级别
• updated 更新时间
• alerts 报警列表
  • id 报警 ID
  • level 报警级别
  • type 报警类型
  • expires 有效期

故障信息 - fault

shadow.fault

设备出现一般故障时只发出警告，如果出现严重故障表示无法继续运行，需要工作人员处理后才能继续运行

• level 故障级别
  • 0 - 无故障
  • 1 - 一般故障
  • 2 - 严重故障
• updated 更新时间
• faults 报警列表
  • level 故障级别
  • type 故障类型
  • code 故障代码
  • name 故障名称
  • updated 更新时间

遥测信息 - telemetry

shadow.telemetry

telemetry 可包含如下通用遥测信息:

NAME	TYPE	DESCRIPTION
device	Object	设备信息
location	Object	位置信息
firmware	Object	固件信息
connectivity	Object	连接信息
config	Object	配置信息

事物描述 - manifest

shadow.manifest

JSON 格式的事物能力描述文档，具体请参考事物描述一文

操作状态 - actions

shadow.actions

属性状态 - properties

shadow.properties

设备上报的属性的最新状态

元数据 - metadata

shadow.metadata

保存了事物属性的最后更新时间等元数据

• metadata.{name}.updated 最后更新时间

服务端状态 - status

shadow.status

设备的状态由云服务器维护和提供, 如云服务器会根据设备的长连接状态和心跳状态来提供设备是否在线的状态.

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
lastSeenOn	yes	Date	-	最后在线时间
connected	yes	Boolean	-	是否在线
authenticated	yes	Boolean	-	是否通过认证

查询事物列表

GET /thing/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	Number	0	开始返回的记录的索引
limit	Number	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
select	String	-	选择要返回的字段，多个字段用空格或 +分隔
q	String	-	搜索条件字符串
floorId	ObjectId	-	楼层 ID
productId	ObjectId	-	产品 ID
key	String	-	产品编号
type	String	-	设备类型
dids	String|Array	-	设备 ID

select 额外要返回的属性:

• properties 事物实时状态

返回结果:

返回包含事物信息的列表

{
    "total": Number,
    "streams": {
        "<name>": {
            ...
        }
    },
    "things": [{
        "id": String,
        "created": Date,
        "did": String,
        "key": String,
        "type": String,
        "product": {
            "id": String,
            "name": String
        },
        "device": {
            "id": String,
            "name": String
        },
        "room": {
            "id": String,
            "name": String
        },
        "floor": {
            "id": String,
            "name": String
        },
        "building": {
            "id": String,
            "name": String
        },
        "properties": {
            "<name>": <value>
        },
        "actions": {},
        "events": {},
        "status": {
            "lastSeenOn": Number
        },
        "updated": Date
    }]
}

• total 总共事物数
• streams 返回的事物包含的所有数据流以及其元数据
• things 事物列表

查询单个事物

GET /thing/get

请求参数 (通过 ID 查询):

NAME	REQUIRED	TYPE	DESCRIPTION
id	Yes	ObjectId	设备的 ID

请求参数 (通过 DID 查询):

NAME	REQUIRED	TYPE	DESCRIPTION
did	Yes	String	设备的 DID

应答消息:

返回指定的事物的详情信息

{
    "id": String,
    "did": String,
    "key": String,
    "type": String,
    "product": {},
    "device": {},
    "room": {},
    "config": {},
    "register": {},
    "floor": {},
    "building": {},
    "properties": {},
    "metadata": {},
    "actions": {},
    "events": {},
    "status": {}
}

装备(设备分组)

装备属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	yes	ObjectId	-	装备 ID
alert	-	Object	-	报警状态
buildingId	yes	ObjectId	-	所在的建筑 ID
code	yes	Object	32	装备编码
created	yes	Date	-	创建时间
description	-	String	100	装备简介
fault	-	Object	-	故障状态
floorId	yes	ObjectId	-	所在的楼层 ID
image	yes	String	32	装备图片地址
metadata	-	Object	-	装备元数据
name	yes	String	32	装备名称
ownerId	yes	ObjectId	-	装备所属的公司账号
parts	-	Array	-	装备部件列表
scope	-	Object	-	装备坐标范围
state	-	String	32	装备状态
type	yes	String	32	装备类型
updated	yes	Date	-	最后更新时间

常见装备状态

• 停机 - stopped
• 关闭 - closed
• 在线 - online
• 完成 - completed
• 已锁 - unlocked
• 开机 - opened
• 开锁 - locked
• 待机 - standby
• 报警 - alert
• 故障 - fault
• 暂停 - suspend
• 正在充电 - charging
• 正在更新 - updating
• 正在测量 - measuring
• 正在重启 - rebooting
• 离线 - offline
• 运转 - running
• 预警 - warning

报警状态

和这个装备相关的报警

• level 报警级别
• alerts 报警列表

故障状态

故障状态，具体的故障代码含义取决于装备的类型

• code 故障代码
• name 故障名称

创建一个新的装备

POST /equipment/add

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
code	-	Object	装备编码
description	-	String	装备描述
floorId	true	ObjectId	装备所在楼层 ID
image	-	String	装备图片
metadata	-	Object	装备元数据
name	true	String	装备名称
parts	-	Array	装备部件 ID 列表
scope	-	Object	装备坐标范围
type	-	String	装备类型

响应结果:

返回创建的装备的信息

{
    "code": String,
    "created": Date,
    "description": String,
    "floorId": String,
    "id": String,
    "image": String,
    "metadata": Object,
    "name": String,
    "ownerId": String,
    "parts": Array,
    "scope": Object,
    "type": String,
    "updated": Date
}

获取指定的装备信息

GET /equipment/get

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	装备 ID

响应结果:

返回指定的装备的信息

{
    "code": String,
    "created": Date,
    "description": String,
    "floorId": String,
    "id": String,
    "image": String,
    "metadata": Object,
    "name": String,
    "ownerId": String,
    "parts": Array,
    "scope": Object,
    "type": String,
    "updated": Date
}

修改装备属性

POST /equipment/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	装备 ID
code	-	Object	装备编码
description	-	String	装备描述
floorId	true	ObjectId	装备所在楼层 ID
image	-	String	装备图片
metadata	-	Object	装备元数据
name	true	String	装备名称
parts	-	Array	装备部件 ID 列表
scope	-	Object	装备坐标范围
type	-	String	装备类型

响应结果:

返回修改后的装备的信息

{
    "code": String,
    "created": Date,
    "description": String,
    "floorId": String,
    "id": String,
    "image": String,
    "metadata": Object,
    "name": String,
    "ownerId": String,
    "parts": Array,
    "scope": Object,
    "type": String,
    "updated": Date
}

删除一个装备

POST /equipment/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	装备 ID

响应结果:

返回删除的装备的信息

{
    "code": String,
    "created": Date,
    "description": String,
    "floorId": String,
    "id": String,
    "image": String,
    "metadata": Object,
    "name": String,
    "ownerId": String,
    "parts": Array,
    "scope": Object,
    "type": String,
    "updated": Date
}

查询装备列表

GET /equipment/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	Number	0	开始返回的记录的索引
limit	Number	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
select	String	-	选择要返回的字段，多个字段用空格或 +分隔
q	String	-	搜索条件字符串
floorId	String	-	设备 ID
expand	String	-	是否展开查询结果，可选: all(展开相关的部件)

响应结果:

返回包含装备信息的列表

{
    "total": Number,
    "offset": Number,
    "limit": Number,
    "equipments": [{
        "code": String,
        "created": Date,
        "description": String,
        "floorId": String,
        "id": String,
        "image": String,
        "metadata": Object,
        "name": String,
        "ownerId": String,
        "parts": Array,
        "scope": Object,
        "type": String,
        "updated": Date
    }]
}

返回包含装备以及展开查询信息的列表(expand=all)

{
    "total": Number,
    "offset": Number,
    "limit": Number,
    "equipments": [{
        "code": String,
        "created": Date,
        "description": String,
        "floorId": String,
        "id": String,
        "image": String,
        "metadata": Object,
        "name": String,
        "ownerId": String,
        "parts": Array,
        "scope": Object,
        "type": String,
        "updated": Date，
        "things": Array,
        "streams": Object
    }]
}

操作

操作属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	yes	ObjectId	-	操作 ID
created	-	Date	-	创建时间
input	-	Object	-	操作输入数据
output	-	Object	-	操作输出数据
name	-	String	32	操作名称
title	-	String	32	操作标题
did	-	String	32	操作设备 DID
updated	-	Date	-	最后更新时间
user	-	Object	-	操作用户
metadata	-	Object	-	元数据
companyId	-	ObjectId	-	事件所属的公司账号
deviceId	-	ObjectId	-	相关的设备 ID

创建一个新的操作

POST /action/add

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
name	true	String	操作名称
did	true	String	操作设备 DID
input	-	Object	操作输入参数

响应结果:

返回创建的操作的信息

{
    "created": Date,
    "data": Object,
    "deviceId": String,
    "id": String,
    "name": String,
    "title": String,
    "updated": Date
}

获取指定的操作信息

GET /action/get

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	操作 ID

响应结果:

返回指定的操作的信息

{
    "created": Date,
    "data": Object,
    "deviceId": String,
    "id": String,
    "name": String,
    "title": String,
    "updated": Date
}

修改操作属性

POST /action/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	警报 ID

响应结果:

返回修改后的操作的信息

{
    "created": Date,
    "data": Object,
    "deviceId": String,
    "id": String,
    "name": String,
    "title": String,
    "updated": Date
}

删除一个操作

POST /action/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	操作 ID

响应结果:

返回删除的操作的信息

{
    "created": Date,
    "data": Object,
    "deviceId": String,
    "id": String,
    "name": String,
    "title": String,
    "updated": Date
}

查询操作列表

GET /event/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	Number	0	开始返回的记录的索引
limit	Number	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
select	String	-	选择要返回的字段，多个字段用空格或 +分隔
q	String	-	搜索条件字符串
did	String	-	设备 DID
name	String	-	操作名称

响应结果:

返回包含操作信息的列表

{
    "total": Number,
    "offset": Number,
    "limit": Number,
    "events": [{
        "created": Date,
        "data": Object,
        "deviceId": String,
        "id": String,
        "name": String,
        "title": String,
        "updated": Date
    }]
}

发送一个操作

POST /action/send

请求参数:

注意: 请求内容格式必须为 application/json

NAME	REQUIRED	TYPE	DESCRIPTION
name	true	String	操作名称
did	true	String	操作设备 DID
timeout	-	Number	等待超时时间，单位为毫秒
type	true	String	总是为 'action'
input	-	Object	操作输入参数

{
    "did": String,
    "timeout": Number,
    "type": "action",
    "data": {
        "<name>": <input>
    }
}

注意：当未提供 timeout 参数或者为 0 时，平台会立即返回应答。否则平台需要等到设备回应或超时后才返回应答消息

响应结果:

返回创建的操作的信息

{
    "did": String,
    "type": "action",
    "result": {
        ...
    }
}

事件

事件属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	yes	ObjectId	-	事件 ID
created	-	Date	-	创建时间
data	-	Object	-	事件数据内容
name	-	String	32	事件名称
title	-	String	32	事件标题
updated	-	Date	-	最后更新时间
ownerId	-	ObjectId	-	事件所属的公司账号
deviceId	-	ObjectId	-	相关的设备 ID

创建一个新的事件

POST /event/add

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
data	-	Object	事件数据
name	true	String	事件名称
deviceId	true	ObjectId	事件来源设备 ID
title	-	String	事件标题

响应结果:

返回创建的事件的信息

{
    "created": Date,
    "data": Object,
    "deviceId": String,
    "id": String,
    "name": String,
    "title": String,
    "updated": Date
}

获取指定的事件信息

GET /event/get

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	事件 ID

响应结果:

返回指定的事件的信息

{
    "created": Date,
    "data": Object,
    "deviceId": String,
    "id": String,
    "name": String,
    "title": String,
    "updated": Date
}

修改事件属性

POST /event/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	警报 ID
data	-	Object	事件数据
name	true	String	事件名称
source	true	Object	事件来源
title	-	String	事件标题

响应结果:

返回修改后的事件的信息

{
    "created": Date,
    "data": Object,
    "deviceId": String,
    "id": String,
    "name": String,
    "title": String,
    "updated": Date
}

删除一个事件

POST /event/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	事件 ID

响应结果:

返回删除的事件的信息

{
    "created": Date,
    "data": Object,
    "deviceId": String,
    "id": String,
    "name": String,
    "title": String,
    "updated": Date
}

查询事件列表

GET /event/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	Number	0	开始返回的记录的索引
limit	Number	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
select	String	-	选择要返回的字段，多个字段用空格或 +分隔
q	String	-	搜索条件字符串
deviceId	String	-	设备 ID

响应结果:

返回包含事件信息的列表

{
    "total": Number,
    "offset": Number,
    "limit": Number,
    "events": [{
        "created": Date,
        "data": Object,
        "deviceId": String,
        "id": String,
        "name": String,
        "title": String,
        "updated": Date
    }]
}

设备统计

统计模板

GET /servlet/list

能耗统计

GET /servlet/stat?name=energy-xxx

节能报表

GET /servlet/stat?name=energy-report

同比分析

GET /servlet/stat?name=energy-yoy

环比分析

GET /servlet/stat?name=energy-chain

能耗历史

GET /servlet/stat?name=energy-history

节能对比

GET /servlet/stat?name=energy-saving

时间段分析

GET /servlet/stat?name=energy-period

充电管理

GET /servlet/stat?name=charging-xxx

充电记录

GET /servlet/stat?name=charging-record

请求参数

NAME	TYPE	DEFAULT	DESCRIPTION
name	String	charging-record	统计模板名
plateNumber	String	-	车牌号码，如粤BD12345
stationNumber	String	-	充电站编号，如123094
startTime	Number	-	车辆入场时间， 1970年以来经过的毫秒数

响应结果:

{
    "name": "charging-record",
    "data": {
        "plateNumber": String, // 车牌号码
        "plateType": Number, // 车牌类型
        "stationNumber": String, // 充电站编号
        "pileNumber": String, // 可选，充电桩编号
        "isNewEnergyVehicle", Boolean, // 是否是新能源车
        "startTime": Number, // 最近一次充电开始时间,1970年以来经过的毫秒数
        "chargingTime": Number, // 最近一次充电总共充电时间（从开始充电到充满),单位为毫秒
        "dwellTime": Number, // 最近一次充电总共停留时间（从进入车位到离开车位),单位为毫秒
        "startSoC": Number, // 最近一次充电开始充电时的电量
        "endSoC": Number // 最近一次充电结束充电时的电量
    }
}

• 总是返回最后一次有效充电数据， 如果短时间内有多次充电，统计时会自动过滤充电时间过短的异常数据，如总充电时间少于 10 分钟的数据

系统属性

系统各模块统计信息

GET /system/stat

响应结果:

返回设备管理系统各模块统计信息

{
    "product": {
        "total": Number
    },
    "device": {
        "total": Number,
        "online": Number // 在线的设备数
    },
    "building": {
        "total": Number
    },
    "floor": {
        "total": Number
    },
    "room": {
        "total": Number
    },
    "shadow": {
        "total": Number
    },
    "schemas": {
        "total": Number
    }
}

系统状态

GET /system/status

返回结果:

返回服务器软件版本等信息

{
    "name": String,
    "description": String,
    "version": String
}

权限列表

表示系统支持并可以分配的权限列表:

注意如果没有 device 系统权限时不可以查看 device 服务下的所有信息.

NAME	DESCRIPTION	NOTE
device	设备管理的基本权限	-
device.action	设备操作权限
device.equipment	装备操作权限
device.stream	数据查询权限
device.product	产品操作权限	没有权限时仅且可以查看所有产品
device.device	设备操作权限	没有权限时仅且可以查看所有设备
device.beacon	信标操作权限	没有权限时仅且可以查看所有信标

权限分配表

API	PERMISSION	NOTE
/stat	-	-
/product/add	device.product	-
/product/del	device.product	-
/product/list	-	-
/product/get	-	-
/product/update	device.product	-
/product/config	device.product	-
/product/properties	device.product	-
/device/add	device.device	-
/device/del	device.device	-
/device/list	-	-
/device/get	-	-
/device/find	-	-
/device/stat	-	-
/device/update	device.device	-
/system/status	*	-

• '-' 表示必须登录后才能访问
• '*' 表示不需要登录也能访问