upFamilyModule 家庭模块

模块概述

家庭模块为H5页面提供获取家庭列表相关信息。

注意，如果需要用到全面的家庭信息，需要注册监听，等家庭列表刷新完成后再调用相关接口，监听调用示例:

uplusapi.addEventListener('Noti_UserFamilyListChange', 'name', (data) => {
  // uses the data
});

Noti_UserFamilyListChange:用户家庭列表刷新后发送此通知
Noti_UserDeviceListChange:用户设备列表刷新后发送此通知
Noti_UserCurrentFamilyChange:用户当前家庭发生变更后发送此通知

方法列表

• getFamilyMap （获取家庭列表）
• getCurrentFamily （获取当前家庭信息）
• setCurrentFamily （设置当前家庭）
• createFamilyFloor （创建家庭楼层）
• deleteFamilyFloor （删除家庭楼层）
• updateRoomName （更新房间名称）
• updateRoomList (更新当前家庭房间列表)
• moveDevicesToOtherRoom （批量移动设备到新房间）
• addFamilyRoom （增加家庭下房间）
• updateDeviceName （更改设备名称）
• removeFamilyRoom （删除家庭下房间）
• createFamily （创建家庭）
• updateFamilyInfo （更新家庭信息）
• exitFamilyAsMember （普通成员离开家庭）
• exitFamilyAsAdmin （管理员移除家庭）
• deleteMemberAsAdmin （管理员移除成员）
• inviteMemberAsAdmin （管理员邀请成员（通过手机号））
• changeFamilyAdmin （变更家庭管理员）
• deleteFamilyAsAdmin （管理员解散家庭）
• queryFirstMember (查询第一个加入家庭的家庭成员)
• queryFamilyInfo (查询家庭信息)
• queryFamilyInfoFromCache (由缓存查询家庭信息)
• addVirtualMember (虚拟用户加入家庭)
• modifyVirtualMember (修改虚拟成员)
• moveDevicesToFamily (批量转移设备到目标家庭)
• unbindDeviceFromFamily (家庭批量解绑设备)
• removeDevicesFromFamily (家庭批量移除设备)

公共数据

• 所有数据均以JSON结构返回，由代码，信息和数据三部分组成

{
    "retCode": "000000", //接口状态标识码,错误标识码以29开头
    "retInfo": "操作成功",//接口信息说明
    "retData": null //业务数据
}

房间信息模型 RoomInfo

{ 
  "familyId": "",
  "roomId": "",
  "roomName": "",
  "roomClass":"", //房间类型
  "roomLabel":"", //房间标签
  "roomLogo":"",  //房间logo url
  "roomPicture":"" //房间图片 url
}

• 房间信息模型定义

楼层信息模型 FloorInfo

{ 
  'floorId': '',
  'floorOrderId': '',
  'floorName': '',
  'floorClass': '',
  'floorLabel': '',
  'floorLogo': '',
  'floorPicture': '',
  'floorCreateTime': '',
  'rooms': [RoomInfo],
}

• 楼层信息模型定义

设备信息模型 DeviceInfo

{
  "apptypeName": "空气净化器", //设备类型名称
  "brand": "haier", // 设备品牌
  "prodNo": "FR00V7M2E", //产品编号
  "bindType": "SmartLink", //绑定类型
  "bindTime": "2019-10-31 10:30:11", //绑定时间comunicationMode
  "comunicationMode": "xxxxx", //通讯方式
  "deviceId": "0007A8AC5CEC", //设备deviceId
  "deviceName": "E70edE6cf51", //设备名称
  "deviceType": "20001###", //设备类型代码
  "deviceNetType":"netDevice",//设备网器类型，netDevice：网器，noNetDevice：非网器
  "deviceRole": "1", //1.普通和设备；2.网关设备；3.附件设备； 4 子设备
  "deviceRoleType": "1", //主设备/子设备/无主从关系，枚举值：0 无主设备；1 主设备；2 子设备。
  "imageAddr1": "http://file.c.haier.net/images/2019/01/11/f3aed13ef3e044b6eba388d046c934fe.png", //设备图片1
  "imageAddr2": "http://file.c.haier.net/images/2019/01/11/f3aed13ef3e044b6eba388d046c934fe.png", //设备图片2
  "isOnline": false, //设备在线状态
  "model": "M1黑色", //设备型号
  "wifiType": "201c120000118674200100418002065800000000000000000000000000000040", //设备typeid
  "ownerId": "25950360", //管理员Id
  "ownerInfo": { //设备管理员信息
    "mobile": "158****4506", //管理员手机号
    "userId": "5569278" //管理员userId
  },
  "permission": {
    "auth": {
      "control": true, //是否可控制
      "set": true, //是否可修改
      "view": true //是否可查看
    },
    "authType": "home" //授权类型
  },
  "room": RoomInfo, // 房间信息，RoomInfo参照房间信息模型
  "devFloorId": "123",  // 楼层id
  "devFloorOrderId": "1", // 楼层次序
  "devFloorName": "一楼", // 楼层名称
  "deviceNetType": "netDevice",//设备网器类型
}

