本文以多用户交互的典型场景为例，介绍在频道分组维度对用户进行权限控制的实现方法和示例代码。

技术原理

网易云信 QChat Web SDK 的QChatRoleServiceInterface接口提供管理频道分组身份组的相关方法（如addChannelCategoryRole），助您快速实现在频道分组维度对不同用户的权限控制。

调用这些方法，需要管理角色的权限（QChatRoleAuth枚举中的manageRole）。

新创建的频道分组身份组的权限，默认继承自指定的服务器身份组（通过服务器身份组的 ID 指定）。如果需要在频道分组维度设置和服务器维度有区分的用户权限，需在创建频道分组身份组后调用updateChannelCategoryRole方法对权限做更改；或者调用addChannelCategoryMemberRole方法创建成员在频道分组的定制权限，再调用updateChannelCategoryMemberRole方法设置具体的权限。

实现方法

本节以服务器所有者和服务器成员的交互为例（服务器成员仅被授予管理角色的权限的场景），介绍服务器成员创建频道分组身份组的实现流程。

• 服务器所有者可以在创建服务器和频道分组后直接调用AddChannelCategoryRole方法创建频道分组身份组。
• 创建后，用户可更新、删除、查询频道分组身份组，相关方法见本文的API 参考。
• 服务器成员创建频道分组某人的定制权限的实现，可参考本场景的流程。

前提条件

• 已接入圈组，并已创建圈组服务器和身份组。
• 已创建 2 个云信 IM 账号，作为下文中服务器所有者和服务器成员的云信 IM 账号。

实现流程

1. 服务器所有者调用addMembersToServerRole方法，将服务器成员加入身份组。

2. 服务器所有者调用updateServerRole方法，授予该身份组管理角色的权限（manageRole）。

   结果：

   服务器成员将拥有管理角色的权限。

3. 服务器所有者调用createChannelCategory方法，创建频道分组。

4. 如果创建的是私密频道分组，服务器所有者需调用updateChannelCategoryWhiteBlackMembers方法，将该成员加入频道分组白名单。

   如果创建的是公开频道分组，请跳过这一步。

5. 服务器成员调用getServerRoles方法，查询目标服务器身份组 ID（serverRoleId）。

   如果服务器成员在服务器维度没有管理角色的权限，但在频道分组维度有该权限时，调用getServerRoles方法时传入频道分组 ID（categoryId）才能查询服务器的身份组列表，进而获取目标服务器身份组 ID。

6. 服务器成员调用addChannelCategoryRole方法，创建频道分组身份组。

   入参	类型	是否必传	说明
   categoryId	long	是	频道分组 ID
   serverId	long	是	频道分组所在的服务器的 ID
   parentRoleId	long	是	服务器身份组 ID。生成的频道分组身份组的权限默认从该服务器身份组继承

   服务器成员可通过圈组的内置系统通知（ESystemMessageType枚举的channelCategoryCreate获知categoryId。如服务器成员人数超过目前默认的阈值 2,000（可联系商务经理调整），成员需调用subscribeServer方法订阅服务器才能接收到该系统通知。服务器成员人数在阈值内，则不需要订阅服务器也能接收到。

API 调用时序图

示例代码

服务器所有者

// 1. 创建服务器身份组，并且赋予身份组管理角色的权限
const role = await qchat.qchatRole.createServerRole({
  serverId: 'YOUR_SERVER_ID',
  channelId: 'YOUR_CHANNEL_ID',
  name: 'test server role'
})

await qchat.qchatRole.updateServerRole({
  serverId: role.serverId,
  roleId: role.roleId,
  auths: {
    manageRole: 'allow'
  }
})

// 2. 创建者将某成员加入这个服务器身份组
await qchat.qchatRole.addMembersToServerRole({
  serverId: role.serverId,
  roleId: role.roleId,
  accids: ['ACCOUNT_ID_OF_A_MEMBER']
})

// 3. 创建两个频道分组，一个公开，一个私密
const category1 = await qchat.qchatChannel.createChannelCategory({
  serverId: role.serverId,
  viewMode: 0
})

const category2 = await qchat.qchatChannel.createChannelCategory({
  serverId: role.serverId,
  viewMode: 1
})

// 4 私密的“频道分组”需要将身份组拉入私密的“频道分组”的白名单中。
// 该身份组所属的用户都将在私密的“频道分组”的白名单中。
await qchat.qchatChannel.updateChannelCategoryWhiteBlackRole({
  categoryId: category2.categoryId,
  serverId: category2.serverId,
  type: 'white',
  opeType: 'add',
  roleId: role.roleId
})

服务器成员

// 5. 用户可以管理“频道分组”的身份组，试试添加一个吧
// 注意：被添加/移除身份组目前没有系统通知，这里我们当做是这个账号已经查询得知了下面的参数。
qchat.on('systemNotification', function(event) {
  if (event.systemNotifications && event.systemNotifications[0]
    && event.systemNotifications[0].type === 'channelCategoryCreate') {
    const { categoryId, serverId } = event.systemNotifications.attach.categoryInfo
    
    // 需要得到关键的 roleId， 这里需要查询一遍，仅供演示。实际是需要开发者自己关联查询界面去做。
    const serverRoles = await qchat.qchatRole.getServerRoles({
      serverId: 'YOUR_SERVER_ID'
    })
    // 假定是要给第二个自定义的服务器身份组添加“频道分组”的身份组。
    const serverRoleId = serverRoles && serverRoles[1] && serverRoles[1].roleId
    if (!serverRoleId) { return }
    await qchat.qchatRole.addChannelCategoryRole({
      serverId: 'YOUR_SERVER_ID',
      categoryId: 'YOUR_CATEGORY_ID',
      parentRoleId: serverRoleId
    })    
  }
})

API 参考

API	说明
addChannelCategoryRole	创建频道分组身份组。创建后，默认继承服务器身份组的权限。如需更改权限，需调用updateChannelCategoryRole
removeChannelCategoryRole	删除频道分组身份组
updateChannelCategoryRole	更新频道分组身份组。设置频道分组身份组的权限，需调用该方法
getChannelCategoryRole	查询频道分组身份组信息
addChannelCategoryMemberRole	创建频道分组某人的定制权限，创建后还需调用updateChannelCategoryMemberRole才能授予某人权限
removeChannelCategoryMemberRole	删除频道分组某人的定制权限
updateChannelCategoryMemberRole	修改频道分组某人的定制权限。创建某人定制权限后，需再调用本方法才能授予某人权限
getChannelCategoryMemberRole	查询频道分组某人的定制权限