设备API

更新时间：2020-07-30 10:11:37

概述

设备服务是与设备相关的一组服务接口，为用户提供设备的查询、控制和关系服务能力。

本文档整体分为两部分

第一部分：数据定义，这些数据结构会频繁在接口中使用；

第二部分：接口定义，说明接口的入参、出参和示例。

接口分为两类：

基本操作接口

接口名	简介
控制设备	实现设备的控制。可以获取设备属性、设备设备属性和执行服务。
获取设备TSL	获取设备的物模型。
获取产品TSL	获取产品的物模型。
查询品类列表	查询品类列表。
查询设备	分页查询租户下的设备。
更新设备的备注名	更新设备的备注名。
重置设备	重置设备，解析所有关系和权限，并把设备从当前租户下移除。
查询子设备网关	查询子设备所属的网关。
查询设备详情	查询设备详细信息。
查询网关的子设备	查询网关下的子设备列表。
根据PK、DN查询设备信息	根据PK、DN查询设备信息。
绑定公区设备	根据PK、DN或者iotId绑定租户或者授权过的设备。

用户与设备的相关接口

接口名	简介
绑定用户与设备	建立用户与设备的逻辑关系。
解绑用户与设备	解除用户与设备的逻辑关系。
授权用户某设备的权限	给用户添加某个设备的管理员权限。
查询用户的设备	查询用户的关联设备。
查询设备的用户	查询设备的关联用户。
查询设备的用户（带角色）	查询设备的关联用户（带角色版本）。

数据定义

设备信息deviceInfo

名称	类型	备注
iotId	String	设备ID
productImage	String	设备的产品图片
deviceName	String	设备名DeviceName
nickName	String	用户对设备设置的昵称
productKey	String	设备ProductKey
productName	String	设备的产品名称
netType	String	产品入网方式
nodeType	String	产品类型，0 DEVICE 1 GATEWAY
categoryName	String	设备所属品类名称
categoryKey	String	设备所属品类key
thingType	String	设备的类型: "VIRTUAL", "WEB", "APP","DEVICE"
status	Integer	设备的状态: 0-初始化；1-在线；3-离线；8-禁用
spaceNamePath	String	设备所属空间路径名称
lastOnlineTime	String	设备最后上线时间
attributeList	JSONArray	设备属性列表，见定义

设备属性attribute

名称	类型	备注
iotId	String	设备ID
batchId	String	批次ID
group	String	设备分组
attribute	String	设备属性名
value	JSONObject	设备属性值
gmtModified	String	设备状态变化时间，须大于前一次同一个属性值的更新时间。

接口定义

设备配网接入

人居开放平台内使用的设备需要通过设备配网接入到平台中。完成了配网接入的设备，可以使用本文档内的接口实现设备的控制、查询、关联操作。

控制设备

实现设备的控制。

支持三种控制类型，通过控制命令的type参数来区分

获取设备的属性 type=GET_PROPERTIES

设置设备的属性 type=SET_PROPERTIES

调用设备的服务 type=INVOKE_SERVICE

/home/paas/device/control

当前版本 1.0.0

入参

字段名	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
targetId	String	是	设备ID，是所有执行命令的目标设备。
commands	JSONArray	是	控制命令列表，命令格式见下面的CommandInfo定义。

CommandInfo

字段名	类型	必填	备注
type	String	是	命令类型：SET_PROPERTIES 设置设备属性；INVOKE_SERVICE 服务调用； GET_PROPERTIES 获取设备属性
data	Map	是	要执行的具体操作：其参数结构详见下文示例

示例

以下示例说明如何使用“控制设备”接口实现“获取属性”、“设置属性”和“调用服务”。

获取属性-示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

控制的设备ID是nOv2JqehdKHQHfVnrJ2L0010366f10。

获取设备的属性值，仅传参type=GET_PROPERTIES即可。

获取到的设备属性与“获取设备TSL”接口->“TSL数据定义”中->properties的定义相同。

请求参数如下：

{
  "operator":{
      "hid":"1111299939433",
      "hidType":"OPEN"
  },
  "targetId": "nOv2JqehdKHQHfVnrJ2L0010366f10",
  "commands": [
    {
      "data": {},
      "type": "GET_PROPERTIES"
    }
  ]
}

设置属性-示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

控制的设备ID是nOv2JqehdKHQHfVnrJ2L0010366f10。

要将设备属性"WorkMode" 的值设置为0。（设备属性名参考“获取设备TSL”接口->“TSL数据定义”中->properties）

请求参数如下：

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"nOv2JqehdKHQHfVnrJ2L0010366f10",
    "commands":[
        {
            "data":{
                "PasswordLength":0
            },
            "type":"SET_PROPERTIES"
        }
    ]
}

调用服务-示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

控制的设备ID是nOv2JqehdKHQHfVnrJ2L0010366f10。

调用设备的服务“addKeys” ，服务参数为LockType=2, UserLimit=1。（设备服务参考“获取设备TSL”接口->“TSL数据定义”中->services）

请求参数如下：

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"nOv2JqehdKHQHfVnrJ2L0010366f10",
    "commands":[
        {
            "data":{
                "args":{
                    "LockType":2,
                    "UserLimit":1
                },
                "method":"AddKey" 
            },
            "type":"INVOKE_SERVICE"
        }
    ]
}