• 设备信息定义

成员信息模型 MemberInfo

{ 
  "joinTime": "2017-02-25 14:09:18", //加入时间
  "memberInfo": { //成员信息
    "avatarUrl": "http://resource.haier.net:80/download/resource/uzhsh/5569278/1499938384705.jpg", //头像地址
    "mobile": "158****4506", //手机号
    "name": "ghgcvvccE7684", // 用户名
    "userId": "5569278", // 用户userId
    "virtualUserFlag": false, // true 虚拟用户，false 非虚拟用户
    "ucUserId":"", //用户中心userId
    "hostUserId":"" //宿主用户的IOT平台userId
  },
  "memberName": "admin5569278", //成员名称
  "familyId":"", //家庭id
  "shareDeviceCount": 5 //分享到该家庭下的设备数量
}

• 成员信息定义

家庭数据模型 FamilyInfo

{
  "createTime": "2017-02-25 14:09:18", //家庭创建时间
  "familyId": "994039150958000000", //家庭familyId
  "firstMember": MemberInfo, //首位加入的成员信息，MemberInfo参照成员信息模型
  "info": { //家庭信息
    "familyLocation": { // 家庭定位
      "cityCode": "101020100", // 家庭所在城市代码
      "latitude": 31.24916, //家庭所在城市经度
      "longitude": 121.4879 //家庭所在城市纬度
    },
    "familyName": "家庭1", //家庭名称
    "familyPosition": "广州 番禺" //家庭位置
  },
  "locationChangeFlag": true, //家庭位置修改标识位
  "members": [MemberInfo], //成员列表，MemberInfo参照成员信息模型
  "owner": { //管理员信息
    "avatarUrl": "",  //头像
    "mobile": "", //电话
    "userId": "", //userId
    "ucUserId":"", //用户中心userId
    "name":"",//昵称
  },
  "floorInfos": [FloorInfo], //楼层列表，FloorInfo参照楼层信息模型
  "sharedDevices": [DeviceInfo], //分享的设备列表，DeviceInfo参照设备信息模型
  "familyOwner":"" // 家庭管理员id

• 设备基本信息定义

批量处理设备结果模型 BatchProcessDeviceCollection

{
  "successDevices": [BatchProcessDevice];
  "failureDevices": [BatchProcessDevice];
}

• 批量处理设备结果模型定义

批量处理设备模型 BatchProcessDevice

{
  "deviceId": string;
  "deviceName": string;
}

• 批量处理设备模型定义

具体定义：返回数据通用

模块变更记录

• V4.0.0
  • 删除接口
    • editFamilyFloor(编辑楼层)
  • 部分错误码变更
  • 创建家庭参数变更：
    • 新增房间参数模型Room，包含roomName、roomClass2个属性。
    • 创建家庭接口参数新增房间参数数组Room[]。
  • 新增接口
    • queryFirstMember (查询第一个加入家庭的家庭成员)
    • queryFamilyInfo (查询家庭信息)
    • queryFamilyInfoFromCache (由缓存查询家庭信息)
    • addVirtualMember (虚拟用户加入家庭)
    • modifyVirtualMember (修改虚拟成员)
    • moveDevicesToFamily (批量转移设备到目标家庭)
    • unbindDeviceFromFamily (家庭批量解绑设备)
    • removeDevicesFromFamily (家庭批量移除设备)

• V3.7.0

  • 数据模型变更：
    • DeviceInfo对象中新增deviceNetType属性， 设备网器类型（netDevice 网器；nonNetDevice 非网器）。
    • DeviceInfo对象中新增deviceRole，deviceRoleType属性。

• V3.6.0（App版本6.22.0及以上）

  • 新增数据模型：
    • FloorInfo（楼层模型）
  • 数据模型变更：
    • FamilyInfo 中去掉 rooms 属性，新增 floorInfos 属性
    • DeviceInfo 中新增楼层字段：devFloorId, devFloorName, devFloorOrderId
  • 新增方法：
    • createFamilyFloor（新建楼层）
    • deleteFamilyFloor（删除楼层）
    • editFamilyFloor（编辑楼层）
  • 方法变更：
    • addFamilyRoom（增加家庭下房间）：新增入参 floorId（必填）
    • updateRoomList（刷新房间列表）：新增入参 floorId（必填）

• V3.0.0

  • 新增family模块，新增方法：
    • getFamilyMap （获取家庭列表）
    • setCurrentFamily （设置当前家庭）
    • getCurrentFamily （获取当前家庭信息）
    • updateRoomName （更新房间名称）
    • deviceUpdateRoomName （更新设备房间位置）

• V3.2.0

  • 重构家庭模块接口，统一返回数据，重新定义retCode：
    • 000000---操作成功
    • 000001---操作失败
    • 000002---非法参数错误
    • 990001---模块未定义
    • 300001---目标家庭不存在
    • 300002---目标房间不存在
    • 300003---目标设备不存在
    • 300004---用户未登陆
    • 300005---用户数据刷新中
    • 300006---目标房间已存在
  • 增加cordova容器对模块的支持
  • 增加updateRoomList（更新当前家庭房间列表）接口
  • 正确返回数据中latitude,longitude字段变更为Number类型
  • 新增moveDevicesToOtherRoom （批量移动设备到新房间）
  • 删除deviceUpdateRoomName
  • 新增addFamilyRoom（增加家庭下房间）、updateDeviceName（更改设备名称）接口

• V3.3.0

  • 新增方法：
    • removeFamilyRoom （删除家庭下房间）
    • createFamily （创建家庭）
    • updateFamilyInfo （更新家庭信息）
    • exitFamilyAsMember （普通成员离开家庭）
    • exitFamilyAsAdmin （管理员移除家庭）
    • deleteMemberAsAdmin （管理员移除成员）
    • inviteMemberAsAdmin （管理员邀请成员（通过手机号））
    • changeFamilyAdmin （变更家庭管理员）
    • deleteFamilyAsAdmin （管理员解散家庭）

• V3.4.0（警告：此版本修改的方法仅支持App版本6.19.0及以上）

  • 修改方法：

    • getFamilyMap （获取家庭列表）

      • 智家App版本6.19.0以前，使用此版本getFamilyMap时，会导致返回数据为空

    • getCurrentFamily （获取当前家庭信息）

      • 智家App版本6.19.0以前，使用此版本getCurrentFamily时，会导致返回数据为空
    • createFamily （创建家庭）
      • 返回数据格式更改为:

        {
        "retCode":"000000",
        "retInfo":"调用函数createFamily([object Object])成功",
        "retData":{
          "familyId":"341169379443000000"
        }
        }
        

方法说明

• getFamilyMap （获取家庭列表）

  getFamilyMap()

适用性

params 输入参数：

无

错误返回 retCode说明：

正确返回 retData说明：

示例

调用方式

uplusapi.upFamilyModule.getFamilyMap().then((result) =>console.log('result',result));

获取成功返回结果

{
    "retCode": "000000",
    "retInfo": "调用函数getFamilyMap()成功",
    "retData": [FamilyInfo] //参照家庭信息模型
}

• getCurrentFamily （获取当前家庭列信息）

  getCurrentFamily()

适用性

params 输入参数：

无

错误返回 retCode说明：

正确返回 retData说明：

示例

调用方式

uplusapi.upFamilyModule.getCurrentFamily().then((result) =>console.log('result',result));

获取成功返回结果

{
    "retCode": "000000",
    "retInfo": "调用函数getCurrentFamily()成功",
    "retData": FamilyInfo //参照家庭信息模型
}

• setCurrentFamily （设置当前家庭）

  setCurrentFamily()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.setCurrentFamily({
  "familyId": "123123"
}).then((result) =>console.log('result',result));

• createFamilyFloor （创建家庭楼层）

  createFamilyFloor()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.createFamilyFloor({
  familyId: '123456',
  floorOrderId: '1',
  floorName: '一楼',
  floorLabel: '客厅一楼',
  floorLogo: 'http://www.haier.com/123.jpg',
  floorPicture: 'http://www.haier.com/456.jpg',
}).then((result) =>console.log('result',result));

• deleteFamilyFloor （删除家庭楼层）

  deleteFamilyFloor()

适用性

| 容器 | Nebula | | :--: ｜ :--: | | 支持情况｜ 是 | | APP版本 | 6.22.0 及以上 |

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.deleteFamilyFloor({
  familyId: '123456',
  floorId: '123'
}).then((result) => {
    console.log('result',result);
}).catch((e) => {
    console.log(e);
});

• updateRoomName （更新房间名称）

  updateRoomName()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.updateRoomName({
  "familyId": "12313",
  "roomId": "123132",
  "roomName": "厨房"
}).then((result) =>console.log('result',result));

• moveDevicesToOtherRoom （批量移动设备到新房间）

  moveDevicesToOtherRoom()

适用性

params 输入参数：

deviceIds属性

错误返回 retCode说明：

｜110004｜房间不存在｜

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.moveDevicesToOtherRoom({
      familyId: '717040163919000002',
      deviceIds: [{ deviceId: '78:A5:04:4B:2A:92', deviceName: '体质仪1112' }],
      newRoom: '客厅',
      newRoomId: '359150848956000000'
    }).then(res=>{
      console.log('moveDevicesToOtherRoom', res);
      uplusapi.upFamilyModule.getFamilyMap().then(ret=>{
      console.log('更新后信息', ret);
    });
    });

• updateRoomList (更新当前家庭房间列表)

  updateRoomList()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

示例

调用方式

uplusapi.upFamilyModule.updateRoomList({
  "familyId":"12312313",
  "floorId":"123abc"
}).then((result) =>console.log('result',result));

• addFamilyRoom (增加家庭下房间)

  addFamilyRoom()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

由于历史原因，虽然接口返回值声明为void，但实际retData返回结构如下:

｜属性名| 数据类型 | 说明 | | --- | --- | --- | ｜ roomId| String | 房间ID |

示例

调用方式

uplusapi.upFamilyModule.addFamilyRoom({
  roomName: '储藏室',
  familyId: '12345678',
  floorId: '123abc'
}).then(res => console.log(res)).catch(err => console.log(err));

• updateDeviceName (更改设备名称)

  updateDeviceName()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

由于历史原因，虽然接口返回值声明为void，但实际retData返回结构如下:

｜属性名| 数据类型 | 说明 | | --- | --- | --- | ｜ deviceId| String | 设备ID |

示例

调用方式

uplusapi.upFamilyModule.updateDeviceName({
  deviceId: 'DC330DDDDDD',
  deviceName: '我的设备'
}).then(res => console.log(res)).catch(err => console.log(err));

• removeFamilyRoom (删除家庭下房间)

  removeFamilyRoom()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.removeFamilyRoom({
  roomId: '123132',
  familyId: '12345678'
}).then(res => console.log(res)).catch(err => console.log(err));

• createFamily (创建家庭)

  createFamily()

适用性

params 输入参数：

familyLocation

roomNames

错误返回 retCode说明：

正确返回 retData说明：

由于历史原因，虽然接口返回值声明为void，但实际retData返回结构如下:

｜属性名| 数据类型 | 说明 | | --- | --- | --- | ｜ familyId| String | 家庭ID |

示例

调用方式

uplusapi.upFamilyModule.createFamily({
  familyName: '小屋',
  familyPosition: '青岛',
  familyLocation:{
    longitude: 120.2563476600,
    latitude:  35.8712468500,
    cityCode: '370202'
  },
  roomNames:[{roomName:'阳台',roomClass:'阳台'}]
}).then(res => console.log(res)).catch(err => console.log(err));

• updateFamilyInfo (更新家庭信息)

  updateFamilyInfo()

适用性

params 输入参数：

familyLocation

错误返回 retCode说明：

｜110003｜家庭不存在｜

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.updateFamilyInfo({
  familyId: '12345678',
  familyName: '小屋',
  familyPosition: '青岛',
  familyLocation:{
    longitude: 120.2563476600,
    latitude:  35.8712468500,
    cityCode: '370202'
  }
}).then(res => console.log(res)).catch(err => console.log(err));

• exitFamilyAsMember (普通成员离开家庭)

  exitFamilyAsMember()

适用性

params 输入参数：

错误返回 retCode说明：

｜110003｜家庭不存在｜

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.exitFamilyAsMember({
  familyId: '12345678'
}).then(res => console.log(res)).catch(err => console.log(err));

• exitFamilyAsAdmin (管理员离开家庭)

  exitFamilyAsAdmin()

适用性

params 输入参数：

错误返回 retCode说明：

｜110003｜家庭不存在｜

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.exitFamilyAsAdmin({
  familyId: '12345678',
  userId: '123456789'
}).then(res => console.log(res)).catch(err => console.log(err));

• deleteMemberAsAdmin (管理员移除成员)

  deleteMemberAsAdmin()

适用性

params 输入参数：

错误返回 retCode说明：

｜110003｜家庭不存在｜

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.deleteMemberAsAdmin({
  familyId: '12345678',
  userId: '123456789'
}).then(res => console.log(res)).catch(err => console.log(err));

• inviteMemberAsAdmin (管理员邀请成员（通过手机号))

  inviteMemberAsAdmin()

