设备服务

更新时间：2019-03-06 09:40:29

概述

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

本文档整体分为两部分

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

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

接口分为四大类：

基本操作接口

接口名	简介
控制设备	实现设备的控制。可以获取设备属性、设备设备属性和执行服务。
获取设备TSL	获取设备的物模型。
查询设备	分页查询租户下的设备。
更新设备的备注名	更新设备的备注名。
重置设备	重置设备，解析所有关系和权限，并把设备从当前租户下移除。

用户与设备的相关接口

接口名	简介
绑定用户与设备	建立用户与设备的逻辑关系。
解绑用户与设备	解除用户与设备的逻辑关系。
查询用户的设备	查询用户的关联设备。
查询设备的用户	查询设备的关联用户。

设备与空间的相关接口

接口名	简介
绑定设备与空间	建立设备与空间的逻辑关系。
解绑设备与空间	解除设备与空间的逻辑关系。
查询空间的设备	查询空间下的关联设备。
获取设备的空间	获取设备的关联空间信息。

虚拟设备的相关接口

接口名	简介
绑定虚拟设备和空间	建立虚拟设备与空间的逻辑关系。
删除空间的虚拟设备	解除虚拟设备与空间的逻辑关系。
查询空间虚拟设备	查询空间下的关联虚拟设备。
替换空间虚拟设备	用真实设备替换空间下的虚拟设备。

数据定义

设备信息deviceInfo

名称	类型	备注
iotId	String	设备ID
productImage	String	设备的产品图片
deviceName	String	设备名DeviceName
nickName	String	用户对设备设置的昵称
productKey	String	设备ProductKey
productName	String	设备的产品名称
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"
  },
  "iotId": "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生成)"
        }
    ]

查询设备

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

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

/home/paas/device/list

当前版本 1.0.0

入参

参数	类型	必填	备注
operator	JSONObject	否	操作员，见“身份信息”定义。
pageQuery	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"
}

重置设备

实现云端设备重置。

设备的重置方式有三种：

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

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

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

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

主要流程有：

reset设备是否是网关设备

如果是网关设备

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

删除每个子设备的权限点

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

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

删除每个子设备的权限点

发送网关设备的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":[]
    }
  ]
}

绑定用户与设备

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

设备是已经完成配网的设备，见“设备配网接入”节的说明。配网后设备会自动和操作用户建立逻辑关系。

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

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

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

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

一个设备最多与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/list

当前版本 1.0.0

入参

参数	类型	必填	备注
operator	JSONObject	否	操作员，见“身份信息”定义。
target	JSONObject	是	查询的目标用户，定义见“身份信息”。
pageQuery	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"
  },
  "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
  }
}

查询设备的用户

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

/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/space/bind

当前版本 1.0.0

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
rootSpaceId	String	是	一级（顶层）空间ID
spaceId	String	是	需要做绑定的空间ID
iotIdList	JSONArray	是	需要做绑定的设备ID列表，每次请求最多绑定20个设备

出参

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

参数	类型	备注
successCount	Integer	成功绑定的设备数；
batchResultMap	JSONObject	以键值对的形式提供每个设备的绑定结果： key：设备ID；value：以通用结果类型表示设备ID的绑定结果。

示例

例：

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

要绑定的空间ID为9e944d47a67a40e89773d1365e048cf6。这个空间是根空间，所以rootSpaceId的值与spaceId相同。否则rootSpaceId为实际空间的根空间ID。

要绑定的设备ID为tMbycP1picrKhT0HQDCk001034b510。

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "rootSpaceId": "9e944d47a67a40e89773d1365e048cf6",
  "spaceId": "9e944d47a67a40e89773d1365e048cf6",
  "iotIdList": [
    "tMbycP1picrKhT0HQDCk001034b510"
  ]
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "batchResultMap": {
      "tMbycP1picrKhT0HQDCk001034b510": {
        "code": 200,
        "message": "success"
      }
    },
    "successCount": 1
  }
}

