服务器身份组 - IM 即时通讯

更新时间： 2024/03/07 11:40:17

服务器身份组指负责在服务器维度对用户进行权限控制的身份组，包括服务器下的 @everyone 身份组和自定义身份组。创建服务器时，@everyone 身份组（type == QChatRoleType.everyone）默认自动创建。而服务器自定义身份组则需要用户手动创建。自定义身份组创建后，其权限配置默认继承自 @everyone 身份组，如需调整，需要拥有相应权限的用户手动更新。此外，用户还可调整服务器身份组的优先级（需要相应权限）。

@everyone 身份组的权限配置，只有服务器创建者可修改。
Web SDK最大可以设置的整型是9007199254740991。如果超过，接收方是Web SDK时会溢出。

服务器身份组定义

SDK 中定义服务器身份组的类为QChatServerRole。该类的成员参数说明如下：

单击展开查看 QChatServerRole 的成员参数

参数	返回数据类型	说明
`roleId`	int	身份组 ID
`serverId`	int	身份组所属服务器的 ID
`name`	String	身份组名称
`icon`	String	身份组图标的 URL
`extension`	String	身份组的扩展字段
`resourceAuths`	Map<`QChatRoleResource`, `QChatRoleOption`	身份组的权限列表，其中: `QChatRoleResource`表示身份组的权限项，具体说明请参见身份组权限项 `QChatRoleOption`定义了权限的配置状态（即用户能否访问各权限），包括： `allow`：开启（身份组成员有权限） `deny`：关闭（身份组成员无权限） `inherit`：继承（继承 @everyone 身份组中对应相同权限的配置状态）
`type`	`QChatRoleType`	返回身份组的类型，1 表示@everyone 身份组，2 表示自定义身份组
`memberCount`	int	身份组的成员数量，@ everyone 身份组的成员数量数量默认为-1
`priority`	int	身份组优先级，用于判定身份组成员是否能修改其他身份组的权限配置。自定义身份组优先级取值大于0，数字越小优先级越高。高优先级身份组中拥有管理角色权限的用户，可修改低优先级身份组的权限，但无法修改更高优先级身份组的权限。 @everyone 身份组优先级取值为 0 且不能更改，默认低于自定义身份组优先级
`createTime`	int	身份组的创建时间
`updateTime`	int	身份组配置的更新时间

前提条件

已注册onReceiveSystemNotification事件流，监听系统通知的接收。示例代码参见接收圈组内置系统通知。

具体与服务器身份组相关的系统通知类型，见本文末尾的相关系统通知。
已创建服务器。

实现方法

以下时序图以典型场景为例，介绍通过服务器身份组进行权限控制的流程。该典型场景为：服务器创建者将频道管理权限（manageChannel）授予服务器成员，从而使该成员能够创建频道。

以下时序图可能因网络问题而显示异常。如显示异常，一般刷新当前页面即可正常显示。

本节仅对上图中标为橙色的方法调用做详细说明，其他方法调用请参考相应的文档。

步骤1：创建服务器身份组

调用createServerRole方法创建自定义身份组（type == QChatRoleType.custom）。调用成功后，可以从返回的QChatCreateServerRoleResult获得新建的服务器身份组QChatServerRole。

新创建的自定义身份组的权限为用户所有已有身份组的权限之和。假设用户在创建之前，只属于 @everyone 身份组的成员，则新创建的自定义身份组的权限将继承 @everyone 身份组的权限，两者权限一致。如需修改，还需要调用updateServerRole方法，具体请参见下文的更新服务器身份组。

调用该方法需要拥有manageRole权限，且必须是相应服务器的成员。如果没有该权限，调用该方法将返回 403 错误码。
新创建的服务器自定义身份组的优先级，必须小于用户已有身份组的最高优先级。
单个服务器内可创建的服务器身份组数量上限，默认为 20 个。
可在云信控制台配置单个服务器内的身份组数量上限
在云信控制台选择应用，进入IM 专业版 > 功能权限开通 > 拓展配置 > 圈组 > 高级配置 > 单server可创建的身份组即可配置。

示例代码