适用性

params 输入参数：

错误返回 retCode说明：

｜110003｜家庭不存在｜

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.inviteMemberAsAdmin({
  familyId: '12345678',
  phone: '123456789'
}).then(res => console.log(res)).catch(err => console.log(err));

• changeFamilyAdmin (变更家庭管理员)

  changeFamilyAdmin()

适用性

params 输入参数：

错误返回 retCode说明：

｜110003｜家庭不存在｜

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.changeFamilyAdmin({
  familyId: '12345678',
  userId: '123456789'
}).then(res => console.log(res)).catch(err => console.log(err));

• deleteFamilyAsAdmin (管理员解散家庭)

  deleteFamilyAsAdmin()

适用性

params 输入参数：

错误返回 retCode说明：

｜110003｜家庭不存在｜

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.deleteFamilyAsAdmin({
  familyId: '12345678'
}).then(res => console.log(res)).catch(err => console.log(err));

• queryFirstMember (查询第一个加入家庭的家庭成员)

  queryFirstMember()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

示例

调用方式

uplusapi.upFamilyModule.queryFirstMember({
  familyId: '12345678'
}).then(res => console.log(res)).catch(err => console.log(err));

获取成功返回结果

{
    "retCode": "000000",
    "retInfo": "调用函数queryFirstMember()成功",
    "retData": MemberInfo //参照家庭成员信息模型
}