获取设备TSL

获取设备的物模型（TSL）。

物模型，简称TSL，即Thing Specification Language。描述了产品是什么，能做什么，可以提供哪些服务，详细定义见“物模型”。

TSL中的services定义了设备支持的服务，properties定义了设备支持的属性，events定义了设备支持事件。关于TSL数据结构的定义，见“TSL数据定义”的定义。

/home/paas/device/tsl/get

当前版本 1.0.0

入参

字段名	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。必须是有效的用户，用于记录接口操作者信息，不影响结果。
iotId	String	是	设备ID，最大长度64。

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

字段名	类型	备注
data	JSONObject	TSL数据，见TSL数据定义

Remarks

使用范围

可以获取租户下所有完成了配网绑定设备的TSL信息，不能获取未配网设备或其它租户的设备的TSL。

权限

支持非登录态和登录态。通常从B端调用时，使用非登录态。不建议从C端直接调用接口，如果使用则尽量以登录态访问（使用从鉴权服务拿到的iotToken作为请求参数）。

常见错误

错误码	处理建议
781	没有访问设备的权限。 1. 说明设备不在当前租户内，要检查设备ID是否正确。 2. 如果设备已经重置，也会报这个错误，可以尝试重新配网绑定。
62101	请求的设备不存在。 1. 检查请求的设备ID是否正确。 2. 如果确认设备ID无误，可以尝试重新配网绑定。

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

控制的设备ID是pp7Vy7zPg2SsL9hxRvIc0010695c10。

请求参数如下：

请求示例

{ 
  "operator":{
      "hid":"1111299939433",
      "hidType":"OPEN"
  },
  "iotId": "pp7Vy7zPg2SsL9hxRvIc0010695c10"
]

返回示例

{
  "code": 200,
  "data": {
    "schema": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json",
    "profile": {
      "productKey": "a17FE8wdZOj"
    },
    "services": [
      {
        "outputData": [

        ],
        "identifier": "set",
        "inputData": [
          {
            "identifier": "PasswordLength",
            "dataType": {
              "specs": {
                "min": "6",
                "unitName": "无",
                "max": "15",
                "step": "1"
              },
              "type": "int"
            },
            "name": "密码长度"
          }
        ],
        "method": "thing.service.property.set",
        "name": "set",
        "required": true,
        "callType": "async",
        "desc": "属性设置"
      },
      {
        "outputData": [
          {
            "identifier": "LockState",
            "dataType": {
              "specs": {
                "0": "关闭",
                "1": "开启"
              },
              "type": "bool"
            },
            "name": "门锁状态"
          },
          {
            "identifier": "PasswordLength",
            "dataType": {
              "specs": {
                "min": "6",
                "unitName": "无",
                "max": "15",
                "step": "1"
              },
              "type": "int"
            },
            "name": "密码长度"
          }
        ],
        "identifier": "get",
        "inputData": [
          "LockState",
          "PasswordLength"
        ],
        "method": "thing.service.property.get",
        "name": "get",
        "required": true,
        "callType": "async",
        "desc": "属性获取"
      }
    ],
    "properties": [
      {
        "identifier": "LockState",
        "dataType": {
          "specs": {
            "0": "关闭",
            "1": "开启"
          },
          "type": "bool"
        },
        "name": "门锁状态",
        "accessMode": "r",
        "required": true
      },
      {
        "identifier": "PasswordLength",
        "dataType": {
          "specs": {
            "min": "6",
            "unitName": "无",
            "max": "15",
            "step": "1"
          },
          "type": "int"
        },
        "name": "密码长度",
        "accessMode": "rw",
        "required": false,
        "desc": "密码长度"
      }
    ],
    "events": [
      {
        "outputData": [
          {
            "identifier": "LockState",
            "dataType": {
              "specs": {
                "0": "关闭",
                "1": "开启"
              },
              "type": "bool"
            },
            "name": "门锁状态"
          },
          {
            "identifier": "PasswordLength",
            "dataType": {
              "specs": {
                "min": "6",
                "unitName": "无",
                "max": "15",
                "step": "1"
              },
              "type": "int"
            },
            "name": "密码长度"
          }
        ],
        "identifier": "post",
        "method": "thing.event.property.post",
        "name": "post",
        "type": "info",
        "required": true,
        "desc": "属性上报"
      },
      {
        "outputData": [
          {
            "identifier": "ErrorCode",
            "dataType": {
              "specs": {
                "0": "正常"
              },
              "type": "enum"
            },
            "name": "故障代码"
          }
        ],
        "identifier": "Error",
        "method": "thing.event.Error.post",
        "name": "故障上报",
        "type": "error",
        "required": true
      },
      {
        "outputData": [
          {
            "identifier": "KeyID",
            "dataType": {
              "specs": {
                "length": "10"
              },
              "type": "text"
            },
            "name": "钥匙ID"
          },
          {
            "identifier": "LockType",
            "dataType": {
              "specs": {
                "1": "指纹",
                "2": "密码",
                "3": "卡",
                "4": "机械钥匙"
              },
              "type": "enum"
            },
            "name": "开锁方式"
          }
        ],
        "identifier": "DoorOpenNotification",
        "method": "thing.event.DoorOpenNotification.post",
        "name": "开门通知",
        "type": "info",
        "required": true
      },
      {
        "outputData": [

        ],
        "identifier": "TamperAlarm",
        "method": "thing.event.TamperAlarm.post",
        "name": "防撬报警",
        "type": "alert",
        "required": true
      },
      {
        "outputData": [

        ],
        "identifier": "LowElectricityAlarm",
        "method": "thing.event.LowElectricityAlarm.post",
        "name": "低电量报警",
        "type": "alert",
        "required": true
      },
      {
        "outputData": [

        ],
        "identifier": "DoorUnlockedAlarm",
        "method": "thing.event.DoorUnlockedAlarm.post",
        "name": "门未锁好报警",
        "type": "alert",
        "required": true
      }
    ]
  }
}

