提供一组家空间相关的接口,您可以根据这些接口开发家、房间以及结合家房间的设备组、场景等相关功能。

创建家

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/create 1.0.1 创建家

说明

  • 首次创建家(创建第一个家)时,会自动进行数据订正(将老版本用户维度下的设备归属到新建的家下面)。
  • 单用户下最多支持创建10个家。
  • 单用户下家名称不允许重名。
  • 家的名称规则:支持字母、数字、空格和汉字,长度最大支持40个字符(中文算一个字符)。
  • 1.0.1 相比 1.0.0 版本,不再支持创建默认房间,请使用 /living/home/room/create 接口创建房间。

请求参数

参数 类型 必填 描述
name String 家的名称

返回参数

参数 类型 描述
data String 家的id,家的唯一标识

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.1"
        },
        "params":{
            "name":"我的家"
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":"50f5op1556f6xxxxa4f2f28104512"
    }

删除家

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/delete 1.0.0 删除家

说明

  • 单用户下至少保留1个家。
  • 删除家,会自动解绑当前家下的所有设备。

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识

返回参数

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op15xxxx4f2f28104512"
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":null
    }

更新家的基本信息

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/update 1.0.0 更新家的基本信息

说明

  • 允许更新家的名称。
  • 家的名称不允许重名。
  • 家的名称规则:支持字母、数字、空格和汉字,长度最大支持40个字符(中文算一个字符)。

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
name String 家的名称

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op1556xxxx2f28104512",
            "name":"我的家"
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":null
    }

设置用户当前所在的家

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/current/update 1.0.0 设置用户当前所在的家

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op155xxxxa4f2f28104512"
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":null
    }

获取家的详情

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/get 1.0.1 获取家的详情

请求参数

参数 类型 必填 描述
homeId String 家id,家的唯一标识

返回参数

参数 类型 描述
homeId String 家id,家的唯一标识
name String 家的名称
myRole String 用户和家的关系
  • ADMIN
  • MEMBER
currentHome Boolean 表示该home是否为用户当前所在的家
roomCnt Integer 家的房间总数
deviceCnt Integer 家的设备总数
deviceOnlineCnt Integer 家的设备在线数
createMillis Long 家的创建时间,UNIX时间戳,单位为ms

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.1"
        },
        "params":{
            "homeId":"50f5op155xxxx4f2f28104512"
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":{
            "homeId":"50f5op1556f6xxxxa4f2f28104512",
            "name":"我的家",
            "myRole":"ADMIN",
            "currentHome":false,
            "roomCnt":10,
            "deviceCnt":36,
            "deviceOnlineCnt":12,
            "createMillis":1569232952000
        }
    }

获取家的列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/query 1.0.0 获取家的列表

请求参数

参数 类型 必填 描述
pageNo Integer 分页页码,从1开始
pageSize Integer 分页大小,大于等于1,小于等于20

返回参数

参数 子参数 类型 描述
total - Long 满足条件的家总数
pageNo - Integer 分页页码
pageSize - Integer 分页大小
data - JSONArray 家的详情列表
- homeId String 家id,家的唯一标识
- name String 家的名称。
- myRole String 用户和家的关系
  • ADMIN
  • MEMBER
- currentHome Boolean 表示该home是否为用户当前所在的家
- createMillis Long 家的创建时间,UNIX时间戳,单位为ms

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "pageNo":1,
            "pageSize":10
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":{
            "total":1,
            "pageNo":1,
            "pageSize":10,
            "data":[
                {
                    "homeId":"50f5op1556xxxxf2f28104512",
                    "name":"我的家",
                    "myRole":"ADMIN",
                    "currentHome":true,
                    "createMillis":1569232952000
                }
            ]
        }
    }

获取家的元素(设备或者设备组)列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/element/query 1.0.2 获取家的全部设备下的元素(设备或者设备组)列表

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
elementType String 元素类型,可取值:DEVICE、CONTROL_GROUP
propertyIdentifiers List < String > 物模型的identifier,用于获取物模型的当前状态
pageNo Integer 分页页码,从1开始
pageSize Integer 分页大小,大于等于1,小于等于20

返回参数

参数 子参数 类型 描述
total - Long 满足条件的元素总数
pageNo - Integer 分页页码
pageSize - Integer 分页大小
items - JSONArray 满足条件的元素详情列表
- elementType String 元素类型
  • DEVICE
  • CONTROL_GROUP
- elementId String 元素(设备或者设备组)id,元素的唯一标识
- name String 元素(设备或者设备组)名称
- roomId String 设备所在房间的id,elementType为DEVICE时有效
- roomName String 设备所在房间的名称,elementType为DEVICE时有效
- productKey String 元素(设备或者设备组)所属产品的ProductKey
- productName String 元素(设备或者设备组)所属产品的名称,elementType为DEVICE时有效
- productImage String 设备所属产品的图标,如果未定义产品图标,该字段和categoryImage字段一致
- productModel String 设备所属产品的型号,elementType为DEVICE时有效
- categoryKey String 设备所属产品的品类key,elementType为DEVICE时有效
- categoryImage String 设备所属产品品类的图标,elementType为DEVICE时有效
- panelPageRouterUrl String 设备所属产品品类的面板页面路由URL。elementType为DEVICE且categroyKey为Camera时有效
- nickName String 设备的昵称,elementType为DEVICE时有效,可为空
- netType String 设备的入网类型,elementType为DEVICE时有效
- thingType String 设备的类型,elementType为DEVICE时有效
  • VIRTUAL
  • WEB
  • APP
  • DEVICE
- status Integer 设备的状态,elementType为DEVICE时有效
  • 0:未激活
  • 1:在线
  • 3:离线
  • 8:禁用
- nodeType String 设备的节点类型,elementType为DEVICE时有效
  • DEVICE
  • GATEWAY
- description String 设备的描述,elementType为DEVICE时有效
- deviceCnt Integer 归属设备组的设备总数,elementType设置为CONTROL_GROUP时有效
- deviceOnlineCnt Integer 归属设备组的设备在线数,elementType设置为CONTROL_GROUP时有效
- propertyList List < DeviceProperty > 设备的TSL属性状态列表

DeviceProperty数据结构说明:

