设备管理

一、应用场景

产品是设备的集合，通常是一组具有相同物模型的设备集合。创建产品完成后，需在产品下添加设备。具体添加设备流程可参照【设备接入指南】进行操作。
开发者可通过本服务获取设备相关信息，包括设备基础信息，网关设备与子设备的关联关系，同时也可通过本服务提供的能力对设备进行相应信息查询和设备控制。

二、功能说明

本服务提供获取设备基础信息，网关设备和子设备关系信息，以及设备信息获取和设备控制的能力，开发者在获取到相应授权前提下，可使用本服务获取设备相关信息，以及开展设备控制等业务构建。

三、前提条件

  1. 参考《创建产品》，完成创建产品流程。
  2. 获取授权

四、关键流程

4.1 通过物模型服务控制设备

img

  1. 创建产品
  2. 创建物模型
  3. 创建产品下设备
  4. 获取token
  5. 调用物模型服务控制设备接口（设备状态为上线状态，设备驱动接收到消息能正确响应，否则会导致调用接口超时）

4.2 设备解绑或绑定到网关

img

  1. 创建网关产品
  2. 创建设备产品
  3. 创建网关设备（产品类型为网关类型）
  4. 创建子设备（子设备和网关必须是同一租户。产品类型为设备类型，不能是网关类型。子设备没有所属网关）
  5. 获取token
  6. 调用设备解绑或绑定网关接口（同一子设备重复绑定网关会执行解绑网关操作）

五、API列表

5.1 设备基础信息（扩展属性、标签）

5.1.1 查询设备列表

接口描述

应用场景: 提供给其他终端（例如：APP，PC端）展示设备列表。

接口限制：B端用户权限，返回企业下的设备列表。

返回信息：设备基础信息，设备标签，设备扩展信息等。

请求方式

POST

请求地址

/v2/devices

请求头

名称 必填 类型 备注
Access-Token true String 访问Token（B端用户权限）
Content-Type true String application/json

请求参数

名称 必填 类型 备注
offset False Int 从某个偏移量开始请求，默认为0
limit False Int 请求的条目数量，默认为10
order False Map<String,String> 可以指定通过设备默认的某个字段排序（键值对），desc降序，asc升序
filter False List<String> 指定返回字段（字符串列表）
query False Object 查询条件，可以根据不同字段加上不同的比较指令来查询，查 询条件字段包含设备所有默认字段，不支持扩展属性字段，支 持比较指令包含如下: $in：包含于该列表任意一个值 $lt：小于该字段值 $lte：小于或等于字段值 $gt：大于该字段值 $gte：大于或等于该字段值 $like：模糊匹配该字段值支持字段有：id、mac、name、sn、is_active、active_date、home_id、create_time、tags_map、groups、gateway_id、thing_model_group、thing_model_category、thing_model_type、tags_map.key、tags_map.value

请求示例：

{
	"offset": 0,
	"limit": 10,
	"order": {
		"name": "desc"
	},
	"filter": ["id", "mac", "name", "is_active", "active_date", "is_online", "last_login", "last_login_ip", "mcu_mod", "mcu_version", "firmware_mod", "firmware_version", "product_id", "sn", "create_time", "creator_id", "creator_type", "dealer_scope", "heavy_buyer", "groups", "last_reset", "online_count", "gateway_id", "allow_shared", "tags_map"],
	"query": {
		"name": {
			"$like": "测试"
		}
	}
}

返回参数说明

名称 必填 类型 备注
count True Int 总数量
list True Array 设备列表
id True Int 设备ID
mac True String 设备MAC地址，12位十六进制字符
name False String 设备名称
is_active True Boolean 是否已激活，布尔值，true或false
active_date False String 激活时间，例：2014-10-09T08:15:40.843Z
is_online True Boolean 是否在线
last_login False String 最近登录时间，例：2014-10-09T08:15:40.843Z
last_login_ip False String 最近登录IP
mcu_mod True String MCU型号，20个字符
mcu_version True Int MCU软件版本号，32位数字整形
firmware_mod True String 固件型号，20个字符
firmware_version True Int 固件版本号，32位数字整形
product_id True String 产品ID
sn False String 设备序列号
create_time True String 创建时间，例：2014-10-09T08:15:40.843Z
creator_id True String 创建者ID
creator_type True Int 创建者类型
dealer_scope False String 经销商可访问的范围
heavy_buyer False String 大客户Id
groups False List<String> 所属分组ID列表字（字符串列表）
last_reset False String 最后激活时间,例：2014-10-09T08:15:40.843Z
online_count False Int 在线总时长
gateway_id False Int 设备的网关ID，取值为另一个设备ID
allow_shared False Boolean 是否可以(公区)分享
tags_map False List<Map<String,String>> 设备标签（键值对的数据结构）tags_map如：{“icon”:”icon.png”}, “icon”为tags_map键, “icon.png”为tags_map的键”icon”的值