TSL数据定义

{
    "schema": "物的TSL描述schema",
    "link": "云端系统级uri,用来调用服务/订阅事件",
    "profile": {
        "productKey": "产品key",
        "deviceName": "设备名称"
    },
    "properties": [
        {
            "identifier": "属性唯一标识符(产品下唯一)",
            "name": "属性名称",
            "accessMode": "属性读写类型，只读(r)，读写(rw)",
            "required": "是否是标准功能的必选属性",
            "dataType": {
                "type": "属性类型: int(原生)，float(原生)，double(原生), text(原生)，date(String类型UTC毫秒)，bool(0或1的int类型)，enum(int类型), struct(结构体类型，可包含前面6种类型)，array(数组类型，支持int/double/float/text)",
                "specs": {
                    "min": "参数最小值(int, float, double类型特有)",
                    "max": "参数最大值(int, float, double类型特有)",
                    "unit": "属性单位, 参考(https://lark.alipay.com/bvm9rw/khct3d/mfedgo)",
                    "unitName": "单位的名称, 参考https://lark.alipay.com/bvm9rw/khct3d/mfedgo",
                    "size":"数组大小，默认最大128(数组特有)",
                    "item": {
                        "type":"数组元素的类型"
                    }
                }
            }
        }
    ],
    "events": [
        {
            "identifier": "事件唯一标识符(产品下唯一，其中post是默认生成的属性上报事件)",
            "name": "事件名称",
            "desc": "事件描述",
            "type": "事件类型(info,alert,error)",
            "required": "是否是标准功能的必选事件",
            "outputData": [
                {
                    "identifier": "参数唯一标识符",
                    "name": "参数名称",
                    "dataType": {
                        "type": "属性类型: int(原生)，float(原生)，double(原生), text(原生)，date(String类型UTC毫秒)，bool(0或1的int类型)，enum(int类型), struct(结构体类型，可包含前面6种类型)，array(数组类型，支持int/double/float/text)",
                        "specs": {
                            "min": "参数最小值(int, float, double类型特有)",
                            "max": "参数最大值(int, float, double类型特有)",
                            "unit": "属性单位, 参考(https://lark.alipay.com/bvm9rw/khct3d/mfedgo)",
                            "unitName": "单位的名称, 参考https://lark.alipay.com/bvm9rw/khct3d/mfedgo",
                            "size":"数组大小，默认最大128(数组特有)",
                            "item": {
                                "type":"数组元素的类型"
                            }
                        }
                    }
                }
            ],
            "method": "事件对应的方法名称(根据identifier生成)"
        }
    ],
    "services": [
        {
            "identifier": "服务唯一标识符(产品下唯一，产品下唯一，其中set/get是根据属性的accessMode默认生成的服务)",
            "name": "服务名称",
            "desc": "服务描述",
            "callType": "async(异步调用)，sync(同步调用)"
            "required": "是否是标准功能的必选服务",
            "inputData": [
                {
                    "identifier": "入参唯一标识符",
                    "name": "入参名称",
                    "dataType": {
                        "type": "属性类型: int(原生)，float(原生)，double(原生), text(原生)，date(String类型UTC毫秒)，bool(0或1的int类型)，enum(int类型), struct(结构体类型，可包含前面6种类型)，array(数组类型，支持int/double/float/text)",
                        "specs": {
                            "min": "参数最小值(int, float, double类型特有)",
                            "max": "参数最大值(int, float, double类型特有)",
                            "unit": "属性单位, 参考(https://lark.alipay.com/bvm9rw/khct3d/mfedgo)",
                            "unitName": "单位的名称, 参考https://lark.alipay.com/bvm9rw/khct3d/mfedgo",
                            "size":"数组大小，默认最大128(数组特有)",
                            "item": {
                                "type":"数组元素的类型"
                            }
                        }
                    }
                }
            ],
            "outputData": [
                {
                    "identifier": "出参唯一标识符",
                    "name": "出参名称",
                    "dataType": {
                        "type": "属性类型: int(原生)，float(原生)，double(原生), text(原生)，date(String类型UTC毫秒)，bool(0或1的int类型)，enum(int类型), struct(结构体类型，可包含前面6种类型)，array(数组类型，支持int/double/float/text)",
                        "specs": {
                            "min": "参数最小值(int, float, double类型特有)",
                            "max": "参数最大值(int, float, double类型特有)",
                            "unit": "属性单位, 参考(https://lark.alipay.com/bvm9rw/khct3d/mfedgo)",
                            "unitName": "单位的名称, 参考https://lark.alipay.com/bvm9rw/khct3d/mfedgo",
                            "size":"数组大小，默认最大128(数组特有)",
                            "item": {
                                "type":"数组元素的类型(数组特有)"
                            }
                        }
                    }
                }
            ],
            "method": "服务对应的方法名称(根据identifier生成)"
        }
    ]

获取产品TSL

获取产品的物模型（TSL），可查询产品的范围为产品列表接口返回结果中的所有产品。

物模型，简称TSL，即Thing Specification Language。描述了产品是什么，能做什么，可以提供哪些服务，详细定义见“物模型”。

TSL中的services定义了设备支持的服务，properties定义了设备支持的属性，events定义了设备支持事件。关于TSL数据结构的定义，见“TSL数据定义”的定义。

/thing/tsl/getByProducyKey

当前版本 1.0.2

入参

字段名	类型	必填	备注
productKey	String	是	产品key
deviceName	String	否	设备名称。

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

字段名	类型	备注
data	JSONObject	TSL数据，见TSL数据定义

具体参考

接口详情描述

查询品类列表

获取人居品类列表

查询维度 categoryName superId

categoryName: 品类名称，支持模糊查询

superId: 父品类Id，某些品类存在层级结构，superId表示某的品类Id
            superId为null时，查询所有品类列表；

            superId不为null时，查询当前品类下的子品类列表；
superId为空，categoryName为空，全量筛选，支持分页

superId为空，categoryName不为空，模糊匹配categoryName，全量范围内筛选，支持分页

superId不为空，categoryName为空，查询父id为superId的品类列表，支持分页

superId不为空，categoryName不为空，查询父id为superId，且其品类名称模糊匹配categoryName的的品类列表，支持分页

superId为0时，是在一级品类范围内筛选，支持分页

/home/paas/category/list

当前版本 1.0.0

入参

字段名	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
categoryName	String	否	品类名称筛选，支持模糊匹配
superId	Long	否	父id
pageNo	int	是	查询页码
pageSize	int	是	页码大小

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

字段名	类型	备注
data	JSONArray	分页数据，品类数据详情见CategoryInfo
total	Integer	总条数
pageNo	Integer	请求的页码，见“分页参数”定义。
pageSize	Integer	请求的页码，见“分页参数”定义。

CategoryInfo信息

字段名	类型	备注
categoryId	String	品类ID
categoryName	String	品类名
categoryKey	String	品类key
imageUrl	String	品类图片
state	Integer	品类状态：0无效，1有效
superId	Long	父品类Id

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

查询匹配名称“智能”的品类列表，查询范围：全范围(superId为空)

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  }
  "pageNo":1,
  "pageSize":20
  "categoryName":"智能"
}

