提供一组家空间相关的接口,您可以根据这些接口开发家、房间以及结合家房间的设备组、场景等相关功能。
创建家
定义描述
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 | 用户和家的关系
|
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 | 用户和家的关系
|
- | 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 | 元素类型
|
- | 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时有效
|
- | status | Integer | 设备的状态,elementType为DEVICE时有效
|
- | nodeType | String | 设备的节点类型,elementType为DEVICE时有效
|
- | 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 | 否 | 根据设备节点类型过滤
|
productKey | String | 否 | 产品的productKey |
categoryKey | String | 否 | 产品的品类key |
homeId | String | 否 | 家的id,家的唯一标识,用于过滤归属在某一个家的设备列表 |
roomId | String | 否 | 房间的id,房间的唯一标识,用于过滤归属在某一个房间的设备列表 |
excludedHomeId | String | 否 | 家的id,家的唯一标识,用于过滤未归属在某一个家的设备列表 |
excludedRoomId | String | 否 | 房间的id,房间的唯一标识,用于过滤未归属在某一个房间的设备列表 |
boundControlGroup | Boolean | 否 | 设备组的绑定状态
|
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 | 设备的类型
|
- | status | Integer | 设备的状态
|
- | nodeType | String | 设备的节点类型
|
- | 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 | 设备的类型
|
- | status | Integer | 设备的状态
|
- | nodeType | String | 设备的节点类型
|
- | 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 | 设备的类型
|
- | status | Integer | 设备的状态
|
- | nodeType | String | 设备的节点类型
|
- | 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 | 是 | 用于对场景进行分类
|
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规则的模式
|
返回参数
参数 | 类型 | 描述 |
---|---|---|
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 | 是 | 用于对场景进行分类
说明 在创建场景时指定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规则的模式
|
返回参数
参数 | 类型 | 描述 |
---|---|---|
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 | 是 |
|
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参数,用于对场景进行分类。
|
|
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 | 否 |
|
返回参数
参数 | 类型 | 描述 |
---|---|---|
id | String | 场景id |
enable | Boolean | 场景开关状态
|
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规则的模式
|
valid | Boolean | 场景的节点是否有效
说明 场景中存在多个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 | 设备的类型
|
- | status | Integer | 设备的状态
|
- | nodeType | String | 设备的节点类型
|
- | 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":"" }