返回示例：

{
    "count": 15076,
    "list": [
        {
            "firmware_version": 0,
            "mac": "9999",
            "gateway_id": 0,
            "online_count": "",
            "last_login_ip": "",
            "active_date": "2020-05-22T16:54:37.693Z",
            "product_id": "16000ebc8ef2200816000ebc8ef2b001",
            "id": 1416378467,
            "is_online": false,
            "sn": "999",
            "is_active": false,
            "create_time": "2020-05-22T16:54:37.693Z",
            "creator_type": 1,
            "last_login": "",
            "mcu_version": 0,
            "name": "门禁测试设备",
            "creator_id": "1201acbd845c7200",
            "groups": [
                "1201acbd845c7201",
                "1201acbd845c723"
            ],
            "tags_map": {
                "door": 1,
                "testing_door": "test_door"
            },
            "mcu_mod": "",
            "firmware_mod": "",
            "dealer_scope": "",
            "heavy_buyer": "",
            "last_reset": "",
            "allow_shared": true
        },
        {
            "firmware_version": 0,
            "mac": "T1",
            "gateway_id": 0,
            "online_count": "",
            "last_login_ip": "",
            "product_id": "160002bb5d9e0001160002bb5d9e0e01",
            "id": 1390631686,
            "is_online": false,
            "sn": "t1",
            "is_active": false,
            "create_time": "2020-12-10T15:44:09.514Z",
            "creator_type": 1,
            "last_login": "",
            "mcu_version": 0,
            "name": "视频重构测试设备",
            "creator_id": "1201acbd845c7200",
            "tags_map": {
                "t1": "t1_test"
            },
						"mcu_mod": "",
            "firmware_mod": "",
            "dealer_scope": "",
            "heavy_buyer": "",
            "last_reset": "",
            "allow_shared": true
        }
    ]
}
错误码 描述
4001001 参数验证不通过
4001002 参数不能为空

5.1.2 创建设备

接口描述

应用场景: 提供给其他终端（例如：APP，PC端）创建产品下设备。

接口限制：B端用户权限，创建产品下的设备。

请求方式

POST

请求地址

/v2/product/{product_id}/device

请求头

名称 必填 类型 备注
Access-Token true String 访问Token（B端用户权限）
Content-Type true String application/json

请求参数

名称 必填 类型 备注
mac True String MAC地址（在一个产品下必须唯一）
sn False String 序列号
name False String 设备别名
thing_model_group False String 物模型分组代码
thing_model_category False String 物模型品类代码
thing_model_type False String 物模型类型代码
tags_map False List<Map<String,String>> 设备标签，tags_map如：{“icon”:”icon.png”}, “icon”为tags_map键, “icon.png”为tags_map的键”icon”的值

请求示例：

{
    "mac": "AEE0",
    "sn": "0001",
		"name": "0001",
    "thing_model_group": "community",
    "thing_model_type": "frcamera",
    "thing_model_category": "security",
    "tags_map": [{
        "key": "类型",
        "value": "摄像头"
    }]
}

返回参数说明

名称 必填 类型 备注
id True Int 设备ID
mac True String 设备MAC

返回示例：

{
	"id": "484372656",
	"mac": "AEE0"
}
错误码 描述
4041005 产品不存在
4001021 该产品下设备MAC地址已存在
4001148 设备的sn已存在
4001469 物模型品类代码无定义错误

5.1.3 修改设备

接口描述

应用场景: 提供给其他终端（例如：APP，PC端）修改产品下设备，ProductId + Mac修改设备信息。

接口限制：B端用户权限。

返回信息：产品下物模型信息，包括物模型属性，服务和事件。

请求方式

POST

请求地址

/v2/device_info_update

请求头

名称 必填 类型 备注
Access-Token true String 访问Token（B端用户权限）
Content-Type true String application/json

请求参数

