群组管理

将具备共性的设备组成一个群组，群组具备和设备类似的控制页面，使用群组命令可以控制群组中的设备。群组与场景都可以实现批量控制设备的功能，场景中各个设备的操作可以灵活多样，群组以通用共性视角批量操作设备执行相同操作。

使用指南

群组管理业务均是通过 ThingGroupBizManager 类来统一调度。每个的接口的入参均为 GroupOperateBuilder，不同接口需要组成的数据各不相同。下文详细说明每个接口所需的参数。

接口说明

接口	说明
fetchDeviceList	获取可创建为群组的设备列表
createGroup	创建群组
updateGroup	更新群组
dismissGroup	删除群组

参数说明

GroupOperateBuilder 说明

属性	类型	说明
groupId	long	群组 ID
groupName	String	群组名称
allSelectDeviceList	List< String >	创建群组时选中的设备列表，或者更新群组时变更之后的设备列表
processCallback	String	群组创建/变更进度的回调
successCallback	SuccessCallback	群组创建/变更成功的回调
failureCallback	FailureCallback	获取设备列表、群组创建/变更/删除失败的回调
queryDeviceCallback	QueryDeviceCallback	获取设备列表成功的回调

初始化

在使用上述接口之前，需要先创建群组管理类 ThingGroupBizManager，初始化群组操作所需的基础内容。不同类型群组的初始化所需的参数各有不同，但统一通过 GroupInitBuilder 来组装。除此之外，还需传入当前家庭 ID。下文将详细说明不同类型群组的初始化。

在对群组进行 增、删、改、查 之前，需要先进行初始化。初始化只需传入 deviceId 或 groupId。

• 对于已存在的群组，传入该群组的 groupId。
• 未存在群组时，需要传入一个 deviceId，表示要创建该类型设备的群组。

参数说明

属性	类型	说明	是否必传
devId	String	设备 ID	否
groupId	long	群组 ID	否

调用示例

GroupInitBuilder initBuilder = new GroupInitBuilder.Builder()
        .setDevId(devId)
        .build();
IThingGroupManager thingGroupBizManager = ThingGroupBizKit.getGroupBizManager(homeId,initBuilder);

获取能组成群组的设备列表

在对群组进行操作之前，需要先调用该接口，获取能组成群组的设备列表。

接口说明

fun fetchDeviceList(operateBuilder: GroupOperateBuilder)

参数说明

属性	类型	说明	是否必传
failureCallback	FailureCallback	获取设备列表、群组创建/变更/删除失败的回调	是
queryDeviceCallback	QueryDeviceCallback	获取设备列表成功的回调	是

调用示例

GroupInitBuilder initBuilder = new GroupInitBuilder.Builder()
        .setDevId(devId)
        .build();

GroupOperateBuilder operateBuilder = new GroupOperateBuilder.Builder()
        .setQueryDeviceCallback(new QueryDeviceCallback() {
            @Override
            public void result(@NonNull List<? extends GroupInfo> list) {

            }
        })
        .setFailureCallback(new FailureCallback() {
            @Override
            public void onError(@Nullable String errorCode, @Nullable String errorMessage, long groupId, @Nullable List<GroupResult> failDevices) {

            }
        })
        .build();
thingGroupBizManager.fetchDeviceList(operateBuilder);

返回数据说明

GroupInfo 类

属性	类型	说明
devId	String	设备 ID。
iconUrl	String	设备图片。
devName	String	设备名称。
nodeId	String	设备的 nodeId。
checked	boolean	是否已被选择。 true：表示该设备已在群组中。 false：表示该设备不在群组中。
isOnline	boolean	设备是否在线。
productId	String	设备产品 ID。
belongHomeName	String	设备属于哪个家庭。
belongRoomName	String	设备属于哪个房间。

创建群组

从 fetchDeviceList 接口返回的设备列表中，选择需要组成群组的设备，然后调用该接口创建群组。