dartfinal antiSpamConfig = QChatAntiSpamConfig()
  ..antiSpamBusinessId = "用户配置的对某些资料内容另外的内容审核（反垃圾）的业务ID";
final param = QChatCreateServerRoleParam(serverId,"测试身份组名称",QChatRoleType.custom)
  ..extension = "自定义扩展字段"
  ..icon = "http://xxxxxx/xxxxx/x/xx"
  ..antiSpamConfig = antiSpamConfig;
NimCore.instance.qChatRoleService.createServerRole(param).then((value) {
  if (value.isSuccess) {
    // 创建成功，返回创建成功的Server身份组信息
    var role = value.data?.role;
  } else {
    // 创建失败
  }
});

上述示例代码中的QChatAntiSpamConfig为圈组内容审核配置，具体说明请参见圈组内容审核。

步骤2：修改服务器身份组

调用updateServerRole方法可修改服务器身份组的名称、图标、自定义扩展字段、权限列表配置和优先级（优先级的具体介绍请参见下文的批量更新服务器身份组优先级）。调用时，需在其入参结构 QChatUpdateServerRoleParam 传入服务器身份组的 ID 和身份组所属服务器的 ID。

调用该方法需要管理角色权限（manageRole），且必须是相应服务器的成员。如没有该权限，调用将返回 403 错误码。
该方法仅支持修改自定义身份组。创建服务器时默认创建的 @everyone 身份组不支持修改。如调用该方法修改 @everyone 身份组信息（身份组的名称、图标、自定义扩展和优先级），将报错（错误码 403）。
调用该方法修改身份组的优先级必须小于用户已有身份组的最高优先级。
用户无法配置自己没有的权限。例如用户没有权限A，则无法修改权限A 的配置。
用户无法将自己拥有的某个权限在全部所属身份组中都设置为deny。例如用户属于 10 个身份组且这 10 个身份组都开启了权限A，那么用户最多可以将其中 9 个身份组的权限A 设置为deny。

示例代码

dartQChatServerRole serverRole = getServerRole();
final antiSpamConfig = QChatAntiSpamConfig()
  ..antiSpamBusinessId = "用户配置的对某些资料内容另外的内容审核（反垃圾）的业务ID";
final param = QChatUpdateServerRoleParam(serverRole.serverId!, serverRole.roleId!)
  ..name = "修改身份组名称"
  ..icon = "http://xxxxxx/xxx/"
  ..ext = "修改自定义扩展"
  ..priority = 2
  ..resourceAuths = {QChatRoleResource.manageBlackWhiteList: QChatRoleOption.allow}
  ..antiSpamConfig = antiSpamConfig;
NimCore.instance.qChatRoleService.updateServerRole(param).then((value) {
  if (value.isSuccess) {
    // 更新成功，返回更新后的Server身份组
    var role = value.data?.role;
  } else {
    // 更新失败
  }
});

步骤3：添加身份组成员

服务器的 @everyone 身份组的成员，默认为服务器的全部成员。服务器自定义身份组的成员，需要用户手动添加。

调用addMembersToServerRole 方法将用户批量添加至指定的服务器自定义身份组。添加后，继承自该服务器身份组的频道身份组成员也会作相应变化。

QChatAddMembersToServerRoleParam为该方法的入参结构，需要传入操作者所属的服务器 ID、服务器身份组 ID 和待添加用户的 IM 账号（accid）列表。

调用该方法必须先拥有manageRole权限。如果没有该权限，调用该方法将返回 403 错误码。

示例代码

dartfinal param = QChatAddMembersToServerRoleParam(serverId,roleId,[accId1]);
NimCore.instance.qChatRoleService.addMembersToServerRole(param).then((value) {
  if (value.isSuccess) {
    // 操作成功,返回加入成功和加入失败的成员accid列表
    var successAccids = value.data?.successAccids;
    var failedAccids = value.data?.failedAccids;
  } else {
    // 操作失败
  }
});

其他相关 SDK API

移除身份组成员

可调用removeMembersFromServerRole方法将服务器自定义身份组的成员批量移除。移除后，继承自该服务器身份组的频道身份组成员也会作相应变化。