名称 类型 描述
identifier String 物模型属性的标识符。
name String 物模型属性的名称。
value String 物模型属性当前状态值。
dataType String 物模型属性值的类型。
imageUrl String 物模型属性的图标 URL。

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.2"
        },
        "params":{
            "homeId":"50f5op1556fxxxxxf2f28104512",
            "propertyIdentifiers":[
                "LightSwitch"
            ],
            "pageNo":1,
            "pageSize":10
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":{
            "total":2,
            "pageNo":1,
            "pageSize":10,
            "items":[
                {
                    "elementType":"DEVICE",
                    "elementId":"edwB6Tqxxxxa000100",
                    "deviceName":"摄像头1",
                    "productKey":"产品 pk",
                    "productName":"产品名称",
                    "productImage":"产品图片 URL",
                    "productModel":"产品型号",
                    "categoryKey":"Camera",
                    "categoryImage":"xxx",
                    "panelPageRouterUrl":"xxx",
                    "nickName":"设备昵称",
                    "netType":"NET_WIFI",
                    "thingType":"DEVICE",
                    "status":1,
                    "nodeType":"DEVICE",
                    "description":"设备描述",
                    "propertyList":[
                        {
                            "identifier":"LightSwitch",
                            "name":"电源开关",
                            "value":"0",
                            "dataType":"BOOL",
                            "imageUrl":""
                        }
                    ]
                },
                {
                    "elementType":"GROUP",
                    "elementId":"bc04e8c1dxxxxb696e6a5",
                    "name":"摄像头组",
                    "productKey":"产品 pk",
                    "productImage":"产品图片 URL",
                    "propertyList":[
                        {
                            "identifier":"LightSwitch",
                            "name":"电源开关",
                            "value":"0",
                            "dataType":"BOOL",
                            "imageUrl":""
                        }
                    ]
                }
            ]
        }
    }

移动家的全部设备下元素(设备或者设备组)的顺序

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/element/reorder 1.0.0 移动家的全部设备下元素(设备或者设备组)的顺序

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
elementId String 元素id,元素的唯一标识
targetOrder Integer 元素的目标位置,从0开始

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op155xxxxca4f2f28104512",
            "elementId":"elementId",
            "targetOrder":0
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":null
    }

获取家下的设备列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/device/query 1.0.0 获取家下的设备列表,支持多维度检索。

请求参数

参数 类型 必填 描述
deviceNodeType String 根据设备节点类型过滤
  • DEVICE
  • GATEWAY
productKey String 产品的productKey
categoryKey String 产品的品类key
homeId String 家的id,家的唯一标识,用于过滤归属在某一个家的设备列表
roomId String 房间的id,房间的唯一标识,用于过滤归属在某一个房间的设备列表
excludedHomeId String 家的id,家的唯一标识,用于过滤未归属在某一个家的设备列表
excludedRoomId String 房间的id,房间的唯一标识,用于过滤未归属在某一个房间的设备列表
boundControlGroup Boolean 设备组的绑定状态
  • true:已绑定设备组
  • false:未绑定设备组
propertyIdentifiers List < String > 物模型的identifier,用于获取物模型的当前状态
pageNo Integer 分页页码,从1开始
pageSize Integer 分页大小,大于等于1,小于等于50

返回参数

参数 子参数 类型 描述
total - Long 满足条件的设备总数
pageNo - Integer 分页页码
pageSize - Integer 分页大小
data - JSONArray 设备的详情列表
- iotId String 设备的iotId,设备的唯一标识
- deviceName String 设备的名称
- homeId String 设备所在家的id
- homeName String 设备所在家的名称
- roomId String 设备所在房间的id
- roomName String 设备所在房间的名称
- productKey String 设备所属产品的ProductKey
- productName String 设备所属产品的名称
- productImage String 设备所属产品的图标,如果未定义产品图标,该字段和categoryImage字段一致
- productModel String 设备所属产品的型号
- categoryKey String 设备所属产品的品类key
- categoryImage String 设备所属产品品类的图标
- panelPageRouterUrl String 设备所属产品品类的面板页面路由URL,categroyKey为Camera时有效
- nickName String 设备的昵称,可为空
- netType String 设备的入网类型
- thingType String 设备的类型
  • VIRTUAL
  • WEB
  • APP
  • DEVICE
- status Integer 设备的状态
  • 0:未激活
  • 1:在线
  • 3:离线
  • 8:禁用
- nodeType String 设备的节点类型
  • DEVICE
  • GATEWAY
- description String 设备的描述
- subDeviceIotIdList List < String > 绑定该用户的网关子设备列表,nodeType为GATEWAY时有效
- propertyList List < DeviceProperty > 设备的TSL属性状态列表

DeviceProperty数据结构说明

名称 类型 描述
identifier String 物模型属性的标识符
name String 物模型属性的名称
value String 物模型属性当前状态值
dataType String 物模型属性值的类型
imageUrl String 物模型属性的图标URL

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "boundControlGroup":false,
            "pageNo":1,
            "pageSize":10
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":{
            "total":2,
            "pageNo":1,
            "pageSize":10,
            "data":[
                {
                    "iotId":"edwB6Tqxxxx00100",
                    "myRole":"OWNED",
                    "deviceName":"摄像头1",
                    "homeId":"50f5op1556f6xxxx2f28104512",
                    "homeName":"我的家",
                    "roomId":"50f5op1556fxxxxf2f28104517",
                    "roomName":"Xbox 游戏室",
                    "productKey":"产品 pk",
                    "productName":"产品名称",
                    "productImage":"产品图片",
                    "productModel":"产品型号",
                    "categoryKey":"Camera",
                    "categoryImage":"xxx",
                    "panelPageRouterUrl":"xxx",
                    "nickName":"设备昵称",
                    "netType":"NET_WIFI",
                    "thingType":"DEVICE",
                    "status":1,
                    "nodeType":"DEVICE",
                    "description":"设备描述",
                    "subDeviceIotIdList":[
                        "xadqsxxxxL89h000100"
                    ],
                    "propertyList":[
                        {
                            "identifier":"LightSwitch",
                            "name":"电源开关",
                            "value":"0",
                            "dataType":"BOOL",
                            "imageUrl":""
                        }
                    ]
                },
                {
                    "iotId":"xadqskpxxxx000100",
                    "myRole":"OWNED",
                    "deviceName":"摄像头2",
                    "homeId":"50f5op1556xxxxca4f2f28104512",
                    "homeName":"我的家",
                    "roomId":"50f5op155xxxxf2f28104517",
                    "roomName":"Xbox 游戏室",
                    "productKey":"产品 pk",
                    "productName":"产品名称",
                    "productImage":"产品图片",
                    "productModel":"产品型号",
                    "categoryKey":"Camera",
                    "categoryImage":"xxx",
                    "panelPageRouterUrl":"xxx",
                    "nickName":"设备昵称",
                    "netType":"NET_WIFI",
                    "thingType":"DEVICE",
                    "status":1,
                    "nodeType":"DEVICE",
                    "description":"设备描述",
                    "propertyList":[
                        {
                            "identifier":"LightSwitch",
                            "name":"电源开关",
                            "value":"0",
                            "dataType":"BOOL",
                            "imageUrl":""
                        }
                    ]
                }
            ]
        }
                                }