接口说明

fun createGroup(operateBuilder: GroupOperateBuilder)

参数说明

属性	类型	说明	是否必传
allSelectDeviceList	List< String >	选中的设备列表	是
groupName	String	群组名称	是
queryDeviceCallback	QueryDeviceCallback	获取设备列表成功的回调	是
failureCallback	FailureCallback	获取设备列表、群组创建/变更/删除失败的回调	是
successCallback	SuccessCallback	群组创建/变更成功的回调	是

调用示例

GroupInitBuilder initBuilder = new GroupInitBuilder.Builder()
        .setDevId(devId)
        .build();

GroupOperateBuilder operateBuilder = new GroupOperateBuilder.Builder()
        .setAllSelectDeviceList(allSelectDeviceList)
        .setSuccessCallback(new SuccessCallback() {
            @Override
            public void result(long groupId, @Nullable List<GroupResult> failDevices) {

            }
        })
        .setProcessCallback(new ProcessCallback() {
            @Override
            public void result(int process, int size) {

            }
        })
        .setFailureCallback(new FailureCallback() {
            @Override
            public void onError(@Nullable String errorCode, @Nullable String errorMessage, long groupId, @Nullable List<GroupResult> failDevices) {

            }
        })
        .build();
thingGroupBizManager.createGroup(operateBuilder);

更新群组中的设备

从 fetchDeviceList 接口返回的设备列表中，选择需要组成群组的设备，然后调用该接口更新群组中的设备。

接口说明

fun updateGroup(operateBuilder: GroupOperateBuilder)

参数说明

属性	类型	说明	是否必传
allSelectDeviceList	List< String >	选中的设备列表	是
queryDeviceCallback	QueryDeviceCallback	获取设备列表成功的回调	是
failureCallback	FailureCallback	获取设备列表、群组创建/变更/删除失败的回调	是
successCallback	SuccessCallback	群组创建/变更成功的回调	是

调用示例

GroupInitBuilder initBuilder = new GroupInitBuilder.Builder()
        .setGroupId(groupId)
        .build();

GroupOperateBuilder operateBuilder = new GroupOperateBuilder.Builder()
        .setAllSelectDeviceList(allSelectDeviceList)
        .setSuccessCallback(new SuccessCallback() {
            @Override
            public void result(long groupId, @Nullable List<GroupResult> failDevices) {

            }
        })
        .setProcessCallback(new ProcessCallback() {
            @Override
            public void result(int process, int size) {

            }
        })
        .setFailureCallback(new FailureCallback() {
            @Override
            public void onError(@Nullable String errorCode, @Nullable String errorMessage, long groupId, @Nullable List<GroupResult> failDevices) {

            }
        })
        .build();
thingGroupBizManager.updateGroup(operateBuilder);

删除群组

传入 groupId，删除群组。

接口说明

fun dismissGroup(operateBuilder: GroupOperateBuilder)

参数说明

属性	类型	说明	是否必传
groupId	long	群组 ID	是
failureCallback	FailureCallback	获取设备列表、群组创建/变更/删除失败的回调	是
successCallback	SuccessCallback	群组创建/变更成功的回调	是

调用示例

GroupInitBuilder initBuilder = new GroupInitBuilder.Builder()
        .setDevId(groupId)
        .build();

GroupOperateBuilder operateBuilder = new GroupOperateBuilder.Builder()
        .setGroupId(groupId)
        .setSuccessCallback(new SuccessCallback() {
            @Override
            public void result(long groupId, @Nullable List<GroupResult> failDevices) {

            }
        })
        .setFailureCallback(new FailureCallback() {
            @Override
            public void onError(@Nullable String errorCode, @Nullable String errorMessage, long groupId, @Nullable List<GroupResult> failDevices) {

            }
        })
        .build();
thingGroupBizManager.dismissGroup(operateBuilder);

错误码

错误码	说明
1001	未获取家庭详细信息，或者配置不正确