该方法的入参结构为QChatRemoveMembersFromServerRoleParam，需要传入操作者所属的服务器 ID、服务器身份组 ID 和待移除的成员的 IM 账号（accid）列表。

调用该方法必须先拥有manageRole权限。如果没有该权限，调用该方法将返回 403 错误码。

示例代码

dartfinal param = QChatRemoveMembersFromServerRoleParam(serverId,roleId,[accId1]);
NimCore.instance.qChatRoleService.removeMembersFromServerRole(param).then((value) {
  if (value.isSuccess) {
    // 操作成功,返回加入成功和加入失败的成员accid列表
    var successAccids = value.data?.successAccids;
    var failedAccids = value.data?.failedAccids;
  } else {
    // 操作失败
  }
});

删除服务器身份组

拥有manageRole权限的用户可调用deleteServerRole方法删除包含此权限的自定义身份组。调用该方法时，入参结构 QChatDeleteServerRoleParam 需要传入待删除的身份组的 ID 和该身份组所属的服务器 ID。

调用该方法必须先拥有manageRole权限，且必须是相应服务器的成员。如果没有该权限，调用该方法将返回 403 错误码。
@everyone 身份组默认不可删除。
用户无法删除优先级高于自己已有身份组的最高优先级的身份组。

示例代码

dartfinal param = QChatDeleteServerRoleParam(serverId,roleId);
NimCore.instance.qChatRoleService.deleteServerRole(param).then((value) {
  if (value.isSuccess) {
    // 删除成功
  } else {
    // 删除失败
  }
});

批量更新服务器身份组优先级

身份组有优先级高低之分。当用户拥有manageRole权限后，可对等级低于自身最高优先级身份组的其他身份组进行操作（如修改权限配置），也可创建一个新的自定义身份组，并对其进行优先级排序。新的自定义身份组被创建后，其优先级默认为用户所属自定义身份组中最低。

调用updateServerRolePriorities方法可同时修改多个服务器身份组的优先级，其中QChatUpdateServerRolePrioritiesParam需要传入服务器 ID、服务器身份组 ID 和身份组优先级构成的 Map。

调用该方法需要拥有manageRole权限。如果没有该权限，调用该方法将返回 403 错误码。当拥有manageRole权限的用户想去变更某个低优先级身份组的某项权限时，首先其自身必须有该权限，即该用户所在的所有身份组中，至少有一个身份组为其赋予过该权限。
自定义身份组等级永远高于@everyone身份组。
修改后的优先级必须在修改前的最高优先级和最低优先级之间。比如，修改前 serverRole1 优先级 p1，serverRole2 优先级 p2，serverRole3 优先级 p3，想把他们的优先级分别改为 P1、P2 和 P3，必须满足 min(P1，P2，P3) >= min(p1，p2，p3)，max(P1，P2，P3) <= max(p1，p2，p3)。

示例代码

dartfinal param = QChatUpdateServerRolePrioritiesParam(serverId,{
  roleId1: 3,
  roleId2: 4,
  roleId3: 5,
});
NimCore.instance.qChatRoleService.updateServerRolePriorities(param).then((value){
  if (value.isSuccess) {
    // 修改成功，返回修改后的Server身份组Id和Server身份组优先级构成的Map
    var roleIdPriorityMap = value.data.roleIdPriorityMap;
  } else {
    // 修改失败
  }
});

API 调用时序示例

以下时序图以用户A（服务器创建者）和用户B（服务器成员）的交互场景为例，展示在调用updateServerRolePriorities方法前需要实现的业务逻辑。

单击展开查看 API 调用时序示例

以下时序图可能因网络问题而显示异常。如显示异常，一般刷新当前页面即可正常显示。

服务器身份组相关查询

NIM SDK 提供了服务器身份组查询相关的方法，如查询服务器身份组列表和服务器身份组成员列表，具体请参见服务器身份组相关查询。

枚举值	说明
`server_role_auth_update`	“服务器身份组”权限更新
`server_role_member_add`	新成员加入“服务器身份组”
`server_role_member_delete`	成员被移出“服务器身份组”