服务器身份组指负责在服务器维度对用户进行权限控制的身份组，包括服务器下的 @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）授予服务器成员，从而使该成员能够创建频道。

sequenceDiagram



note over QChat 实例: 初始化并登录
note over QChat 实例: 用户A 将权限授予用户 B
用户A ->> QChat 实例: 创建服务器
用户A ->> QChat 实例: 创建服务器身份组<br>(createServerRole)
用户A ->> QChat 实例: 修改服务器身份组<br>(updateServerRole)
note over 用户A: 修改时将频道管理权限开启，<br>使该身份组的成员拥有该权限
用户A ->> QChat 实例: 邀请用户B 加入服务器
用户B ->> QChat 实例: 接受邀请加入服务器
note over 用户B: 用户B 需要先加入服务器，<br>才能被添加为身份组成员
用户A ->> QChat 实例: 添加身份组成员<br>(addMembersToServerRole)
note over 用户A: 将用户B 加入该服务器身份组，<br>使用户B 获得频道管理权限
note over QChat 实例: 用户B 创建频道
note over 用户B: 用户B 拥有了频道管理权限，<br>可进行频道创建操作
用户B ->> QChat 实例: 在服务器内创建频道

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

步骤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 调用时序示例

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

  sequenceDiagram
  
  note over QChat 实例: 初始化与登录
  用户A ->> QChat 实例: 初始化
  用户B ->> QChat 实例: 初始化
  用户A ->> QChat 实例: 登录圈组
  用户B ->> QChat 实例: 登录圈组
  note over QChat 实例: 用户A 创建服务器
  用户A ->> QChat 实例: 创建服务器
  note over QChat 实例: 用户A 创建多个身份组并授予用户B 权限
  用户A ->> QChat 实例: 创建身份组1 
  note left of 用户A: 身份组1 的优先级默认高于<br>之后新创建的身份组
  用户A ->> QChat 实例: 修改身份组1
  note over 用户A: 调用修改身份组接口<br>开启身份组1的管理角色权限，<br>使该身份组的成员拥有该权限
  用户A ->> QChat 实例: 创建身份组2
  用户A ->> QChat 实例: 创建身份组3
  用户A ->> QChat 实例: 邀请用户B 加入服务器
  用户B ->> QChat 实例: 接受邀请加入服务器
  note left of 用户B: 需先加入服务器<br>才能被添加为身份组成员
  用户A ->> QChat 实例: 将用户B 加入身份组1
  note left of 用户A: 用户B 加入身份组1 后，<br>获得管理角色权限
  
  note over QChat 实例: 用户B 批量更新身份组优先级
  note left of 用户B: 用户B 获得管理角色权限后，<br>可进行身份组管理操作
  用户B ->> QChat 实例: 创建身份组4
  note left of 用户B: 由于用户B 所属的身份组1<br>优先级高于身份组2、3、4，<br>所以用户B 可批量更新2、3、4 的优先级
  用户B ->> QChat 实例: 批量更新身份组2,3,4的优先级
  

服务器身份组相关查询

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

相关系统通知

圈组系统通知的类型在QChatSystemNotificationType枚举中定义，与服务器身份组相关的内置系统通知类型如下：

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

这三种系统通知的接收条件，请参见服务端文档的身份组成员管理相关通知和身份组权限相关事件通知。