频道黑白名单 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

频道黑白名单

更新时间： 2024/03/14 16:36:32

频道黑白名单用于管控频道对服务器成员是否可见。圈组支持选择服务器成员加入黑名单或白名单，或者选择身份组将身份组所有成员批量加入黑名单或白名单。

被加入黑白名单的用户，即为黑白名单成员；被加入黑名单或白名单的身份组即为黑白名单身份组。

功能介绍

频道的可见性管控是圈组消息流转中的一个环节，管控方式根据频道的查看模式存在区分，具体如下：

频道查看模式	可见性管控
公开	通过频道黑名单进行管控，频道对黑名单中的服务器成员不可见，即这些成员无法访问该频道，其他服务器成员均可访问该频道
私密	通过频道白名单进行管控，频道对白名单中的服务器成员可见，即这些成员可访问该频道，其他服务器成员均无法访问该频道

前提条件

已注册observeReceiveSystemNotification监听圈组的系统通知。示例代码参见圈组系统通知收发。

具体与频道黑白名单相关的系统通知类型，见本文末尾的相关系统通知。
已创建频道。

使用限制

频道黑白名单存在如下与黑白名单相关的限制：

单个频道的黑白名单成员人数上限，默认为 1000。
单个频道可设置的黑白名单身份组的数量上限，默认为 20。

若需要扩展上限，可在控制台配置圈组子功能项（公开私密频道的黑白名单成员数 和 channel 公开私密频道的黑白名单身份组对象数），具体请参考开通和配置圈组功能。

实现方法

管理黑白名单成员

更新频道黑白名单成员

用户可调用updateChannelBlackWhiteMembers方法更新频道的黑白名单，将服务器成员加入或移出黑白名单，从而管控服务器成员是否可访问频道。

调用该方法需拥有管理黑白名单的权限（QChatRoleResource.MANAGE_BLACK_WHITE_LIST）。

QChatUpdateChannelBlackWhiteMembersParam为其入参结构，具体参数说明如下：

返回值	参数	说明
Long	`getServerId()`	获取服务器 ID
Long	`getChannelId()`	获取频道 ID
`QChatChannelBlackWhiteType`	`getType()`	获取黑白名单类型 `QChatChannelBlackWhiteType.WHITE`：白名单 `QChatChannelBlackWhiteType.BLACK`：黑名单
`QChatChannelBlackWhiteOperateType`	`getOperateType()`	获取黑白名单操作类型: `QChatChannelBlackWhiteOperateType.ADD`:添加 `QChatChannelBlackWhiteOperateType.REMOVE`:移除
List< String>	`getToAccids()`	获取账户`accid`列表：添加或者移除到黑白名单的`accid`列表

示例代码如下：

//将accids中的这些账户添加到黑名单中
NIMClient.getService(QChatChannelService.class).updateChannelBlackWhiteMembers(new QChatUpdateChannelBlackWhiteMembersParam(943445L,885305L,
        QChatChannelBlackWhiteType.BLACK, QChatChannelBlackWhiteOperateType.ADD,accids)).setCallback(new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void result) {
        //更新Channel黑白名单成员成功

    }

    @Override
    public void onFailed(int code) {
        //更新Channel黑白名单成员失败，返回错误code
    }

    @Override
    public void onException(Throwable exception) {
        //更新Channel黑白名单成员异常
    }
});

分页查询频道黑白名单成员

调用getChannelBlackWhiteMembersByPage方法，可分页查询频道黑白名单。调用时需要传入查询的 serverId、channelId、黑白名单类型、查询锚点时间戳timeTag 和查询数量限制limit。

调用该方法需要拥有管理频道黑白名单的权限（QChatRoleResource.MANAGE_BLACK_WHITE_LIST）。

示例代码如下：

//查处频道黑名单中的成员列表
NIMClient.getService(QChatChannelService.class).getChannelBlackWhiteMembersByPage(new QChatGetChannelBlackWhiteMembersByPageParam(943445L,885305L,QChatChannelBlackWhiteType.BLACK,System.currentTimeMillis())).setCallback(new RequestCallback<QChatGetChannelBlackWhiteMembersByPageResult>() {
    @Override
    public void onSuccess(QChatGetChannelBlackWhiteMembersByPageResult result) {
        //查询成功,返回频道黑名单中成员列表
        List<QChatServerMember> members = result.getMemberList();
        //下一页的起始时间戳
        long nextTimeTag = result.getNextTimeTag();
        //是否还有下一页
        boolean hasMore = result.isHasMore();
    }

    @Override
    public void onFailed(int code) {
        //查询失败，返回错误code
    }

    @Override
    public void onException(Throwable exception) {
        //查询异常
    }
});

批量查询频道黑白名单成员

调用getExistingChannelBlackWhiteMembers方法可根据传入的用户账号（accid）列表查询其中已被加入的黑白名单的用户。

单次调用最多可传入 100 个 accid。

示例代码如下：