• queryFamilyInfo (查询家庭信息)

  queryFamilyInfo()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

示例

调用方式

uplusapi.upFamilyModule.queryFamilyInfo(data: {
({
  familyId: '12345678'
}).then(res => console.log(res)).catch(err => console.log(err));

获取成功返回结果

{
    "retCode": "000000",
    "retInfo": "调用函数queryFamilyInfo()成功",
    "retData": FamilyInfo //参照家庭信息模型
}

• queryFamilyInfoFromCache (由缓存查询家庭信息)

  queryFamilyInfoFromCache()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

示例

调用方式

uplusapi.upFamilyModule.queryFamilyInfoFromCache(data: {
({
  familyId: '12345678'
}).then(res => console.log(res)).catch(err => console.log(err));

获取成功返回结果

{
    "retCode": "000000",
    "retInfo": "调用函数queryFamilyInfoFromCache()成功",
    "retData": FamilyInfo //参照家庭信息模型
}

• addVirtualMember (虚拟用户加入家庭)

  addVirtualMember()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.addVirtualMember({
  familyId: '12345678';
  virtualUCId: '1234567';
  userFamilyName: 'name';
}).then(res => console.log(res)).catch(err => console.log(err));

• modifyVirtualMember (修改虚拟成员)

  modifyVirtualMember()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

无

示例

调用方式

uplusapi.upFamilyModule.modifyVirtualMember({
  familyId: '12345678';
  memberId: '1234567';
  memberName: 'name';
  avatarUrl: 'url';
  isCreater: true;
}).then(res => console.log(res)).catch(err => console.log(err));

• moveDevicesToFamily (批量转移设备到目标家庭)

  moveDevicesToFamily()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

示例

调用方式

uplusapi.upFamilyModule.moveDevicesToFamily({
  familyId: "familyId",
  newFamilyId: "newFamilyId",
  deviceIds: ["deviceId"],
}).then(res => console.log(res)).catch(err => console.log(err));

• unbindDeviceFromFamily (家庭批量解绑设备)

  unbindDeviceFromFamily()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

示例

调用方式

uplusapi.upFamilyModule.unbindDeviceFromFamily({
  familyId: "familyId",
  deviceIds: ["deviceId"],
}).then(res => console.log(res)).catch(err => console.log(err));

• removeDevicesFromFamily (家庭批量移除设备)

  removeDevicesFromFamily()

适用性

params 输入参数：

错误返回 retCode说明：

正确返回 retData说明：

示例

调用方式

uplusapi.upFamilyModule.removeDevicesFromFamily({
  familyId: "familyId",
  deviceIds: ["deviceId"],
}).then(res => console.log(res)).catch(err => console.log(err));