返回示例

{
  "code": 200,
  "data": {
    "data": [
      {
        "categoryKey": "SmartLife",
        "state": 1,
        "superId": 0,
        "class": "com.aliyun.iotx.homelink.aquarius.hsf.dto.device.CategoryDTO",
        "categoryName": "智能生活",
        "categoryId": 274
      },
      {
        "categoryKey": "campus",
        "state": 1,
        "superId": 0,
        "class": "com.aliyun.iotx.homelink.aquarius.hsf.dto.device.CategoryDTO",
        "categoryName": "智能园区",
        "categoryId": 623
      },
      {
        "imageUrl": "url",
        "categoryKey": "SmartCity",
        "state": 1,
        "superId": 0,
        "class": "com.aliyun.iotx.homelink.aquarius.hsf.dto.device.CategoryDTO",
        "categoryName": "智能城市",
        "categoryId": 1
      },
      {
        "categoryKey": "SmartIndustry",
        "state": 1,
        "superId": 0,
        "class": "com.aliyun.iotx.homelink.aquarius.hsf.dto.device.CategoryDTO",
        "categoryName": "智能工业",
        "categoryId": 300
      }
    ],
    "pageNo": 1,
    "pageSize": 10,
    "total": 4
  },
  "message": "success",
}

查询设备

查询租户接入的所有设备，以分页列表方式返回。

查询的范围是所有完成了配网接入的、与用户产生关联的设备。

/home/paas/device/list

当前版本 1.0.0

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
pageInfo	JSONObject	否	分页查询参数，见“分页参数”定义。

出参

返回结果使用通用结果类型，data域是分页查询结果对象（下表中的data是分页结果中的数据），见下表的详细说明：

参数	类型	备注
data	JSONArray	分页数据，见设备信息定义。
total	Integer	总条数
pageNo	Integer	分页页码
pageSize	Integer	分页大小

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

查询所有接入的设备列表，查询第1页，每页20条记录。

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "pageQuery": {
    "pageNo":1,
    "pageSize":20
  }
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "iotId": "tMbycP1picrKhT0HQDCk001034b510",
        "spaceNamePath": "/根节点1/",
        "attributeList": [
          {
            "iotId": "tMbycP1picrKhT0HQDCk001034b510",
            "gmtModified": 1547797068655,
            "attribute": "LightMode",
            "batchId": "ce354176212c47448b6a7e97e2c85705",
            "value": 0
          },
          {
            "iotId": "tMbycP1picrKhT0HQDCk001034b510",
            "gmtModified": 1548036653624,
            "attribute": "LightSwitch",
            "batchId": "188cde35f2544526b9660abfc60b4b6a",
            "value": 1
          }
        ],
        "thingType": "DEVICE",
        "productKey": "a1mB9mXoz0q",
        "deviceName": "fordev",
        "productName": "带服务的灯_qw",
        "status": 1,
        "productImage": "https://img.alicdn.com/tps/TB1_I0aPXXXXXajXpXXXXXXXXXX-100-82.png",
        "nickName": "dev1",
        "lastOnlineTime": "2019-01-01 12:00:00"
      }
    ],
    "total": 1,
    "pageNo": 1,
    "pageSize": 20
  }
}