移动家下设备的顺序

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/device/reorder 1.0.0 移动家下设备的顺序

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
iotId String 设备的 iotId。如果productKey和deviceName字段为空,该字段必填。如果iotId,productKey和deviceName都不为空,以iotId作为设备的唯一标识
productKey String 设备所属产品的 productKey。如果 iotId 字段为空,该字段必填
deviceName String 设备的名称。如果 iotId 字段为空,该字段必填
targetOrder Integer 房间的目标位置,从 0 开始

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op1556f6xxxxa4f2f28104512",
            "iotId":"edwB6TxxxxNa000100",
            "targetOrder":2
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":""
    }

创建房间

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/room/create 1.0.1 创建房间

说明

  • 单个家下最多支持创建20个房间。
  • 单个家下房间名称不允许重名。
  • 房间的名称规则:支持字母、数字、空格和汉字,长度最大支持20个字符(中文算一个字符)。

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
name String 房间的名称
backgroudImage String 房间的背景图标

返回参数

参数 类型 描述
data String 房间id,房间的唯一标识

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.1"
        },
        "params":{
            "homeId":"50f5op1556xxxxa4f2f28104512",
            "name":"Xbox 游戏室"
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":"50f5op1556f6xxxxa4f2f28104516"
    }

删除房间

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/room/delete 1.0.0 删除房间

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
roomId String 房间的id,房间的唯一标识

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op15xxxxbca4f2f28104512",
            "roomId":"50f5op1556f6xxxxca4f2f28104517"
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":null
    }

更新房间的基本信息

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/room/update 1.0.1 更新房间的基本信息

说明

  • 允许更新房间的名称。
  • 单个家下房间名称不允许重名。
  • 房间的名称规则:支持字母、数字、空格和汉字,长度最大支持20个字符(中文算一个字符)。

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
roomId String 房间的id,房间的唯一标识
name String 房间的名称
backgroudImage String 房间的背景图标

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.1"
        },
        "params":{
            "homeId":"50f5op15xxxx5bca4f2f28104512",
            "roomId":"50f5op1556fxxxxa4f2f28104517",
            "name":"Switch 游戏室"
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":null
    }

获取房间的详情

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/room/get 1.0.1 获取房间的详情

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
roomId String 房间的id,房间的唯一标识

返回参数

参数 类型 描述
roomId String 房间的id,房间的唯一标识
name String 房间的名称
backgroudImage String 房间的背景图标
deviceCnt Integer 房间的设备总数
deviceOnlineCnt Integer 房间的设备在线数
createMillis Long 房间的创建时间,UNIX时间戳,单位为ms

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.1"
        },
        "params":{
            "homeId":"50f5op1xxxxa4f2f28104512",
            "roomId":"50f5op1556fxxxx4f2f28104517"
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":{
            "roomId":"50f5op1556f6xxxxa4f2f28104517",
            "name":"房间名称",
            "backgroudImage":"https://www.aliyundoc.com/***.png",
            "deviceCnt":10,
            "deviceOnlineCnt":7,
            "createMillis":1569232952000
        }
    }

获取家的房间列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/room/query 1.0.1 获取家的房间列表

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
pageNo Integer 分页页码,从1开始
pageSize Integer 分页大小,大于等于1,不大于20

返回参数

参数 子参数 类型 描述
total - Long 满足条件的房间总数
pageNo - Integer 分页页码
pageSize - Integer 分页大小
items - JSONArray 房间的详情列表
- roomId String 房间的id,房间的唯一标识
- name String 房间的名称
- backgroudImage String 房间的背景图标
- deviceCnt Integer 归属于该房间的设备总数
- deviceOnlineCnt Integer 房间的设备在线数
- createMillis Long 房间的创建时间,UNIX时间戳,单位为ms

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.1"
        },
        "params":{
            "homeId":"50f5op1556xxxxca4f2f28104512",
            "pageNo":1,
            "pageSize":10
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":{
            "total":2,
            "pageNo":1,
            "pageSize":10,
            "items":[
                {
                    "roomId":"50f5op1556xxxxca4f2f28104516",
                    "name":"Xbox 游戏室",
                    "deviceCnt":10,
                    "createMillis":1569232952000
                },
                {
                    "roomId":"50f5op15xxxxd5bca4f2f28104517",
                    "name":"Switch 游戏室",
                    "deviceCnt":6,
                    "createMillis":1569232957000
                }
            ]
        }
    }

获取房间的设备列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/room/device/query 1.0.0 获取房间的设备列表

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
roomId String 房间的id,房间的唯一标识
propertyIdentifiers List < String > 物模型的identifier,用于获取物模型的当前状态
pageNo Integer 分页页码,从1开始
pageSize Integer 分页大小,大于等于1,小于等于50

返回参数

参数 子参数 类型 描述
total - Long 满足条件的设备总数
pageNo - Integer 分页页码
pageSize - Integer 分页大小
data - JSONArray 设备的详情列表
- iotId String 设备的iotId,设备的唯一标识
- deviceName String 设备的名称
- homeId String 设备所在家的id
- homeName String 设备所在家的名称
- roomId String 设备所在房间的id
- roomName String 设备所在房间的名称
- productKey String 设备所属产品的ProductKey
- productName String 设备所属产品的名称
- productImage String 设备所属产品的图标,如果未定义产品图标,该字段和categoryImage字段一致
- productModel String 设备所属产品的型号
- categoryKey String 设备所属产品的品类
- categoryImage String 设备所属产品品类的图标key
- panelPageRouterUrl String 设备所属产品品类的面板页面路由URL,categroyKey为Camera时有效
- nickName String 设备的昵称,可为空
- netType String 设备的入网类型
- thingType String 设备的类型
  • VIRTUAL
  • WEB
  • APP
  • DEVICE