名称 必填 类型 备注
product_id True String 产品ID
mac True String 设备MAC
name False String 设备名称，1~64字符
sn False String 设备序列号，1~32字符
groups False List<String> 设备所属分组ID列表（字符串列表）
allow_shared False Boolean 是否可以(公区)分享
tags_map False List<Map<String,String>> 设备标签，tags_map如：{“icon”:”icon.png”}, “icon”为tags_map键, “icon.png”为tags_map的键”icon”的值

请求示例：

{
	"product_id": "16086ac2e4e0200916086ac2e4e09801",
	"mac": "A1",
	"name": "A1设备",
	"sn": "A1",
	"groups": ["asd","qwe"],
	"allow_shared": false,
	"tags_map": {
		"a1_tag": "test"
	}
}

返回参数说明

名称 必填 类型 备注
id True Int 设备ID，32位数字整形
mac True String 设备MAC地址
name False String 设备名称
is_active True Boolean 设备激活状态
active_date False String 激活时间，例：2014-10-09T08:15:40.843Z
is_online True Boolean 是否在线，true：在线；false：离线
last_login False String 最近登录时间，例：2014-10-09T08:15:40.843Z
last_login_ip False String 最近登录IP
mcu_mod True String MCU型号，20个字符
mcu_version True Int MCU软件版本号
firmware_mod True String 固件型号，20个字符
firmware_version True Int 固件版本号
corp_id True String 企业ID
product_id True String 产品ID
sn False String 设备序列号
create_time True String 设备创建时间，例：2014-10-09T08:15:40.843Z
groups False List<String> 所属分组列表（字符串列表）
allow_shared False Boolean 是否可以(公区)分享
tags_map False List<Map<String,String>> 设备标签，tags_map如：{“icon”:”icon.png”}, “icon”为tags_map键, “icon.png”为tags_map的键”icon”的值

返回示例：

{
    "active_date": "",
    "firmware_version": 0,
    "mac": "A1",
    "last_login_ip": "",
		"sn": "A1",
    "product_id": "16086ac2e4e0200916086ac2e4e09801",
    "id": 484372656,
    "is_online": false,
    "sn": "A1",
		"groups": ["group1","group2"],
    "is_active": false,
    "create_time": "2021-10-22T16:03:41.697Z",
    "creator_type": 1,
    "last_login": "",
    "firmware_mod": "",
    "region_id": 0,
    "allow_shared": false,
    "mcu_version": 0,
    "mcu_mod": "",
    "access_key": 0,
    "name": "A1设备",
    "creator_id": "12086ec202666c00",
    "corp_id": "100010b9c424fa00",
		"tags_map": {
			"test_a": "tag1",
			"test_group_a": "tag1_group"
		}
}
错误码 描述
4041005 产品信息不存在
4041008 设备不存在
4001148 设备序列号（SN）冲突

5.1.4 删除设备

接口描述

应用场景: 提供给其他终端（例如：APP，PC端）删除产品下设备，ProductId + Mac删除设备信息。

接口限制：B端用户权限。

请求方式

POST

请求地址

/v2/device_info_delete

请求头

名称 必填 类型 备注
Access-Token true String 访问Token（B端用户权限）
Content-Type true String application/json

请求参数

名称 必填 类型 备注
product_id True String 产品ID
mac True String 设备MAC

请求示例：

{
	"product_id": "16086ac2e4e0200916086ac2e4e09801",
	"mac": "A1"
}

返回参数说明

名称 必填 类型 备注
- - - -

返回示例：

无
错误码 描述
4041005 产品不存在

5.1.5 重置设备MAC信息

接口描述

使用场景：设备在返厂维修后，替换机器部件导致需要替换设备mac地址，维修成功后重新进入市场，由订阅该设备的用户或者企业下成员对该设备进行重置MAC。

接口限制：B端用户权限

请求方式

PUT

请求地址

/v2/device/{device_id}/mac

请求头

名称 必填 类型 备注
Access-Token true String 访问Token（B端用户权限）
Content-Type true String application/json

请求参数

名称 必填 类型 备注
mac True String 设备新的MAC地址（在一个产品下必须唯一）

请求示例：

{
    "mac": "1325997461395734529"
}

返回参数说明

名称 必填 类型 备注
- - - -

返回示例：

无
错误码 描述
4001021 该产品下设备MAC地址已存在
4041008 设备不存在

5.1.6 设置扩展信息

接口描述

使用场景：提供给其他终端（例如：APP，PC端）设置设备扩展信息，设备扩展信息以key-Value方式进行设置，最多设置10个字段。

接口限制：B端用户权限

请求方式