更新设备的备注名

设置单个设备的备注名。

主要用于设备详情页显示设备别名，前提需要发起请求的用户与设备已绑定，每个设备至多有一个备注名，nickName传入null时表示删除（清空）设备的备注名。

/home/paas/device/nickname/update

当前版本 1.0.1

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
iotId	String	是	设备ID
nickName	String	否	备注名，最大长度64字符

出参

返回结果使用通用结果类型，不使用data域，无值。

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

修改的设备ID是tMbycP1picrKhT0HQDCk001034b510。

新名称为“deviceA”

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "iotId": "tMbycP1picrKhT0HQDCk001034b510",
  "nickName": "deviceA"
}

返回示例

{
  "code": 200,
  "message": "success"
}

重置设备

实现云端设备重置。

设备的重置方式有三种：

1、硬件重置：用户在硬件上按reset键

2、云端重置：B端SaaS通过云云接口触发设备（云端）重置

3、C端重置：用户在App的设备管理中，点击“删除设备”

设备配网后即接入了业务平台，可以使用重置设备的接口主动从云端解绑与设备相关的所有业务关系。

主要流程有：

1、reset设备是否是网关设备

  1. 如果是网关设备

    1、解除与每个子设备相关的所有关系，包括：用户、空间、场景

    2、删除每个子设备的权限点

    3、发送reset complete消息给B端SaaS平台

2、解除与设备相关的所有关系，包括：用户、空间、场景

3、删除每个子设备的权限点

4、发送网关设备的reset complete消息给B端SaaS平台

注意：这个接口不会触发设备端的reset逻辑，所以云端重置后，如wifi类型的已配网设备可能仍保留配网信息连接在网络上。但从用户角度，已经查询不到这个设备，也接收不到这个设备的任何上报数据。

/home/paas/device/reset

当前版本 1.0.1

入参

参数	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
iotId	String	是	要重置的设备ID

出参

返回结果使用通用结果类型，data域是对象，类型是DeviceResetResult，见下面的详细说明：

DeviceResetResult

参数	类型	备注
iotId	String	解绑的设备ID
users	JSONArray	设备在重置前的关联用户列表，见DeviceUser定义
spaces	JSONArray	设备在重置前的关联空间列表，见DeviceSpace定义
scenes	JSONArray	设备在重置前的关联场景列表，见DeviceScene定义
children	JSONArray	子设备的重置信息，见DeviceResetResult定义。这是个嵌套结构，最多只嵌套一层，即一个网关设备带所性的子设备重置信息。

DeviceUser

参数	类型	备注
identity	JSONObject	设备的关联用户，见“身份信息”定义。
role	String	用户对设备的角色

DeviceSpace

参数	类型	备注
id	String	空间ID
name	String	空间名称
rootSpaceId	String	空间的根节点
parentId	String	空间的父节点
typeCode	String	空间类型代码
typeName	String	空间类型名称

DeviceScene

参数	类型	备注
id	String	场景ID

设备的重置数据用异步的方式通过HTTP2通道发给用户。消息数据见DeviceResetResult定义。

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

要重置的设备ID是ODFL8xIUDLrtAnfNw90v001020ae10。

请求参数如下：

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"ODFL8xIUDLrtAnfNw90v001020ae10"
}

返回示例

{
  "iotId":"ODFL8xIUDLrtAnfNw90v001020ae10",
  "deviceType":"GATEWAY",
  "users":[
    {
      "identity":{
        "hid":"1111299939433",
        "hidType":"OPEN",
        "appKey":"1234"
      }
    }
  ],
  "spaces":[
    {
      "id":"space_id_1",
      "name":"卧室",
      "parentId":"parent_space_id_1",
      "typeCode":"HOUSE",
      "typeName":"房屋"
    }
  ],
  "scenes":[],
  "children":[
    {
      "iotId":"child_device_1",
      "deviceType":"GATEWAY",
      "users":[
        {
          "identity":{
            "appKey":"1234",
            "hid":"abcd1234",
            "hidType":"OPEN"
          }
        }
      ],
      "spaces":[
        {
          "id":"space_id",
          "name":"卧室",
          "parentId":"parent_space_id_1",
          "typeCode":"HOUSE",
          "typeName":"房屋"
        }
      ],
      "scenes":[
        {
          "id":"scene_id_2"
        }
      ],
      "children":[]
    }
  ]
}

查询子设备网关

/home/paas/device/gateway/get

当前版本 1.0.1
入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
iotId	String	是	要查询的子设备ID，接口会检查设备的有效性。

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
data	JSON	包含网关的productKey, deviceName以及iotId

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

要重置的设备ID是ODFL8xIUDLrtAnfNw90v001020ae10。

请求参数如下：

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"ODFL8xIUDLrtAnfNw90v001020ae10"
}

返回示例