- status Integer 设备的状态
  • 0:未激活
  • 1:在线
  • 3:离线
  • 8:禁用
- nodeType String 设备的节点类型
  • DEVICE
  • GATEWAY
- description String 设备的描述
- propertyList List < DeviceProperty > 设备的TSL属性状态列表

DeviceProperty数据结构说明:

名称 类型 描述
identifier String 物模型属性的标识符
name String 物模型属性的名称
value String 物模型属性当前状态值
dataType String 物模型属性值的类型
imageUrl String 物模型属性的图标URL

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op155xxxxxa4f2f28104512",
            "roomId":"50f5op155xxxx5bca4f2f28104517",
            "pageNo":1,
            "pageSize":10
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":{
            "total":1,
            "pageNo":1,
            "pageSize":10,
            "data":[
                {
                    "iotId":"edwB6TqvxxxxNa000100",
                    "deviceName":"摄像头1",
                    "homeId":"50f5op1556f6xxxx2f28104512",
                    "homeName":"我的家",
                    "roomId":"50f5op1556f65xxxx28104517",
                    "roomName":"Xbox 游戏室",
                    "productKey":"产品 pk",
                    "productName":"产品名称",
                    "productImage":"产品图片 URL",
                    "productModel":"产品型号",
                    "categoryKey":"Camera",
                    "categoryImage":"xxx",
                    "panelPageRouterUrl":"xxx",
                    "nickName":"设备昵称",
                    "netType":"NET_WIFI",
                    "thingType":"DEVICE",
                    "status":1,
                    "nodeType":"DEVICE",
                    "description":"设备描述",
                    "propertyList":[
                        {
                            "identifier":"LightSwitch",
                            "name":"电源开关",
                            "value":"0",
                            "dataType":"BOOL",
                            "imageUrl":""
                        }
                    ]
                }
            ]
        }
    }

移动房间下设备的顺序

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/room/device/reorder 1.0.0 移动房间下设备的顺序

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
roomId String 房间的id,房间的唯一标识
iotId String 设备的iotId,设备的唯一标识
targetOrder Integer 设备的目标位置,从0开始

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op155xxxxca4f2f28104512",
            "roomId":"50f5op1556fxxxx4f2f28104517",
            "iotId":"edwB6Tqvxxxxa000100",
            "targetOrder":0
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":null
    }

移动家下房间的顺序

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/room/reorder 1.0.0 移动家下房间的顺序

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
roomId String 房间的 id,房间的唯一标识
targetOrder Integer 房间的目标位置,从 0 开始

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op1556f6xxxxa4f2f28104512",
            "roomId":"50f5op1556f6xxxxa4f2f28104516",
            "targetOrder":2
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":""
    }

家下房间的顺序调整

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/room/order/refresh 1.0.0 家下房间的顺序调整

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
roomIdList List < String > roomId列表

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op155xxxxa4f2f28104512",
            "roomIdList":[
                "2656fd48b1xxxx598a5ced85",
                "2656fd4xxxxd598a5ced87"
            ]
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":null
    }

移动设备

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/device/move 1.0.0 移动设备

说明

  • 支持跨家移动设备。
  • 支持跨房间移动设备。
  • 支持从房间中移出设备。

请求参数

参数 子参 类型 必填 描述
homeId - String 待移动目标家的 id,家的唯一标识
roomId - String 待移动房间的 id,房间的唯一标识。如果 homeId 为空,设备(deviceList)会归属在 homeId 的全部设备列表中
deviceList - JSONArray 待移动的设备列表,最大支持100个设备
- iotId String 设备的 iotId。如果productKey和deviceName字段为空,该字段必填。如果 iotId、productKey和deviceName都不为空,以iotId作为设备的唯一标识
- productKey String 设备所属产品的 productKey。如果iotId字段为空,该字段必填
- deviceName String 设备的名称。如果iotId字段为空,该字段必填

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op1556f6xxxxa4f2f281045102",
            "roomId":"50f5op1556f6xxxxa4f2f28104516",
            "deviceList":[
                {
                    "iotId":"edwB6TxxxxNa000100"
                }
            ]
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":""
    }

房间的设备更新

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/room/device/full/update 1.0.0 房间的设备更新

说明

  • 支持设备的增加,删除和排序。
  • 该接口支持跨家移动和跨房间移动设备。
  • 单个房间最多添加100个设备。

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
roomId String 房间的id,房间的唯一标识
iotIdList List < String > 设备iotId列表

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5oxxxxa4f2f28104512",
            "roomId":"50f5op15xxxxbca4f2f28104517",
            "iotIdList":[
                "xadqskxxxx000100",
                "UfPAmFxxxx6OF000100"
            ]
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":null
    }

创建设备组

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/controlgroup/create 1.0.1 创建设备组

说明

  • 单个家下最多支持创建20个设备组。
  • 单个家下设备组名称不允许重名。
  • 设备组的名称规则:支持字母、数字、空格和汉字,长度最大支持60个字符(中文算一个字符)。
  • 单个设备组下最少2个设备,最多100个设备。
  • 一个设备只能添加到一个设备组。
  • 必须同一个productKey下的设备才能组建设备组。
  • 目前只支持“灯”和“插座”两个品类。

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
name String 设备组的名称
productKey String 设备组所属产品的productKey
iotIdList List < String > 设备的iotId列表

返回参数

参数 类型 描述
data String 设备组的id,设备组的唯一标识

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.1"
        },
        "params":{
            "homeId":"50f5op15xxxxa4f2f28104512",
            "name":"球泡灯组",
            "productKey":"a1xxxxsk",
            "iotIdList":[
                "xadqskpxxxxL89h000100",
                "UfPAmxxxxW6OF000100"
            ]
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":"bc04e8c1d4xxxxeb696e6a5"
    }

删除设备组

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/controlgroup/delete 1.0.0 删除设备组

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
controlGroupId String 设备组的id,设备组的唯一标识

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op155xxxxa4f2f28104512",
            "controlGroupId":"bc04e8xxxxa5eb696e6a5"
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":null
    }