PUT

请求地址

/v2/product/{product_id}/device/{device_id}/property

请求头

名称 必填 类型 备注
Access-Token true String 访问Token（B端用户权限、C端用户权限）
Content-Type true String application/json

请求参数

名称 必填 类型 备注
{key} True String 扩展属性值

请求示例：

{
		"extend_refer":"1390639571"
}

返回参数说明

名称 必填 类型 备注
{key} True String 扩展属性值

返回示例：

{
		"extend_refer":"1390639571"
}
错误码 描述
4041005 产品不存在
4041008 设备不存在

5.1.7 获取扩展信息

接口描述

使用场景：提供给其他终端（例如：APP，PC端）获取设备扩展信息。

接口限制：B端用户权限。

返回信息：返回设备下的设备扩展信息。

请求方式

GET

请求地址

/v2/product/{product_id}/device/{device_id}/property

请求头

名称 必填 类型 备注
Access-Token true String 访问Token（B端用户权限、C端用户授权）
Content-Type true String application/json

请求参数

名称 必填 类型 备注
- - - -

请求示例：

无

返回参数说明

名称 必填 类型 备注
{key} True String 扩展属性值

返回示例：

{
		"extend_refer":"1390639571"
}
错误码 描述
4041005 产品不存在
4041008 设备不存在

5.1.8 删除扩展信息

接口描述

使用场景：提供给其他终端（例如：APP，PC端）删除设备扩展信息。

接口限制：B端用户权限

请求方式

DELETE

请求地址

/v2/product/{product_id}/device/{device_id}/property/{key}

请求头

名称 必填 类型 备注
Access-Token true String 访问Token（B端用户权限、C端用户授权）
Content-Type true String application/json

请求参数

名称 必填 类型 备注
- - - -

请求示例：

无

返回参数说明

名称 必填 类型 备注
- - - -

返回示例：

无
错误码 描述
4041005 产品不存在
4041008 设备不存在
4041009 扩展属性不存在

5.2 设备网关关系

5.2.1 获取网关下子设备列表

接口描述

使用场景：提供给其他终端（例如：APP，PC端）获取网关设备下的子设备列表。

接口限制：B端用户权限，设备类型为网关类型。

返回信息：网关设备下的子设备基础信息，子设备数量。

请求方式

POST

请求地址

/v2/device-subdevices

请求头

名称 必填 类型 备注
Access-Token true String 访问Token（B端用户权限、边缘网关）
Content-Type true String application/json

请求参数

名称 必填 类型 备注
gateway_id True Int 网关设备ID
offset False Int 从某个偏移量开始请求，默认为0
limit False Int 请求的条目数量，默认为10

请求示例：

{
    "gateway_id": "1390639571",
    "offset": 0,
    "limit": "10"
}

返回参数说明

名称 必填 类型 备注
count True Int 符合条件总数
list True Array 本次返回条目
list.id True Int 子设备ID
list.mac True String 子设备MAC
list.product_id True String 子设备所属产品
list.sn False String 子设备编号
list.name False String 子设备名称
list.home_id False String 子设备所属家庭
list.thing_model_group False String 子设备所属物模型分组代码
list.thing_model_category False String 子设备所属物模型品类代码
list.thing_model_type False String 物模型类型代码

返回示例：

{
    "count": 1,
    "list": [
        {
            "product_id": "16086ac27608200916086ac276081c01",
            "id": 1064576769,
            "mac": "AAA",
						"sn": "AAA",
						"name": "AAA",
						"home_id": "",
						"thing_model_group": "",
						"thing_model_category": "",
						"thing_model_type": ""
        }
    ]
}
错误码 描述
4001002 必填字段不可为空
4041008 设备不存在
4001242 不是网关设备
4041005 产品信息不存在

5.2.2 设备解绑或绑定到网关

接口描述

使用场景：提供给其他终端（例如：APP，PC端）绑定或者解绑网关；如终端网关自行管理的子设备，应当通过终端网关设备来管理设备与网关的关系

接口限制：

  1. B端用户权限
  2. 子设备和网关必须同属于一个租户下
  3. 子设备的产品类型必须是设备类型，不能是网关类型
  4. 网关设备的产品类型必须是网关类型

绑定逻辑：

  1. 当前子设备所属网关是所传参数的网关，接口不做任何操作。
  2. 当前子设备已有或没有所属网关，直接将设备绑定到所传参数的网关