解绑设备与空间

解除设备与空间的逻辑关系。

设备与空间建立逻辑关系后，可以使用这个接口解除它们的关系。

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

解除一个空间与一个设备的逻辑关系；

解除一个空间与多个设备的逻辑关系。

/home/paas/device/space/unbind

当前版本 1.0.0

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
rootSpaceId	String	是	一级（顶层）空间ID
spaceId	String	是	需要做解绑的空间ID。
iotIdList	JSONArray	是	需要做解绑的目标设备ID列表，每次请求最多解绑20个设备。

出参

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

参数	类型	备注
successCount	Integer	成功解绑的设备数。
batchResultMap	JSONObject	以键值对的形式提供每个设备的绑定结果： key：设备ID；value：以通用结果类型表示设备ID的绑定结果。

示例

例：

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

要解绑的空间ID为9e944d47a67a40e89773d1365e048cf6。这个空间是根空间，所以rootSpaceId的值与spaceId相同。否则rootSpaceId为实际空间的根空间ID。

要解绑的设备ID为tMbycP1picrKhT0HQDCk001034b510。

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "rootSpaceId": "9e944d47a67a40e89773d1365e048cf6",
  "spaceId": "9e944d47a67a40e89773d1365e048cf6",
  "iotIdList": [
    "tMbycP1picrKhT0HQDCk001034b510"
  ]
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "batchResultMap": {
      "tMbycP1picrKhT0HQDCk001034b510": {
        "code": 200,
        "message": "success"
      }
    },
    "successCount": 1
  }
}

查询空间的设备

查询空间下的设备列表。

查询与空间建立了逻辑关系的设备。建立空间与设备的逻辑关系使用“绑定空间与设备”接口。

可以通过includeSubSpace参数指定是否包含空间下子空间的设备。

查询结果是一维的设备列表，不包含空间的结构关系。

/home/paas/space/device/list

当前版本 1.0.0

入参

参数	类型	必填	备注
operator	JSONObject	否	操作员，见“身份信息”定义。
rootSpaceId	String	是	一级（顶层）空间ID
spaceId	String	是	空间ID
includeSubSpace	Boolean	是	是否查询子空间的设备 True 查询子空间 False 不查询子空间
pageQuery	JSONObject	否	设备分页查询参数，见“分页参数”定义。

出参

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

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

示例

例：

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

要查询的空间ID为9e944d47a67a40e89773d1365e048cf6，要查询这个空间，以及子空间下的所有设备。

查询第1页数据，每页记录数为20。

接口返回1条记录，总记录数为1条。

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "rootSpaceId": "9e944d47a67a40e89773d1365e048cf6",
  "spaceId": "9e944d47a67a40e89773d1365e048cf6",
  "includeSubSpace": true,
  "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
  }
}

获取设备的空间

查询某根空间下与设备建立逻辑关系的空间列表。

/home/paas/device/space/get

当前版本 1.0.0

入参

参数	类型	必填	备注
operator	JSONObject	否	操作员，见“身份信息”定义。
rootSpaceId	String	是	一级（顶层）空间ID
iotId	String	是	设备ID

出参

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

参数	类型	备注
data	JSONObject	空间信息，见空间信息定义

示例

例：

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

根空间ID： 9e944d47a67a40e89773d1365e048cf6

设备ID： tMbycP1picrKhT0HQDCk001034b510

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "rootSpaceId": "9e944d47a67a40e89773d1365e048cf6",
  "iotId": "tMbycP1picrKhT0HQDCk001034b510"
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "spaceName": "根节点1",
    "attribute": "",
    "parentId": null,
    "description": "根节点1",
    "typeCode": "default",
    "typeName": "默认",
    "hasChild": 0,
    "hasDeviceChild": 1
  }
}

绑定虚拟设备和空间

虚拟设备相对于真实的物理设备而言，并不需要存在此类设备的实体。主要应用与人居的使用流程的解决方案。