{
    "iotId":"4I0flISLFCDTMeE63LfG001085c000",
    "deviceName":"gridlink_gateway_01",
    "productKey":"a17x7h7FlsH",
}

查询设备详情

每次请求至多查询20个设备。

/home/paas/device/detail/get

当前版本

版本号	说明
1.0.0	初始版本，属性值列表中的value是JSON结构体（详见出参说明）
1.0.1	属性值列表中的value是String类型的JSON字符串
1.0.2	在1.0.1版本基础上，在出参中增加了节点类型和产品入网类型
1.0.3	在1.0.2版本基础上，在出参中增加了品类key和品类名称

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
rootSpaceId	String	否	顶层空间id。
iotIds	JSONArray	是	要查询的设备。

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
data	JSONArray	属性详情信息见DeviceInfoDTO

DeviceInfoDTO信息

字段名	类型	备注
spaceId	String	空间Id
spaceName	String	空间名称
iotId	String	设备id
productImage	String	产品图片
deviceName	String	设备名称
nickName	String	设备昵称
productKey	String	产品key
productName	String	产品名
categoryKey	String	品类key
categoryName	String	品类名
nodeType	String	节点类型（限1.0.2版本及以上）
netType	String	产品入网类型（限1.0.2版本及以上）
status	Integer	设备状态
isEdgeGateway	Boolean	是否边缘网关
attributes	JSONArray	属性值列表，属性定义见Attribute

Attribute信息

字段名	类型	备注
attribute	String	属性名
value	String	属性值

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

要重置的设备ID是ODFL8xIUDLrtAnfNw90v001020ae10。

请求参数如下：

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"ODFL8xIUDLrtAnfNw90v001020ae10"
}

返回示例

{
  "id": "4de2c367-c1db-417c-aa15-8c585e595d92",
  "code": 200,
  "message": null,
  "localizedMsg": null,
  "data": [
    {
      "spaceName": "孙子空间Ii",
      "spaceId": "e1e11a41574a4ad8945049e05178d53f",
      "iotId": "5LrQn6zlVQ0o1CITxr06000101",
      "attributes": [

      ],
      "productKey": "a1aF7LtSNk8",
      "isEdgeGateway": false,
      "deviceName": "light0",
      "productName": "带服务的灯",
      "status": 0
    },
    {
      "iotId": "nU0hWEGeqg8TNB5tCcfk000101",
      "attributes": [
        {
          "attribute": "CountDown",
          "value": "{}"
        },
        {
          "attribute": "CountDownList",
          "value": "{}"
        },
        {
          "attribute": "LocalTimer",
          "value": "[]"
        }
      ],
      "productKey": "a1aF7LtSNk8",
      "isEdgeGateway": false,
      "deviceName": "light2",
      "productName": "带服务的灯",
      "status": 0
    }
  ]
}

查询网关的子设备

/home/paas/device/sub/list

当前版本 1.0.0
入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
iotId	String	是	网关设备ID
pageQuery	JSONObject	否	分页查询参数，见“分页参数”定义。

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
data	JSONArray	分页数据，每个数据项中包含子设备的productKey、deviceName、iotId，以及是否接入人居平台。
total	Integer	总条数
pageNo	Integer	分页页码
pageSize	Integer	分页大小

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

要查询的网关设备ID是ODFL8xIUDLrtAnfNw90v001020ae10。

请求参数如下：

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"ODFL8xIUDLrtAnfNw90v001020ae10",
    "pageQuery":{
        "pageNo":1,
        "pageSize":10
    }
}

返回示例

{
  "total":1,
  "data":[
    {
      "iotId":"4I0flISLFCDTMeE63LfG001085c000",
      "deviceName":"gridlink_sub_01",
      "productKey":"a17x7h7FlsH",
      "belongsToHomelink":true
    }
  ],
  "pageNo":1,
  "pageSize":10
}

根据PK、DN查询设备信息

/home/paas/device/info/get

版本1.0.0

入参

字段名	类型	必传	备注
productKey	String	是	设备PK
deviceName	String	是	设备名称

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	描述
iotId	String	设备ID
productKey	String	设备PK
deviceName	String	设备名称

示例

请求示例

{
   "productKey":"PK",
   "deviceName":"deviceName"
}

返回示例

{
   "code":200,
   "data":{
       "iotId":"iotId",
       "productKey":"PK",
       "deviceName":"deviceName"
   },
   "message":"success"
}

绑定公区设备

绑定公区设备，使设备接入人居平台。

仅对租户下的设备或者授权给该租户的设备有权限。

如果公区设备是边缘网关，会异步处理子设备绑定。如果ISV给后续操作预留等待时间，每设备50ms。

/home/paas/lp/device/bind

当前版本 1.0.0

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
iotId	String	否	要绑定的设备ID，接口会检查设备的有效性，与productKey和deviceName不可同时为空。
productKey	String	否	要绑定设备的产品的key
deviceName	String	否	要绑定的设备名称。
target	JSONObject	是	要绑定用户账号列表，格式见“身份信息”定义。列表不允许为空，所有元素的hid类型必须一致。

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
iotId	String	设备iotId

绑定用户与设备

绑定用户与设备的逻辑关系。

设备是已经完成配网的设备，见“设备配网接入”节的说明。

其它用户与设备的逻辑关系通过本接口和“解绑用户与设备”的接口维护。

