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

本文介绍通过服务器身份组进行权限控制的流程，以及其他与服务器身份组相关的 SDK API。

@everyone 身份组的权限配置，只有服务器创建者可修改。@everyone 身份组的其他信息（身份组的名称、图标、自定义扩展和优先级）不支持修改。

服务器身份组数据结构

服务器身份组由QChatServerRole定义。该结构体的参数说明如下：

参数	类型	说明
roleId	string	身份组 ID
serverId	string	身份组所属服务器的 ID
name	string	身份组名称
icon	string	身份组图标的 URL
ext	string	身份组的扩展字段
auths	QChatRoleAuth	权限对象，key-value 形式提供，格式如{ key1: 'ignore', key2: 'allow', key3: 'deny' } 其中ignore、allow和deny表示权限在身份组中的状态，分别为“继承”、“开启”和“关闭”。
type	TRoleType	身份组的类型，eveyone：@everyone 身份组，custom: 自定义身份组
memberCount	number	身份组的成员数量，@ everyone 身份组的成员数量数量默认为-1
priority	number	身份组优先级（具体见下文的批量更新服务器身份组优先级），用于判定身份组成员是否能修改其他身份组的权限配置。自定义身份组优先级取值大于0，数字越小优先级越高。高优先级身份组中拥有管理角色权限的用户，可修改低优先级身份组的权限，但无法修改更高优先级身份组的权限。 @everyone 身份组优先级取值为 0 且不能更改，默认低于自定义身份组优先级
createTime	number	身份组的创建时间
updateTime	number	身份组配置的更新时间

前提条件

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

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

• 已创建服务器。

使用限制

单个服务器内可创建的服务器身份组数量上限，默认为 20 个。

若需要扩展上限，可在控制台配置圈组子功能项（单 server 可创建的身份组），具体请参考开通和配置圈组功能。

实现流程

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

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

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

调用createServerRole方法创建自定义身份组。调用成功后，返回新建的服务器身份组QChatServerRole。

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

• 调用该方法需要拥有manageRole权限，且必须是相应服务器的成员。如果没有该权限，调用该方法将返回 403 错误码。
• 新创建的服务器自定义身份组的优先级，必须小于用户已有身份组的最高优先级。

• API 原型

  createServerRole(options: CreateServerRoleOptions): Promise<QChatServerRole>
  

  类型	参数名	说明
  serverId	string	serverId
  type	string	类型，"everyone" 或者 "custom"
  auths	QChatRoleAuth	权限对象，key-value 形式提供
  priority	number	权限优先级，数字越小，优先级越高

• 示例代码

  const serverRole = await qchat.qchatRole.createServerRole({
  "serverId": "1377422",
  "name": "serverRole1",
  "priority": 9
  })
  
  console.log(serverRole)
  // {
  //     "serverId": "1377422",
  //     "roleId": "1246243",
  //     "name": "serverRole1",
  //     "auths": {
  //         "manageServer": "allow",
  //         "manageChannel": "allow",
  //         "manageRole": "allow",
  //         "sendMsg": "allow",
  //         "accountInfoSelf": "allow",
  //         "inviteServer": "allow",
  //         "kickServer": "allow",
  //         "accountInfoOther": "allow",
  //         "recallMsg": "allow",
  //         "deleteMsg": "allow",
  //         "remindOther": "allow",
  //         "remindEveryone": "allow",
  //         "manageBlackWhiteList": "allow"
  //     },
  //     "type": "custom",
  //     "memberCount": 0,
  //     "priority": 9,
  //     "createTime": 1646186783776,
  //     "updateTime": 1646186783776,
  //     "antispamTag":{
  //        "textbid":"",
  //        "picbid"：“”
  //     }
  // }
  

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

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

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

• API 原型

  updateServerRole(options: UpdateServerRoleOptions): Promise<QChatServerRole>
  

• 示例代码

  let serverRole = await qchat.qchatRole.createServerRole({
  "serverId": "1377422",
  "name": "serverRole1",
  "priority": 9
  })
  
  serverRole = await qchat.qchatRole.updateServerRole({
  serverId: serverRole.serverId,
  roleId: serverRole.roleId,
  name: "testServerRole",
  ext: "This is a ext",
  icon: "http://icon",
  auths: {
      deleteMsgs: "allow"
  },
  antispamTag:{
      textbid:"",
      picbid：“”
  }
  priority: 10
  })
  
  

步骤3：添加身份组成员

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

调用addMembersToServerRole 方法将用户批量添加至指定的服务器自定义身份组。

添加后，继承自该服务器身份组的频道身份组成员也会作相应变化。频道身份组与服务器身份组在成员的具体关联为：公开频道的身份组成员等于被继承的服务器身份组成员去掉频道黑名单成员和频道黑名单身份组成员；私密频道的身份组成员是同时存在于频道白名单和被继承的服务器身份组的公共成员。

• 调用该方法必须先拥有manageRole权限。如果没有该权限，调用该方法将返回 403 错误码。
• 待加入用户必须为身份组所属服务器成员，才能被成功加入该身份组。
• 将用户加入某服务器身份组会触发系统通知。具体的触发条件和接收条件请参考圈组系统通知。