例如： SI在后台portal的房屋内添加好虚拟设备，然后把房屋指派给施工人员，施工人员将真实的设备完成配网后，再将虚拟设备替换为真实设备，完成施工。

/home/paas/space/virtualdevice/bind

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
spaceId	String	是	空间id
deviceInfoList	JSONArray	是	产品定义

deviceInfoList定义

字段名	类型	是否必填	备注
productKey	String	是	产品标示
nickName	String	是	设备别名，比如床头灯1

出参

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

字段名	类型	备注
productKey	String	产品标示
nickName	String	设备别名
iotId	String	设备id
thingType	String	设备类型，虚拟设备为"VIRTUAL"

示例

例：

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

要绑定的空间ID为9e944d47a67a40e89773d1365e048cf6。

要绑定的设备的PK=a1aGFrtGWLw，nickName=风扇，iotId=EbtNIco8t2Ju9Q8h

请求参数如下：

请求示例

{
    "operator":{
        "hid":"1111299939433"
    },
    "deviceInfoList":[
        {
            "productKey":"a1aGFrtGWLw",
            "nickName":"xxx"
        }
    ],
    "spaceId":"9e944d47a67a40e89773d1365e048cf6"
}

返回示例

{
    "data":[
        {
            "productKey":"a1aGFrtGWLw",
            "nickName":"风扇",
            "iotId":"xxxx"
        }
    ]
}

删除空间的虚拟设备

该接口提供虚拟设备删除，不能删除真实设备。

/home/paas/space/virtualdevice/delete

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
iotIdList	JSONArray	是	虚拟设备id列表
spaceId	String	是	设备所在空间id

出参

IoT通用返回。

示例

例：

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

设备的空间ID为9e944d47a67a40e89773d1365e048cf6。

要删除的虚拟设备ID为EbtNIco8t2Ju9Q8h

请求参数如下：

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotIdList":[
        "EbtNIco8t2Ju9Q8h"
    ],
    "spaceId":"9e944d47a67a40e89773d1365e048cf6"
}

返回示例

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

查询空间虚拟设备

查询空间下的虚拟设备。

/home/paas/space/virtualdevice/list

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
spaceId	String	是	空间id
condition	JSONObject	是	查询条件

condition定义

字段名	类型	是否必填	备注
pageNo	Integer	是	页码，见“分页参数”定义。
pageSize	Integer	是	分页大小，见“分页参数”定义。
productKey	String	否	产品品类

出参

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

虚拟设备信息定义

名称	类型	备注
iotId	String	设备id
name	String	设备名
nickname	String	用户对设备设置的昵称
productKey	String	设备ProductKey

示例

例：

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

要查询的空间ID为9e944d47a67a40e89773d1365e048cf6。

请求参数如下：

请求示例

{
  "operator":{"hid":"1111299939433", "hidType":"OPEN"},
   "spaceId":"9e944d47a67a40e89773d1365e048cf6", 
  "condition":{
      "pageNo":1,
      "pageSize":20
  }
}

返回示例

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

替换空间虚拟设备

实际安装施工中，SI使用配网完成的设备去替换虚拟设备。完成一个从后台设计，到安装施工的过程。

替换设备会继承虚拟设备的设备别名。

/home/paas/space/virtualdevice/replace

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
iotId	String	是	实际设备，源设备
virtualIotId	String	是	虚拟设备，被替换设备
spaceId	String	是	空间id

出参

IoT通用返回。

示例

例：

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

要查询的空间ID为9e944d47a67a40e89773d1365e048cf6。

实际设备ID为lrSPldlWpr4maJyE

虚拟设备ID为EbtNIco8t2Ju9Q8h

请求参数如下：

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "spaceId":"9e944d47a67a40e89773d1365e048cf6",
    "virtualIotId":"EbtNIco8t2Ju9Q8h",
    "iotId":"lrSPldlWpr4maJyE"
}

返回示例

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