解绑逻辑：

  1. 子设备当前没有所属网关，接口不做任何操作。
  2. 子设备当前所属网关是所传参数的网关，会执行解绑操作，如不是，不能解绑抛错。

请求方式

POST

请求地址

/v2/device-bind-gateway

请求头

名称 必填 类型 备注
Access-Token true String 访问Token（内部授权）
Content-Type true String application/json

请求参数

名称 必填 类型 备注
sub_device_id True int 子设备ID
gateway_id True int 网关设备ID
is_bind True Boolean true为绑定，false为解绑

请求示例：

{
    "sub_device_id": "1064576769",
    "gateway_id": "1390639571",
    "is_bind": true
}

返回参数说明

名称 必填 类型 备注
- - - -

返回示例：

无
错误码 描述
4041005 产品不存在
4041008 设备不存在

5.3 获取设备属性

5.3.1 获取设备属性

接口描述

使用场景：提供给其他终端（例如：APP，PC端）产品ID、MAC获取物模型属性。

接口限制：B端用户权限。

返回信息：设备最后一次上报的属性数据。

注意：设备属性数据是完全由设备上报的最后一次数据，如设备从未上报、或者仅靠属性下发而不使设备上报的情况下会获取不到。

请求方式

POST

请求地址

/v2/things/attribute_list_by_pid_mac

请求头

名称 必填 类型 备注
Access-Token true String 访问Token（B端用户权限）
Content-Type true String application/json

请求参数

名称 必填 类型 备注
product_id true string 产品ID
mac true string 设备MAC地址

请求示例：

{
    "mac":"1325997461395734529",
    "product_id":"16057cbf5404200916057cbf5404a401"
}

返回参数说明

名称 必填 类型 备注
false Object 返回数据
xnms false string 物模型ID
thing_id true string 设备ID
attributes false Map<String,String> 设备属性列表（键值对），如：attributes:{ “open”: “1”, “state”: “on”}

返回示例：

{
    "xnms": "n5fc26b11b5m9p36",
    "thing_id": "1390639571",
    "attributes": {
        "inner_ip": "192.168.2.25",
        "disk": "179",
        "memory": "7",
        "cpu_core": "8",
        "disk_usage": "1.0",
        "memory_usage": "3",
        "cpu_usage": "8.1",
        "uptime": "2020-11-07T13:39:46.294Z"
    }
}
错误码 描述
4001002 缺少必填请求字段
40428001 请求的设备信息不存在
4031003 无效的AccessToken

5.4 设备控制

5.4.1 通过物模型服务控制设备

接口描述

使用场景：提供给其他终端（例如：APP，PC端）产品ID、Mac调用设备（物模型）服务。

接口限制：B端用户权限，设备必须在线，设备协议为6.5协议。

返回信息：设备响应内容或服务端下发设备控制失败响应内容。

注：设置属性使用固定服务名（device_attribute_set_service）调用

请求方式

POST

请求地址

/v2/things/service_invoke_by_pid_mac

请求头

名称 必填 类型 备注
Access-Token true String 访问Token（B端用户权限）
Content-Type true String application/json

请求参数

名称 必填 类型 备注
product_id true string 产品ID
mac true string 设备MAC地址
service true string 服务名
input true Map<String,String> 输入参数（键值对），如: {“ColorTemperature”: 8}

请求示例：

{
    "mac":"1325997461395734529",
    "product_id":"16057cbf5404200916057cbf5404a401",
    "service":"device_attribute_set_service",
    "input":{
        "ColorTemperature":8
    }
}

返回参数说明

名称 必填 类型 备注
xnms false string 物模型ID
thing_id true string 设备ID
code true string 服务调用返回错误码
msg false string 服务调用返回错误信息
output false string 服务调用输出参数

返回示例：

{
    "output": {
    	"result": "200"
    },
    "code": "200",
    "xnms": "n5fc26b11b5m9p36",
    "thing_id": "1390639571"
}

服务调用返回错误码定义

code 描述
200 代表成功下发，并得到设备端的回复
202 设备在云平台为离线状态，不进行下发；
503 控制出现错误，可能情况：①平台内部无法访问IoT平台下发；②（常见原因）设备收到数据无响应；③（场景原因）设备没有实现该物模型服务
错误码 描述
4001002 缺少必填请求字段
40428001 请求的设备信息不存在
4031003 无效的AccessToken
40428009 产品没有定义物模型
没找到需要的文档？
你可以提交工单反馈 或 阅读常见问题
客服工单常见问题