批量删除设备组

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/controlgroup/batch/delete 1.0.0 批量删除设备组

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
controlGroupIdList List < String > 设备组ID列表

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op1xxxxca4f2f28104512",
            "controlGroupIdList":[
                "bc04e8c1xxxx5eb696e6a5",
                "bc04exxxxa5eb696e6a7"
            ]
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":null
    }

更新设备组的基本信息

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/controlgroup/update 1.0.0 更新设备组的基本信息

说明

  • 允许更新设备组的名称。
  • 单个家下设备组的名称不允许重名。
  • 设备组的名称规则:支持字母、数字、空格和汉字,长度最大支持60个字符(中文算一个字符)。

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
controlGroupId String 设备组的id,设备组的唯一标识
name String 设备组的名称

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op1556fxxxx2f28104512",
            "controlGroupId":"bc04e8c1xxxx9a5eb696e6a5",
            "name":"球泡灯组"
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":null
    }

获取设备组的详情

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/controlgroup/get 1.0.1 获取设备组的详情

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
controlGroupId String 设备组id,设备组的唯一标识

返回参数

参数 类型 描述
controlGroupId String 设备组id,设备组的唯一标识
name String 设备组的名称
productKey String 设备组所属产品的productKey
productImage String 设备组所属产品的图标,如果未定义产品图标,该字段和categoryImage字段一致
createMillis Long 设备组的创建时间,UNIX时间戳,单位为ms

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.1"
        },
        "params":{
            "homeId":"50f5opxxxx5bca4f2f28104512",
            "controlGroupId":"bc04exxxx59a5eb696e6a5"
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":{
            "controlGroupId":"bc04e8xxxxb696e6a5",
            "name":"球泡灯组",
            "productKey":"a1xxxxsk",
            "productImage":"xxx",
            "createMillis":1569232952000
        }
    }

获取家的设备组列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/controlgroup/query 1.0.1 获取家的设备组列表

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
pageNo Integer 分页页码,从1开始
pageSize Integer 分页大小,大于等于1,小于等于20

返回参数

参数 子参数 类型 描述
total - Long 满足条件的设备组总数
pageNo - Integer 分页页码
pageSize - Integer 分页大小
data - JSONArray 设备组的详情列表
- controlGroupId String 设备组的id,设备组的唯一标识
- name String 设备组的名称
- productKey String 设备组所属产品的productKey
- productImage String 设备组所属产品的图标,如果未定义产品图标,该字段和categoryImage字段一致
- createMillis Long 设备组的创建时间,UNIX时间戳,单位为ms

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.1"
        },
        "params":{
            "homeId":"50f5op1556xxxx104512",
            "pageNo":1,
            "pageSize":10
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":{
            "total":2,
            "pageNo":1,
            "pageSize":10,
            "data":[
                {
                    "controlGroupId":"bc04e8cxxxx5eb696e6a5",
                    "name":"球泡灯组",
                    "productKey":"a1Uxxxxsk",
                    "parductImage":"xxx",
                    "createMillis":1569232952000
                },
                {
                    "controlGroupId":"bc04exxxx5eb696e6a7",
                    "name":"插座灯组",
                    "productKey":"a1xxxxvj",
                    "parductImage":"xxx",
                    "createMillis":1569232952000
                }
            ]
        }
    }

获取设备组的设备列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/controlgroup/device/query 1.0.2 获取设备组的设备列表

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
controlGroupId String 设备组的id,设备组的唯一标识
propertyIdentifiers List < String > 用于过滤设备TSL属性运行态数据的标识符 identifier
pageNo Integer 分页页码,从1开始
pageSize Integer 分页大小,取值范围:1~20

返回参数

参数 子参数 类型 描述
total - Long 满足条件的设备总数
pageNo - Integer 分页页码
pageSize - Integer 分页大小
items - JSONArray 设备的详情列表
- iotId String 设备的iotId,设备的唯一标识
- deviceName String 设备的名称
- productKey String 设备所属产品的ProductKey
- productName String 设备所属产品的名称
- productImage String 设备所属产品的图标,如果未定义产品图标,该字段和categoryImage字段一致
- productModel String 设备所属产品的型号
- categoryKey String 设备所属产品的品类key
- categoryImage String 设备所属产品品类的图标
- nickName String 设备的昵称,可为空
- netType String 设备的入网类型
- thingType String 设备的类型
  • VIRTUAL
  • WEB
  • APP
  • DEVICE
- status Integer 设备的状态
  • 0:未激活
  • 1:在线
  • 3:离线
  • 8:禁用
- nodeType String 设备的节点类型
  • DEVICE
  • GATEWAY
- description String 设备的描述

DeviceProperty数据结构说明:

名称 类型 描述
identifier String 物模型属性的标识符
name String 物模型属性的名称
value String 物模型属性当前状态值
dataType String 物模型属性值的类型
imageUrl String 物模型属性的图标URL

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.2"
        },
        "params":{
            "homeId":"50f5op1556f6xxxxa4f2f28104512",
            "controlGroupId":"bc04e8c1xxxxeb696e6a5",
            "propertyIdentifiers":[
                "LightSwitch"
            ],
            "pageNo":1,
            "pageSize":10
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":{
            "total":1,
            "pageNo":1,
            "pageSize":10,
            "items":[
                {
                    "iotId":"edwB6TxxxxNa000100",
                    "deviceName":"摄像头1",
                    "productKey":"产品 pk",
                    "productName":"产品名称",
                    "productImage":"产品图片 URL",
                    "productModel":"产品型号",
                    "categoryKey":"Camera",
                    "categoryImage":"xxx",
                    "panelPageRouterUrl":"xxx",
                    "roomId":"50f5op1556f6xxxxa4f2f28104516",
                    "roomName":"xBox游戏室",
                    "nickName":"设备昵称",
                    "netType":"NET_WIFI",
                    "thingType":"DEVICE",
                    "status":1,
                    "nodeType":"DEVICE",
                    "description":"设备描述",
                    "propertyList":[
                        {
                            "identifier":"LightSwitch",
                            "name":"电源开关",
                            "value":"0",
                            "dataType":"BOOL",
                            "imageUrl":""
                        }
                    ]
                }
            ]
        }
    }

设备组的设备更新

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/controlgroup/device/full/update 1.0.0 更新设备组内的设备列表