//查询频道中存在的黑名单成员
List<String> accidList = getQueryAccids();
QChatGetExistingChannelBlackWhiteMembersParam param = new QChatGetExistingChannelBlackWhiteMembersParam(currentChannel.getServerId(),currentChannel.getChannelId(), QChatChannelBlackWhiteType.BLACK,accidList);
NIMClient.getService(QChatChannelService.class).getExistingChannelBlackWhiteMembers(param).setCallback(
        new RequestCallback<QChatGetExistingChannelBlackWhiteMembersResult>() {
            @Override
            public void onSuccess(QChatGetExistingChannelBlackWhiteMembersResult result) {
                //查询到的在黑名单中的成员
                List<QChatServerMember> memberList = result.getMemberList();
            }

            @Override
            public void onFailed(int code) {
                //查询失败，返回错误code
            }

            @Override
            public void onException(Throwable exception) {
                //查询异常
            }
        });

管理黑白名单身份组

更新频道黑白名单身份组

调用updateChannelBlackWhiteRoles方法可选择身份组将所选身份组的成员批量加入或移出频道黑白名单，加入黑白名单的身份组即为黑白名单身份组。调用时需要传入服务器 ID（serverId）、频道 ID（channelId）、黑白名单类型、黑白名单操作类型和身份组 ID 列表。、

调用该方法需要拥有管理频道黑白名单的权限（QChatRoleResource.MANAGE_BLACK_WHITE_LIST）。

示例代码如下：

NIMClient.getService(QChatChannelService.class).updateChannelBlackWhiteRoles(new QChatUpdateChannelBlackWhiteRolesParam(943445L,885305L,
        QChatChannelBlackWhiteType.BLACK, QChatChannelBlackWhiteOperateType.ADD,roleIds)).setCallback(new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void result) {
        //更新Channel黑白名单身份组成功

    }

    @Override
    public void onFailed(int code) {
        //更新Channel黑白名单身份组失败，返回错误code
    }

    @Override
    public void onException(Throwable exception) {
        //更新Channel黑白名单身份组异常
    }
});

分页查询黑白名单身份组列表

调用getChannelBlackWhiteRolesByPage方法可分页查询频道的黑白名单身份组列表。调用时需要传入服务器 ID、频道 ID、黑白名单类型、查询锚点时间戳 timeTag 和查询数量限制 limit。

调用该方法需要拥有管理频道黑白名单的权限（QChatRoleResource.MANAGE_BLACK_WHITE_LIST）。

示例代码如下：

//查处频道黑名单中的身份组列表
NIMClient.getService(QChatChannelService.class).getChannelBlackWhiteRolesByPage(new QChatGetChannelBlackWhiteRolesByPageParam(943445L,885305L,QChatChannelBlackWhiteType.BLACK,System.currentTimeMillis())).setCallback(new RequestCallback<QChatGetChannelBlackWhiteRolesByPageResult>() {
    @Override
    public void onSuccess(QChatGetChannelBlackWhiteRolesByPageResult result) {
        //查询成功,返回频道黑名单中身份组列表
        List<QChatServerRole> roleList = result.getRoleList();
        //下一页的起始时间戳
        long nextTimeTag = result.getNextTimeTag();
        //是否还有下一页
        boolean hasMore = result.isHasMore();
    }

    @Override
    public void onFailed(int code) {
        //查询失败，返回错误code
    }

    @Override
    public void onException(Throwable exception) {
        //查询异常
    }
});

批量查询黑白名单身份组列表

调用getExistingChannelBlackWhiteRoles方法可根据传入的身份组 ID 列表批量查询其中被加入黑白名单的身份组。

单次调用最多可传入 100 个身份组的 ID。

示例代码如下：

//查询频道中存在的黑名单身份组
List<Long> roleIds = getQueryRoles();
        QChatGetExistingChannelBlackWhiteRolesParam param = new QChatGetExistingChannelBlackWhiteRolesParam(currentChannel.getServerId(),
                currentChannel.getChannelId(), QChatChannelBlackWhiteType.BLACK,roleIds);
        NIMClient.getService(QChatChannelService.class).getExistingChannelBlackWhiteRoles(param).setCallback(
                new RequestCallback<QChatGetExistingChannelBlackWhiteRolesResult>() {
                    @Override
                    public void onSuccess(QChatGetExistingChannelBlackWhiteRolesResult result) {
                        //查询到的在黑名单中的身份组列表
                        List<QChatServerRole> roleList = result.getRoleList();
                    }

                    @Override
                    public void onFailed(int code) {
                        //查询失败，返回错误code
                    }

                    @Override
                    public void onException(Throwable exception) {
                        //查询异常
                    }
                });

枚举值	说明
`CHANNEL_UPDATE_WHITE_BLACK_MEMBER`	更新“频道黑白名单成员”
`CHANNEL_UPDATE_WHITE_BLACK_ROLE`	更新“频道黑白名单身份组”

功能介绍

前提条件

使用限制

实现方法

管理黑白名单成员

更新频道黑白名单成员

分页查询频道黑白名单成员

批量查询频道黑白名单成员

管理黑白名单身份组

更新频道黑白名单身份组

分页查询黑白名单身份组列表

批量查询黑白名单身份组列表

相关系统通知