• API 原型

  addMembersToServerRole(options: AddMembersToServerRoleOptions): Promise<AddMembersToServerRoleResult>
  

• 示例代码

  const result = await qchat.qchatRole.addMembersToServerRole({
  "serverId": "{{YOUR_SERVER_ID}}",
  "roleId": "{{YOUR_ROLE_ID}}",
  "accids": ["{{TARGET_ACCOUNT_ID1}}", "{{NO_EXIST_ACCOUNT_ID2}}"]
  })
  
  console.log(result)
  // {
  //   "successAccids": ["{{TARGET_ACCOUNT_ID1}}"],
  //   "failedAccids": ["{{NO_EXIST_ACCOUNT_ID2}}"]
  // }
  

其他相关 SDK API

移除身份组成员

可调用removeMembersFromServerRole方法将服务器自定义身份组的成员批量移除。

移除服务器身份组成员后，继承自该服务器身份组的频道身份组成员也会作相应变化。频道身份组与服务器身份组在成员的具体关联为：公开频道的身份组成员等于被继承的服务器身份组成员去掉频道黑名单成员和频道黑名单身份组成员；私密频道的身份组成员是同时存在于频道白名单和被继承的服务器身份组的公共成员。

• 调用该方法必须先拥有manageRole权限。如果没有该权限，调用该方法将返回 403 错误码。
• 将用户移出某服务器身份组会触发系统通知。具体的触发条件和接收条件请参考圈组系统通知。

• API 原型

  removeMembersFromServerRole(options: RemoveMembersFromServerRoleOptions): Promise<RemoveMembersFromServerRoleResult>
  

• 示例代码

  await qchat.qchatRole.addMembersToServerRole({
  "serverId": "{{YOUR_SERVER_ID}}",
  "roleId": "{{YOUR_ROLE_ID}}",
  "accids": ["{{TARGET_ACCOUNT_ID1}}", "{{NO_EXIST_ACCOUNT_ID2}}"]
  })
  
  const result = await qchat.qchatRole.removeMembersFromServerRole({
  "serverId": "{{YOUR_SERVER_ID}}",
  "channelId": "{{YOUR_CHANNEL_ID}}",
  "accids": ["{{TARGET_ACCOUNT_ID1}}"]
  })
  
  console.log(result)
  // {
  //   "successAccids": ["{{TARGET_ACCOUNT_ID1}}"],
  //   "failedAccids": []
  // }
  

删除服务器身份组

拥有manageRole权限的用户可调用deleteServerRole方法删除包含此权限的自定义身份组。

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

• API 原型

  deleteServerRole(options: DeleteServerRoleOptions): Promise<void>
  

• 示例代码

  let serverRole = await qchat.qchatRole.createServerRole({
  "serverId": "1377422",
  "name": "serverRole1",
  "priority": 9
  })
  
  serverRole = await qchat.qchatRole.deleteServerRole({
  serverId: serverRole.serverId,
  roleId: serverRole.roleId
  })
  
  

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

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

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

最佳实践：建议把 priority 为 1 的身份组空出来，不要用在业务上。可以把这个 priority 为 1 的身份组专门留给最高管理员使用，方便后面调整其他身份组的优先级。

• 调用该方法需要拥有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)。

• API 调用时序示例

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

  

• API 原型

  updateServerRolePriorities(options: UpdateServerRolePrioritiesOptions): Promise<QChatServerRole[]>
  

• 示例代码

  let serverRole1 = await qchat.qchatRole.createServerRole({
  "serverId": "1377422",
  "name": "serverRole1",
  })
  
  console.log(serverRole1.priority) // 1
  
  let serverRole2 = await qchat.qchatRole.createServerRole({
  "serverId": "1377422",
  "name": "serverRole2",
  })
  
  console.log(serverRole1.priority) // 2
  
  let serverRole3 = await qchat.qchatRole.createServerRole({
  "serverId": "1377422",
  "name": "serverRole3",
  })
  
  console.log(serverRole1.priority) // 3
  
  // swap 1 to 3
  await qchat.qchatRole.updateServerRolePriorities({
  "serverId": "1377422",
  "serverRoles": [
      {
      "serverId": "1377422",
      "roleId": serverRole1.roleId,
      "priority": serverRole3.priority
      },
      {
      "serverId": "1377422",
      "roleId": serverRole2.roleId,
      "priority": serverRole2.priority
      },
      {
      "serverId": "1377422",
      "roleId": serverRole3.roleId,
      "priority": serverRole1.priority
      }
  ]
  })
  
  

API 参考

API	说明
createServerRole	创建服务器自定义身份组
updateServerRole	修改服务器身份组的信息，包括名称、图标、自定义扩展字段、权限列表配置和优先级
deleteServerRole	删除服务器自定义身份组，@everyone 身份组默认不可删除
updateServerRolePriorities	批量更新服务器身份组优先级
addMembersToServerRole	将用户批量添加至服务器自定义身份组
removeMembersFromServerRole	将用户批量从服务器自定义身份组中移除