说明

  • 支持设备的增加,删除和排序。
  • 单个设备组下最少2个设备,最多100个设备。
  • 一个设备只能添加到一个设备组。
  • 必须同一个 productKey 下的设备才能组建设备组。

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
controlGroupId String 设备组的id,设备组的唯一标识
iotIdList List < String > 设备iotId列表

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op155xxxxxbca4f2f28104512",
            "controlGroupId":"bc04exxxxf59a5eb696e6a5",
            "iotIdList":[
                "xadqskxxxx89h000100",
                "UfPxxxxW6OF000100"
            ]
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":null
    }

获取可创建设备组的产品列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/controlgroup/product/query 1.0.1 获取可创建设备组的产品列表

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
pageNo Integer 分页页码,从1开始
pageSize Integer 分页大小,取值范围:1~50

返回参数

参数 子参数 类型 描述
total - Long 满足条件的产品总数
pageNo - Integer 分页页码
pageSize - Integer 分页大小
data - JSONArray 产品的详情列表
- productKey String 产品的 productKey
- productName String 产品的名称
- productImage String 产品的图标,如果未定义产品图标,该字段和categoryImage字段一致

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.1"
        },
        "params":{
            "homeId":"50f5op1xxxxa4f2f28104512"
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":{
            "total":2,
            "pageNo":1,
            "pageSize":50,
            "data":[
                {
                    "productKey":"a1xxxxvsk",
                    "productName":"球泡灯",
                    "productImage":"xxx"
                },
                {
                    "productKey":"a1bxxxxvj",
                    "productName":"插座",
                    "productImage":"xxx"
                }
            ]
        }
    }

移动家下设备组的顺序

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/home/controlgroup/reorder 1.0.0 移动家下设备组的顺序

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
controlGroupId String 设备组的 id,设备组的唯一标识
targetOrder Integer 设备组的目标位置,从 0 开始

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "homeId":"50f5op1556f6xxxxa4f2f28104512",
            "controlGroupId":"50f5op1556f6xxxxa4f2f28104516",
            "targetOrder":2
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":""
    }

设置设备组属性

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/controlgroup/properties/set 1.0.1 设置设备组的属性

请求参数

参数 类型 必填 描述
controlGroupId String 设备组id,设备组的唯一标识
items JSON 属性信息,组成为key:value,数据格式为 JSON;key为属性的标识符(identifier),类型为String,value为属性值,类型为Object

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.1"
        },
        "params":{
            "controlGroupId":"bc04e8cxxxxeb696e6a5",
            "items":{
                "PowerSwitch":1,
                "Temperature":20
            }
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":""
    }

设备组调用服务

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/controlgroup/service/invoke 1.0.1 设备组调用服务

请求参数

参数 类型 必填 描述
controlGroupId String 设备组id,设备组的唯一标识
identifier String 服务的标识符
args JSON 服务的参数,组成为 key:value,数据格式为JSON。key的类型为String,value的类型为Object

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.1"
        },
        "params":{
            "controlGroupId":"bc04xxxx1284f59a5eb696e6a5",
            "identifier":"executeAction",
            "args":{
                "action":"POWER"
            }
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":""
    }

在家中创建场景

定义描述

path 版本 描述 是否需要登录
/living/scene/create 1.0.1 在家中创建场景。
说明

目前平台提供了家空间管理服务,可以使用相关API搭建自有App的家空间模型。场景服务也对家空间进行了相应支持,提供了管理家中场景的能力。

您一旦使用家空间服务为App用户创建了家,App用户之前创建的场景就会归属于这个家下。此时,App用户需要使用家场景接口方可管理场景。以下接口不能访问家空间中的场景:

  • /scene/create
  • /scene/info/get

请求参数

参数 类型 必填 描述
homeId String 场景所在家的唯一标识
catalogId String 用于对场景进行分类
  • 0表示手动场景,只包含action场景
  • 1表示自动场景,包含Trigger和Condition的场景
enable Boolean 是否在创建时启用场景,true表示启用,false表示停用
name String 用户给场景起的名称
description String 对场景的描述
icon String 场景图标的下载链接
iconColor String 场景图标色,例如#FFFFFF
triggers JSON Object IFTTT 规则的trigger对象
conditions JSON Object IFTTT规则的condition对象
caConditions JSON Array CA规则的condition对象
actions JSON Array action对象
sceneType String 场景规则类型,可取值为:IFTTT和CA,缺省值为IFTTT
mode String CA规则的模式
  • all

    caConditions中的条件全部满足时, 才会执行action中的内容

  • any

    caConditions中的任何一个条件被满足,就会执行action中的内容

返回参数

参数 类型 描述
sceneId String 创建的场景Id

请求示例

​{
    "homeId": "testHomeId"
    "catalogId":"1",
    "enable":true,
    "name":"testScene",
    "icon":"http://www.aliyundoc.com/***.png",
    "iconColor":"#FFFFFF",
    "caConditions":[
        {
            "params":{
                "cron":"42 00 * * *",
                "cronType":"linux",
                "timezoneId":"Asia/Shanghai"
            },
            "uri":"condition/timer"
        },
        {
            "params":{
                "compareValue":0,
                "compareType":"==",
                "propertyName":"PowerSwitch",
                "productKey":"xxxx",
                "deviceName":"xxxx"
            },
            "uri":"condition/device/property"
        }
    ],
    "actions":[
        {
            "params":{
                "iotId":"xxxx",
                "propertyName":"PowerSwitch",
                "propertyValue":1
            },
            "uri":"action/device/setProperty"
        }
    ],
    "sceneType":"CA",
    "mode":"all"
}​

返回示例

​{
    "code": 200,
    "data": "sceneId",
    "message": "success"
}​

更新家中场景

定义描述

path 版本 描述 是否需要登录
/living/scene/update 1.0.0 更新场景

请求参数

参数 类型 必填 描述
catalogId String 用于对场景进行分类
  • 0表示手动场景,只包含action场景
  • 1表示自动场景,包含Trigger和Condition的场景