接口支持批量操作，可以实现：

一个设备与一个用户建立逻辑关系；

一个设备与多个用户建立逻辑关系。

一个设备最多与1000个用户建立关系。

接口执行时会绑定尽可能多的关系，单个用户与设备的绑定失败不影响其它用户与设备的绑定。

如果完成后没有一个成功绑定的用户，接口会返回错码和消息，否则返回成功。

/home/paas/user/device/bind

当前版本 1.0.1

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
iotId	String	是	要绑定的设备ID，接口会检查设备的有效性。
targetList	JSONArray	是	要绑定用户账号列表，格式见“身份信息”定义。列表不允许为空，所有元素的hid类型必须一致。

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
data	JSONArray	这是一个组合结果的列表，每个元素都描述一个用户的绑定结果当输入用户中有重复时，结果列表中也会有重复结果项。

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

控制的设备ID是nOv2JqehdKHQHfVnrJ2L0010366f10。

要绑定到两个用户，用户使用了三方账号体系：

用户1，ID=3008045502161

用户2，ID=8189058505890，这是个错误的用户ID

请求参数如下：

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"nOv2JqehdKHQHfVnrJ2L0010366f10",
    "targetList":[
        {
            "hid":"3008045502161",
            "hidType":"OPEN"
        },
        {
            "hid":"8189058505890",
            "hidType":"OPEN"
        }
    ]
}

返回示例

{
    "code":200,
    "message":"success",
    "data":[
        {
            "identity":{
                "hid":"3008045502161",
                "hidType":"OPEN"
            },
            "result":{
                "code":200,
                "message":"success"
            }
        },
        {
            "identity":{
                "hid":"8189058505890",
                "hidType":"OPEN"
            },
            "result":{
                "code":62107,
                "message":"No valid target user was found.",
                "localizedMsg":"没有有效的目标用户。"
            }
        }
    ]
}

表示

第一个hid绑定成功
第二个hid绑定失败，返回错误码是62107

解绑用户与设备

解除设备与用户的逻辑关系。

设备完成配网后，使用绑定用户与设备接口建立用户与设备的逻辑关系。这个接口是绑定操作的逆操作。

接口支持批量操作，可以实现：

一个设备与一个用户解除逻辑关系；

一个设备与多个用户解除逻辑关系。

接口执行时会解绑尽可能多的关系，单个用户与设备的操作失败不影响其它用户与设备的操作。

如果完成后没有一个成功解绑的用户，接口会返回错码和消息，否则返回成功。

/home/paas/user/device/unbind

当前版本 1.0.1

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
iotId	String	是	要解绑的设备ID，接口会检查设备的有效性。
targetList	JSONOArray	是	要解绑的用户账号列表，格式见“身份信息”定义。列表不允许为空，所有元素的hid类型必须一致。

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
data	JSONArray	这是一个组合结果的列表，每个元素都描述一个用户的解绑结果当输入用户中有重复时，结果列表中也会有重复结果项。

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

控制的设备ID是nOv2JqehdKHQHfVnrJ2L0010366f10。

要解绑的两个用户如下，使用了三方账号体系：

用户1，ID=3008045502161

用户2，ID=8189058505890，这是个错误的用户ID

请求参数如下：

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"nOv2JqehdKHQHfVnrJ2L0010366f10",
    "targetList":[
        {
            "hid":"3008045502161",
            "hidType":"OPEN"
        },
        {
            "hid":"8189058505890",
            "hidType":"OPEN"
        }
    ]
}

返回示例

{
    "code":200,
    "message":"success",
    "data":[
        {
            "identity":{
                "hid":"3008045502161",
                "hidType":"OPEN"
            },
            "result":{
                "code":200,
                "message":"success"
            }
        },
        {
            "identity":{
                "hid":"8189058505890",
                "hidType":"OPEN"
            },
            "result":{
                "code":62107,
                "message":"No valid target user was found.",
                "localizedMsg":"没有有效的目标用户。"
            }
        }
    ]
}

授予用户对某设备的权限

授予设备与用户的权限。

接口支持批量操作，可以实现：

设置一个用户在当前设备下的管理员/普通成员权限；

设置多个用户在当前设备下的管理员/普通成员权限；

如果一个用户已是设备管理员，授权为普通用户可以取消用户对当前设备的管理员权限。

设置用户为设备的管理员时，当前用户需与设备有绑定关系

接口执行时会授予尽可能多的权限，单个用户与设备的授权操作失败不影响其它用户与设备的操作。

如果完成后没有一个成功解绑的用户，接口会返回错码和消息，否则返回成功。

/home/paas/user/device/perm/auth

当前版本 1.0.0

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
iotId	String	是	要授权的设备ID，接口会检查设备的有效性。
targetList	JSONOArray	是	要解绑的用户账号列表，格式见“身份信息”定义。列表不允许为空，所有元素的hid类型必须一致。
roleCode	String	是	要授权的类型 DEVICE_MANAGER 设备管理员权限。有删除设备、修改设备备注名的权限 DEVICE_MEMBER 设备的使用者，可以看到和使用设备，

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
data	JSONArray	这是一个组合结果的列表，每个元素都描述一个用户的解绑结果当输入用户中有重复时，结果列表中也会有重复结果项。

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