说明 在创建场景时指定catalogId,场景创建后catalogId不可以修改,即不能通过修改catalogId的方式,将手动场景变更为自动场景。
sceneId String 场景Id
enable Boolean true表示启用场景;false表示停用场景
name String 场景的名称
icon String 场景图标URL
iconColor String 场景图标色
description String 对场景的描述
triggers JSON Object IFTTT规则的trigger对象
conditions JSON Object IFTTT规则的condition对象
caConditions JSON Array CA 规则的condition对象
actions JSON Array action对象
sceneType String 场景规则类型,可取值为IFTTT和CA,缺省值为IFTTT
mode String CA规则的模式
  • all

    caConditions 中的条件全部满足时, 才会执行action中的内容

  • any

    caConditions 中的任何一个条件被满足,就会执行action中的内容

返回参数

参数 类型 描述
sceneId String 更新的场景Id

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.1",
        "iotToken": "token"
    },
    "params": {
    "enable" : true,
    "iconColor" : "#DE4545",
    "reBind" : true,
    "mode" : "any",
    "caConditions" : [
      {
        "uri" : "condition\/timer",
        "params" : {
          "cron" : "3g3 10 * * 1,2,3,4",
          "cronType" : "linux"
        }
      }
    ],
    "sceneType" : "CA",
    "icon" : "http:\\www.aliyundoc.com/***.png",
    "sceneId" : "2420d2xxxxf93c54fc4e",
    "catalogId" : "1",
    "name" : "10:27 周一 周二 - 电源开关 开启",
    "actions" : [
      {
        "uri" : "action\/device\/setProperty",
        "params" : {
          "iotId" : "uumR5xxxx00101",
          "propertyName" : "PowerSwitch",
          "propertyValue" : 1
        }
      }
    ]
  }
}          

返回示例

{
    "code": 200,
    "data": "bdc60bexxxxd617697",
    "message": "success"
}
            
​​

删除家中场景

定义描述

path 版本 描述 是否需要登录
/living/scene/delete 1.0.0 删除场景

请求参数

参数 类型 必填 描述
sceneId String 场景Id

返回参数

参数 类型 描述
sceneId String 删除的场景Id

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.1",
        "iotToken": "token"
    },
    "params": {
        "sceneId": "0c965xxxx5306a6657",
        "groupId": null
    }
}                

正常返回示例

{
    "code": 200,
    "data": "0c9653xxxx06a6657",
    "message": "success"
}
​​

查询家中场景列表

定义描述

path 版本 描述 是否需要登录
/living/scene/query 1.0.1 查询场景列表

请求参数

参数 类型 必填 描述
homeId String 场景所在家的唯一标识
catalogId String
  • 0表示手动场景,只包含action场景
  • 1表示自动场景,包含Trigger和Condition的场景
pageNo Integer 页序号,不小于1
pageSize Integer 每页数量,不小于1,不大于50

返回参数

参数 子参数 类型 描述
total Integer 总条目数
pageNo Integer 从1开始的页序号
pageSize Integer 每页数量
scenes Array 返回当前页条目
id String 场景id
status Integer 场景运行时状态:1表示场景上线;2表示场景下线
enable Boolean 场景开关(App上的开关):true-场景置为打开;false-场景置为关闭
icon String 场景图标连接
iconColor String 场景图标颜色
name String 场景名称
description String 场景描述
valid Boolean 是否有效
catalogId String 类型:null-场景1.0版本;0-场景;1-自动化

请求示例

{
  "id": "1509086454180",
  "version": "1.0",
  "request": {
    "apiVer": "1.0.1",
    "iotToken": "token"
  },
  "params": {
    "homeId": "testHomeId",
    "catalogId": "1",
    "pageSize": 20,
    "pageNo": 1,
  }
}

正常返回示例

{
  "code": 200,
  "data": {
    "pageNo": 1,
    "pageSize": 20,
    "scenes": [{
      "description": "电热毯-hy-信噪比--127 ",
      "enable": true,
      "icon": "https://g.aliplus.com/scene_icons/default.png",
      "id": "260de82dxxxx691be22",
      "name": "电热毯",
      "status": 2,
      "iconColor":"#19BBFF",
      "valid":false,
      "catalogId":"1"

    }, {
      "description": "light-hy-LightSwitch-1, shuijin-hy-WiFI_SNR--127 ",
      "enable": true,
      "icon": "https://g.aliplus.com/scene_icons/default.png",
      "id": "45dc6fcxxxx6974e5f7",
      "name": "凉宫",
      "status": 1,
        "iconColor":"#19BBFF",
      "valid":true,
      "catalogId":"1"
    }, {
      "description": "fengsan-hy-PowerSwitch-关闭, light-hy-LightSwitch-1 ",
      "enable": true,
      "icon": "https://g.aliplus.com/scene_icons/default.png",
      "id": "3ce636xxxx1367f2dc88",
      "name": "风扇灯0522",
      "status": 1,
       "iconColor":"#19BBFF",
      "valid":false,
      "catalogId":"1"
    }, {
      "description": "light-hy-LightSwitch-1 ",
      "enable": true,
      "icon": "https://g.aliplus.com/scene_icons/default.png",
      "id": "5b4bdexxxx2612f81",
      "name": "灯0522",
      "status": 2,
        "iconColor":"#19BBFF",
      "valid":false,
      "catalogId":"1"
    }],
    "total": 4
  },
  "message": "success"
}

改变家中场景列表表项的排序

定义描述

path 版本 描述 是否需要登录
/scene/list/reorder 1.0.6 改变场景列表中表项的排序

请求参数

参数 子参数 类型 必填 描述
homeId String 场景所属家的唯一标识
groupId String 对应于 /living/scene/create接口的catalogId参数,用于对场景进行分类。
  • 0表示手动场景,只包含action场景
  • 1表示自动场景,包含Trigger和Condition的场景
sceneId String 需要将场景调整到哪个位置,序号从0开始。
newOrders Array 序号变化的场景数组
​​​

返回参数

参数 类型 描述
code Integer 操作成功状态
​​

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.1",
        "iotToken": "token"
    },
    "params": {
        "groupId": "1",
        "newOrders": [{
            "sceneId": "a596dexxxx9685d25",
            "targetOrder": 2
        }, {
            "sceneId": "c1a8de4xxxxb473c3",
            "targetOrder": 1
        }]
    }
}

正常返回示例

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

获取家中场景详情

定义描述

path 版本 描述 是否需要登录
/living/scene/info/get 1.0.0 获取场景详情

请求参数

参数 类型 必填 描述
sceneId String 待查询的场景ID
catalogId String
  • 0表示手动场景,只包含action场景
  • 1表示自动场景,包含Trigger和Condition的场景
​​

返回参数

参数 类型 描述
id String 场景id
enable Boolean 场景开关状态
  • true:打开状态,场景可以正常被触发执行
  • false:关闭状态,即使达到触发条件,场景也不会执行
name String 用户给场景起的名称
description String 对场景的描述
icon String 场景图标
iconColor String 场景图标色
triggersJson JSON Object IFTTT规则Trigger内复杂对象的JSON序列化,用于前端展示
conditionsJson JSON Object IFTTT规则的condition对象
caConditionsJson JSON Array Since场景2.0,CA规则Condition内复杂对象的JSON序列化,用于前端展示
actionsJson JSON Object Action内复杂对象的JSON序列化,用于前端展示
sceneType String Since场景2.0,场景规则:IFTTT和CA(缺省值为IFTTT)
mode String Since场景2.0,CA规则的模式
  • all

    caConditions 中的条件全部满足时, 才会执行action中的内容

  • any

    caConditions 中的任何一个条件被满足,就会执行action中的内容

valid Boolean 场景的节点是否有效
  • true:场景的节点有效
  • false:场景的节点失效

    设备作为Action节点被解绑后,将不再被场景所控制,此时场景的节点失效

说明 场景中存在多个Action节点时,只要一个Action节点失效,整个场景的valid字段就为false
​​

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.1",
        "iotToken": "token"
    },
    "params": {
        "catalogId": "0",
        "sceneId": "debf2dxxxx51496c2"
    }
}

返回示例

{
    "code":200,
    "data":{
        "id":"testSceneId",
        "name":"测试场景名",
        "description":"这是一个测试场景",
        "enable":true,
        "icon":"https://www.aliyundoc.com/***.png",
        "iconColor":"#FFFFFF",
        "sceneId":"testSceneId",
        "valid":true,
        "triggersJson":"{"items":[{"params":{"cron":"0 7 * * 1,2,3,4,5,6,7","cronType":"linux","timezoneID":"Asia/Shanghai"},"uri":"trigger/timer"}],"uri":"logical/or"}",
        "actionsJson":"[{"uri":"action/device/setProperty","params":{"propertyName":"PowerSwitch_2","propertyValue":1,"iotId":"testDeviceIotId01","productKey":"testProduct","deviceName":"testDeviceName01"}}]"
    },
    "message":"success"
}

获取用户维度的配置数据

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/user/profile/get 1.0.0 获取用户维度的配置数据

请求参数

返回参数

参数 类型 描述
currentHomeId String 用户当前选中的家
sharedDeviceCnt Integer 被分享的设备总数
sharedDeviceOnlineCnt Integer 被分享的设备在线数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":{
          "currentHomeId":"50f5op1xxxxf2f28104512",
            "sharedDeviceCnt":10,
            "sharedDeviceOnlineCnt":3
        }
    }

获取被分享的设备列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/user/device/shared/query 1.0.0 获取被分享的设备列表

请求参数

参数 类型 必填 描述
propertyIdentifiers List < String > 用于过滤设备TSL属性运行态,数据的标识符identifier
pageNo Integer 分页页码,从1开始
pageSize Integer 分页大小,大于等于1,小于等于50

返回参数

参数 子参数 类型 描述
total - Long 满足条件的设备总数
pageNo - Integer 分页页码
pageSize - Integer 分页大小
items - JSONArray 设备的详情列表
- iotId String 设备的iotId,设备的唯一标识
- deviceName String 设备的名称
- productKey String 设备所属产品的ProductKey
- productName String 设备所属产品的名称
- productImage String 设备所属产品的图标,如果未定义产品图标,该字段和categoryImage字段一致
- productModel String 设备所属产品的型号
- categoryKey String 设备所属产品的品类
- categoryImage String 设备所属产品品类的图标key
- panelPageRouterUrl String 设备所属产品品类的面板页面路由URL,categroyKey为Camera时有效
- nickName String 设备的昵称,可为空
- netType String 设备的入网类型
- thingType String 设备的类型
  • VIRTUAL
  • WEB
  • APP
  • DEVICE
- status Integer 设备的状态
  • 0:未激活
  • 1:在线
  • 3:离线
  • 8:禁用
- nodeType String 设备的节点类型
  • DEVICE
  • GATEWAY
- description String 设备的描述
- propertyList List < DeviceProperty > 设备的TSL属性状态列表

DeviceProperty数据结构说明:

名称 类型 描述
identifier String 物模型属性的标识符
name String 物模型属性的名称
value String 物模型属性当前状态值
dataType String 物模型属性值的类型
imageUrl String 物模型属性的图标URL

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "propertyIdentifiers":[
            "LightSwitch"
        ],
            "pageNo":1,
            "pageSize":10
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":{
            "total":1,
            "pageNo":1,
            "pageSize":10,
            "data":[
                {
                    "iotId":"edwB6TqvOxxxx000100",
                    "deviceName":"摄像头1",
                    "productKey":"产品 pk",
                    "productName":"产品名称",
                    "productImage":"产品图片 URL",
                    "productModel":"产品型号",
                    "categoryKey":"Camera",
                    "categoryImage":"xxx",
                    "panelPageRouterUrl":"xxx",
                    "nickName":"设备昵称",
                    "netType":"NET_WIFI",
                    "thingType":"DEVICE",
                    "status":1,
                    "nodeType":"DEVICE",
                    "description":"设备描述",
                    "propertyList":[
                        {
                            "identifier":"LightSwitch",
                            "name":"电源开关",
                            "value":"0",
                            "dataType":"BOOL",
                            "imageUrl":""
                        }
                    ]
                }
            ]
        }
    }

移动被分享设备的顺序

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/user/device/shared/reorder 1.0.0 移动被分享设备的顺序

请求参数

参数 类型 必填 描述
iotId String 设备的iotId,如果productKey和 deviceName字段为空,该字段必填。如果iotId、productKey、deviceName都不为空,以iotId作为设备的唯一标识
productKey String 设备所属产品的productKey,如果iotId字段为空,该字段必填
deviceName String 设备的名称。如果iotId字段为空,该字段必填
targetOrder Integer 设备的目标位置,从0开始

返回参数

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "iotId":"edwB6xxxxNa000100",
            "targetOrder":2
        }
    }
  • 返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":""
    }