控制的设备ID是nOv2JqehdKHQHfVnrJ2L0010366f10。

要授权的两个用户如下，使用了三方账号体系：

用户1，ID=3008045502161

用户2，ID=8189058505890，这是个错误的用户ID

请求参数如下：

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"nOv2JqehdKHQHfVnrJ2L0010366f10",
    "targetList":[
        {
            "hid":"3008045502161",
            "hidType":"OPEN"
        },
        {
            "hid":"8189058505890",
            "hidType":"OPEN"
        }
    ],
    "DEVICE_MANAGER"
}

返回示例

{
    "code":200,
    "message":"success",
    "data":[
        {
            "identity":{
                "hid":"3008045502161",
                "hidType":"OPEN"
            },
            "result":{
                "code":200,
                "message":"success"
            }
        },
        {
            "identity":{
                "hid":"8189058505890",
                "hidType":"OPEN"
            },
            "result":{
                "code":62107,
                "message":"No valid target user was found.",
                "localizedMsg":"没有有效的目标用户。"
            }
        }
    ]
}

查询用户的设备

查询与用户关联的设备列表。

接口返回使用“绑定用户与设备”接口建立逻辑关系的用户的设备。

/home/paas/user/device/list

当前版本 1.0.0

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
target	JSONObject	是	查询的目标用户，定义见“身份信息”。
pageInfo	JSONObject	否	分页查询参数，见“分页参数”定义。

出参

返回结果使用通用结果类型，data域是分页查询结果对象（下表中的data是分页结果中的数据），见下表的详细说明：

参数	类型	备注
data	JSONArray	分页数据，见设备信息定义。
total	Integer	总条数
pageNo	Integer	分页页码
pageSize	Integer	分页大小

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

用户ID：1111299939433

查询该用户的设备列表。

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "target": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "pageInfo":{
    "pageNo": 1,
    "pageSize": 20
  }
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "iotId": "tMbycP1picrKhT0HQDCk001034b510",
        "spaceNamePath": "/根节点1/",
        "attributeList": [
          {
            "iotId": "tMbycP1picrKhT0HQDCk001034b510",
            "gmtModified": 1547797068655,
            "attribute": "LightMode",
            "batchId": "ce354176212c47448b6a7e97e2c85705",
            "value": 0
          },
          {
            "iotId": "tMbycP1picrKhT0HQDCk001034b510",
            "gmtModified": 1548036653624,
            "attribute": "LightSwitch",
            "batchId": "188cde35f2544526b9660abfc60b4b6a",
            "value": 1
          }
        ],
        "thingType": "DEVICE",
        "productKey": "a1mB9mXoz0q",
        "deviceName": "fordev",
        "productName": "带服务的灯_qw",
        "status": 1,
        "productImage": "https://img.alicdn.com/tps/TB1_I0aPXXXXXajXpXXXXXXXXXX-100-82.png",
        "nickName": "dev1",
        "lastOnlineTime": "2019-01-01 12:00:00"
      }
    ],
    "total": 1,
    "pageNo": 1,
    "pageSize": 20
  }
}

查询设备的用户

查询与设备有逻辑关系的用户列表。

/home/paas/device/user/list

当前版本 1.0.1

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，扩展“身份信息”定义。
iotId	String	是	设备ID
pageQuery	JSONObject	否	分页查询参数，见“分页参数”定义。

出参

返回结果使用通用结果类型，data域是分页查询结果对象（下表中的data是分页结果中的数据），见下表的详细说明：

参数	类型	备注
data	JSONArray	分页数据，见身份信息定义。
total	Integer	总条数
pageNo	Integer	分页页码
pageSize	Integer	分页大小

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

要查询的设备ID为tMbycP1picrKhT0HQDCk001034b510。

查询第1页数据，每页最多20条记录。

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "iotId": "tMbycP1picrKhT0HQDCk001034b510",
  "pageQuery": {
    "pageNo":1,
    "pageSize":20
  }
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "hid": "1111299939433",
        "hidType": "OPEN"
      }
    ],
    "total": 1,
    "pageNo": 1,
    "pageSize": 20
  }
}

查询设备的用户（带角色）

查询与设备有逻辑关系的用户列表，用户信息上带有设备角色信息

  /home/paas/device/userrole/query

当前版本 1.0.0

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，扩展“身份信息”定义。
iotId	String	是	设备ID
pageQuery	JSONObject	否	分页查询参数，见“分页参数”定义。

出参

返回结果使用通用结果类型，data域是分页查询结果对象（下表中的data是分页结果中的数据），见下表的详细说明：

参数	类型	备注
data	JSONArray	分页数据，扩展身份信息增加role字段说明用户与设备的关系，取值DEVICE_MANAGER或DEVICE_MEMBER
total	Integer	总条数
pageNo	Integer	分页页码
pageSize	Integer	分页大小

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

要查询的设备ID为tMbycP1picrKhT0HQDCk001034b510。

查询第1页数据，每页最多20条记录。

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "iotId": "tMbycP1picrKhT0HQDCk001034b510",
  "pageQuery": {
    "pageNo":1,
    "pageSize":20
  }
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "hid": "1111299939433",
        "hidType": "OPEN",
        "role":"DEVICE_MANAGER"
      }
    ],
    "total": 1,
    "pageNo": 1,
    "pageSize": 20
  }
}