身份组管理 - IM 即时通讯

IM 即时通讯

不含 UI 集成

开发者中心

更新时间： 2022/12/21 15:55:40

SDK 提供一套完善的圈组身份组管理服务，它有着比较明确的继承逻辑，使用前请翻阅身份组系统。

有两个维度的权限，频道维度、频道分组维度，其中频道身份组的权限可以选择是否同步自“频道分组”，结构如下

// 频道维度
├── QChatServerRole 服务器身份组定义
├── QChatChannelRole 频道身份组定义，权限优先级比服务器身份组高
├── QChatMemberRole 频道下给个人定制的身份，优先级最高

// “频道分组”维度
├── QChatServerRole 服务器身份组定义
├── QChatChannelCategoryRole “频道分组”的身份组定义，权限优先级比服务器身份组高
├── QChatChannelCategoryMemberRole “频道分组”下给个人定制的身份，优先级最高

QChatServerRole 参见 TS 定义 QChatRoleServiceInterface-QChatServerRole
QChatChannelRole 参见 TS 定义 QChatRoleServiceInterface-QChatChannelRole
QChatMemberRole 参见 TS 定义 QChatRoleServiceInterface-QChatMemberRole
QChatChannelCategoryRole 参见 TS 定义 QChatRoleServiceInterface-QChatChannelCategoryRole
QChatChannelCategoryMemberRole 参见 TS 定义 QChatRoleServiceInterface-QChatChannelCategoryMemberRole

创建服务器身份组

接口

服务器创建时会自动创建 @所有人的身份组(type === "everyone")。
通过 createServerRole 接口可以创建自定义身份组(type === "custom")。

@所有人身份组的权限配置，只有服务器创建者可修改。

/**
 * 新增服务器身份组
 */
createServerRole(options: CreateServerRoleOptions): Promise<QChatServerRole>

QChatServerRole 完整定义参见 TS 定义 QChatRoleServiceInterface-QChatServerRole，下面列出其中的重要属性

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

9.3.0 版本新增实时互动频道相关权限、申请邀请管理权限以及申请邀请历史查看权限类型，具体请参见QChatRoleAuth。

其中，权限字段 auths 提供 key-value 形式的键值对，完整的权限属性参照上文 TS 定义，其形式如：

auths: {
  // 管理服务器：修改服务器。仅 server 的身份组有此权限可配置
  "manageServer": "allow",
  // 管理频道，server 和 channel 的身份组都有此权限配置
  "manageChannel": "ignore",
  // 管理角色的权限，server 和 channel 的身份组都有此权限配置
  "manageRole": "deny",
  ...
}

allow 为允许，deny 为拒绝此权限，ignore 为忽略，继承自上层权限。如果拥有多个自定义的身份组针对同一个权限分别设置 allow，deny，ignore，那么 allow 的优先级最高，deny 次之。

createServerRole接口需要管理角色的权限，即 manageRole 资源项的选项需要为 allow。

示例代码

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"：“”
//     }
// }

安全通相关

新增服务器身份组参数中如果带上 antiSpamBusinessId 则会对参数信息进行安全通检查。antiSpamBusinessId 代表安全通自定义业务 ID；如需新增安全通自定义业务，请联系商务经理进行相关配置，然后前往云信控制台的安全通配置界面获取该业务 ID。

移除服务器身份组

接口

自定义身份组 可以通过 deleteServerRole 接口删除。该接口需要 manageRole 权限。

/**
 * 移除服务器身份组
 */
deleteServerRole(options: DeleteServerRoleOptions): Promise<void>

完整 TS 定义参见 QChatRoleServiceInterface-deleteServerRole

示例代码

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

serverRole = await qchat.qchatRole.deleteServerRole({
  serverId: serverRole.serverId,
  roleId: serverRole.roleId
})

更新服务器身份组信息

接口

调用 updateServerRole 方法可以修改服务器身份组的 name、icon、ext、auths 和 priority 字段。

该接口需要 manageRole 权限。
仅自定义身份组（即 ERoleType 为 CUSTOM 的身份组）支持调该方法更新身份组信息。创建身份组时默认创建的 @everyone 身份组（即 ERoleType 为 EVERYONE 的身份组）不支持调用该方法更新身份组信息。@everyone身份组只支持修改其定义的权限。如调用该方法更新 @everyone 身份组更新其信息（身份组的名称，图标，自定义扩展，优先级），将报错（错误码 403）。

/**
 * 修改服务器身份组信息
 */
updateServerRole(options: UpdateServerRoleOptions): Promise<QChatServerRole>

其中 UpdateServerRoleOptions 需要传入服务器身份组的 serverId 和 roleId。
可以修改 serverRole 的名称，图标，自定义扩展，优先级和权限。

示例代码

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
})

修改服务器身份组信息参数中如果带上 antiSpamBusinessId 则会对参数信息进行安全通检查。antiSpamBusinessId 代表安全通自定义业务 ID；如需新增安全通自定义业务，请联系商务经理进行相关配置，然后前往云信控制台的安全通配置界面获取该业务 ID。
只有修改服务器身份组中的权限信息，才会触发系统通知。具体的触发条件和接收条件请参考圈组系统通知。

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

接口

updateServerRolePriorities 接口可以同时修改多个服务器身份组的优先级。请开发者自行计算好 priority

/**
 * 批量更新 serverRole 的优先级
 */
updateServerRolePriorities(options: UpdateServerRolePrioritiesOptions): Promise<QChatServerRole[]>

修改后的优先级必须在修改前的优先级范围之内。比如，修改前 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)。
该接口需要 manageRole 权限。

示例代码，交换两个权限的优先级。

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
    }
  ]
})

查询某服务器下身份组列表

getServerRoles 通过分页方式查询服务器身份组列表，查询结果按照 priority 数值的升序排列。

完整 TS 定义参见 QChatRoleServiceInterface-getServerRoles

/**
 * 查询服务器下身份组列表
 */
getServerRoles(options: GetServerRolesOptions): Promise<GetServerRolesResult>

注意，查询的第一页一定会包含 everyone 默认的身份组，因此返回的结果可能会突破 limit 上限。

示例代码

const roles = await qchat.qchatRole.getServerRoles({
  "serverId": "1001190",
  "timetag": 0
})

console.log(roles)
// {
//     "roles": [
//         {
//             "serverId": "1001190",
//             "roleId": "706315",
//             "name": "@everyOne",
//             "icon": "",
//             "auths": {
//                 "manageServer": "allow",
//                 "manageChannel": "deny",
//                 "manageRole": "deny",
//                 "sendMsg": "allow",
//                 "accountInfoSelf": "allow",
//                 "inviteServer": "allow",
//                 "kickServer": "deny",
//                 "accountInfoOther": "deny",
//                 "recallMsg": "deny",
//                 "deleteMsg": "deny",
//                 "remindOther": "allow",
//                 "remindEveryone": "allow",
//                 "manageBlackWhiteList": "deny"
//             },
//             "type": "everyone",
//             "priority": 0,
//             "createTime": 1645090303618,
//             "updateTime": 1645608234657
//         },
//         {
//             "serverId": "1001190",
//             "roleId": "1246291",
//             "name": "计算机1111",
//             "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": 1646190551938,
//             "updateTime": 1646190551938
//         },
//         {
//             "serverId": "1001190",
//             "roleId": "1246297",
//             "name": "计1212算机1111",
//             "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": 10,
//             "createTime": 1646190793107,
//             "updateTime": 1646190793107
//         }
//     ],
//     "isMemberRoles": [
//         "1246291",
//         "1246297"
//     ]
// }

新增频道身份组

接口

默认情况下，频道直接使用服务器身份组来控制权限。通过 addChannelRole 接口可以通过继承某个服务器身份组来新增一个频道身份组。

/**
 * 将某身份组加入某频道
 */
addChannelRole(options: AddChannelRoleOptions): Promise<QChatChannelRole>

频道身份组 QChatChannelRole 完整 TS 定义参见 QChatRoleServiceInterface-QChatChannelRole

/**
 * 频道身份组 
 */
export type QChatChannelRole = {
  serverId: string
  channelId: string
  /**
   * 权限对象
   */
  auths: QChatRoleAuth
  /**
   * 身份组 id
   */
  roleId: string
  /**
   * 继承服务器的身份组id
   */
  parentRoleId: string
  /**
   * 身份组类型： everyone 标志所有人都适用的身份组, custom 表示针对个人可定制的身份组
   */
  type: TRoleType
  /**
   * 身份组扩展字段
   */
  ext?: string
  /**
   * 身份组图标
   */
  icon?: string
  /**
   * 身份组名称
   */
  name: string
  createTime: number
  updateTime: number
}

新创建的频道身份组和被继承的服务器身份组有以下联系：

公开频道的身份组成员等于被继承的服务器身份组成员去掉频道黑名单成员和频道黑名单身份组成员；私密频道的身份组成员是同时存在于频道白名单和被继承的服务器身份组的公共成员，以及同时存在于频道白名单身份组和被继承的服务器身份组的公共成员。
刚创建时两者权限一样。频道身份组刚创建时所有权限都为 ignore，和被继承的服务器身份组一样，之后我们可以修改频道身份组，使频道身份组和服务器身份组拥有不一样的权限。
频道身份组的 parentRoleId 等于被继承的服务器身份组 serverRole.roleId。
该接口需要 manageRole 权限。

示例代码

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

const channelRole = await qchat.qchatRole.addChannelRole({
  "serverId": "1377422",
  "channelId": "1099153",
  "parentRoleId": serverRole.roleId
})

console.log(channelRole)
// {
//     "serverId": "1377422",
//     "roleId": "1115969",
//     "parentRoleId": "1246291",
//     "channelId": "1099153",
//     "name": "role1",
//     "auths": {
//         "manageChannel": "ignore",
//         "manageRole": "ignore",
//         "sendMsg": "ignore",
//         "recallMsg": "ignore",
//         "deleteMsg": "ignore",
//         "remindOther": "ignore",
//         "remindEveryone": "ignore",
//         "manageBlackWhiteList": "ignore"
//     },
//     "type": "custom",
//     "createTime": 1646191891861,
//     "updateTime": 1646191891861
// }

删除频道身份组

该接口需要 manageRole 权限。

完整 TS 定义参见 QChatRoleServiceInterface-removeChannelRole

/**
 * 删除某频道下的某身份组
 */
removeChannelRole(options: RemoveChannelRoleOptions): Promise<void>

示例代码

await qchat.qchatRole.removeChannelRole({
  "serverId": "1377422",
  "channelId": "1099153",
  "roleId": '1115969'
})

更新频道下某身份组

该接口需要 manageRole 权限。QChatRoleServiceInterface-updateChannelRole

/**
 * 修改频道下某身份组的权限
 */
updateChannelRole(options: UpdateChannelRoleOptions): Promise<QChatChannelRole>

其中 UpdateChannelRoleOptions 需要传入频道身份组的 serverId、channelId、roleId 和欲更新的 auths Map。

示例代码，某个身份组禁止 @所有人的权限：

const channelRole = await qchat.qchatRole.removeChannelRole({
  "serverId": "575440",
  "channelId": "558679",
  "roleId": "296919",
  "auths": {
    "remindEveryone": "deny"
  }
})

只有修改频道身份组中的权限信息，才会触发系统通知。具体的触发条件和接收条件请参考圈组系统通知。

查询某频道下的身份组信息列表

getChannelRoles 可以查询某个频道下的身份组列表，完整 TS 定义见 QChatRoleServiceInterface-getChannelRoles

/**
 * 查询某频道下的身份组信息列表
 */
getChannelRoles(options: GetChannelRolesOptions): Promise<QChatChannelRole[]>

示例代码:

const channelRoles = await qchat.qchatRole.getChannelRoles({
  "serverId": "1001190",
  "channelId": "935550",
  "limit": 10
})

console.log(channelRoles)

// [
//   {
//     "serverId": "1001190",
//     "roleId": "689754",
//     "parentRoleId": "706315",
//     "channelId": "935550",
//     "name": "@everyOne",
//     "icon": "",
//     "auths": {
//       "manageChannel": "ignore",
//       "manageRole": "ignore",
//       "sendMsg": "ignore",
//       "recallMsg": "ignore",
//       "deleteMsg": "ignore",
//       "remindOther": "ignore",
//       "remindEveryone": "ignore",
//       "manageBlackWhiteList": "ignore"
//     },
//     "type": "everyone",
//     "createTime": 1645090353549,
//     "updateTime": 1645090353549
//   },
//   {
//     "serverId": "1001190",
//     "roleId": "771147",
//     "parentRoleId": "788313",
//     "channelId": "935550",
//     "auths": {
//       "manageChannel": "ignore",
//       "manageRole": "ignore",
//       "sendMsg": "ignore",
//       "recallMsg": "ignore",
//       "deleteMsg": "ignore",
//       "remindOther": "ignore",
//       "remindEveryone": "ignore",
//       "manageBlackWhiteList": "ignore"
//     },
//     "type": "custom",
//     "createTime": 1645178916951,
//     "updateTime": 1645178916951
//   },
// ]

为某个人定制某频道的权限

除了可以通过频道身份组对所有身份组成员进行权限控制，也可以通过 addMemberRole 接口对某个成员的权限进行定制。接口参数详见 TS 文档 QChatRoleServiceInterface-addMemberRole

该接口需要 manageRole 权限。

/**
 * 为某个人定制某频道的权限
 */
addMemberRole(options: AddMemberRoleOptions): Promise<QChatMemberRole>

QChatMemberRole 的完整定义参见 TS 文档 QChatRoleServiceInterface-QChatMemberRole

/**
 * (某频道下给某人)定制权限
 */
export type QChatMemberRole = {
  id: string
  /**
   * 成员的 account id
   */
  accid: string
  channelId: string
  serverId: string
  /**
   * 权限
   */
  auths: QChatRoleAuth
  /**
   * 昵称
   */
  nick?: string
  /**
   * 头像
   */
  avatar?: string
  /**
   * 扩展
   */
  ext?: string
  /**
   * 成员类型
   */
  memberType: TMemberType
  /**
   * 加入时间
   */
  joinTime: number
  /**
   * 邀请者的 account ID
   */
  inviter: string
  createTime: number
  updateTime: number
}

定制权限默认也是 ignore 继承 channelRole 或者 serverRole 的权限的，示例代码：

const memberRole = await qchat.qchatRole.addMemberRole({
  "serverId": "{{YOUR_SERVER_ID}}",
  "channelId": "{{YOUR_CHANNEL_ID}}",
  "accid": "{{YOUR_ACCOUNT_ID}}"
})

console.log(memberRole)
// {
//     "serverId": "1001190",
//     "id": "444056",
//     "accid": "ctt1",
//     "channelId": "1099153",
//     "auths": {
//         "manageChannel": "ignore",
//         "manageRole": "ignore",
//         "sendMsg": "ignore",
//         "recallMsg": "ignore",
//         "deleteMsg": "ignore",
//         "remindOther": "ignore",
//         "remindEveryone": "ignore",
//         "manageBlackWhiteList": "ignore"
//     },
//     "createTime": 1646200705882,
//     "updateTime": 1646200705882,
//     "nick": "",
//     "memberType": "normal",
//     "joinTime": 1645431196871,
//     "inviter": "cjl"
// }

删除频道下某人的定制权限

该接口需要 manageRole 权限。

接口完整 TS 定义参见 QChatRoleServiceInterface-removeMemberRole

/**
 * 删除频道下某人的定制权限
 */
removeMemberRole(options: RemoveMemberRoleOptions): Promise<void>

其中 RemoveMemberRoleOptions 需要传入 serverId、channelId 和 accid。

示例代码

const memberRole = await qchat.qchatRole.addMemberRole({
  "serverId": "{{YOUR_SERVER_ID}}",
  "channelId": "{{YOUR_CHANNEL_ID}}",
  "accid": "{{YOUR_ACCOUNT_ID}}"
})

await qchat.qchatRole.removeMemberRole({
  "serverId": memberRole.serverId,
  "channelId": memberRole.channelId,
  "accid": memberRole.accid
})

修改某人的定制权限

该接口需要 manageRole 权限，参见 TS 文档 QChatRoleServiceInterface-updateMemberRole

/**
 * 修改某人的定制权限
 */
updateMemberRole(options: UpdateMemberRoleOptions): Promise<QChatMemberRole>

更新定制权限，使禁止此人 @所有人，示例代码：

let memberRole = await qchat.qchatRole.addMemberRole({
  "serverId": "{{YOUR_SERVER_ID}}",
  "channelId": "{{YOUR_CHANNEL_ID}}",
  "accid": "{{YOUR_ACCOUNT_ID}}"
})

memberRole = await qchat.qchatRole.updateMemberRole({
  "serverId": memberRole.serverId,
  "channelId": memberRole.channelId,
  "accid": memberRole.accid,
  "auths": {
    "remindEveryone": "deny"
  }
})

修改频道下某人的定制权限会触发系统通知。具体的触发条件和接收条件请参考圈组系统通知。

查询频道成员定制权限

可以通过以下接口分页某Channel下的成员定制权限列表。

/**
 * 查询某人的定制权限
 */
getMemberRoles(options: GetMemberRolesOptions): Promise<QChatMemberRole[]>

其中 GetMemberRolesOptions 需要传入 serverId、channelId、查询锚点时间戳和查询数量限制。

示例代码：

await qchat.qchatRole.addMemberRole({
  "serverId": "{{YOUR_SERVER_ID}}",
  "channelId": "{{YOUR_CHANNEL_ID}}",
  "accid": "{{YOUR_ACCOUNT_ID}}"
})

const memberRoles = await qchat.qchatRole.getMemberRoles({
  "serverId": "{{YOUR_SERVER_ID}}",
  "channelId": "{{YOUR_CHANNEL_ID}}",
  "timetag": 0,
})

console.log(memberRoles)
// [{
//     "serverId": "{{YOUR_SERVER_ID}}",
//     "id": "{{THE_ID}}",
//     "accid": "{{YOUR_ACCOUNT_ID}}",
//     "channelId": "{{YOUR_CHANNEL_ID}}",
//     "auths": {
//         "manageChannel": "ignore",
//         "manageRole": "ignore",
//         "sendMsg": "ignore",
//         "recallMsg": "ignore",
//         "deleteMsg": "ignore",
//         "remindOther": "ignore",
//         "remindEveryone": "ignore",
//         "manageBlackWhiteList": "ignore"
//     },
//     "createTime": 1646200705882,
//     "updateTime": 1646200705882,
//     "nick": "",
//     "memberType": "normal",
//     "joinTime": 1645431196871,
//     "inviter": "test"
// }]

将某些人加入某服务器身份组

接口

通过 addMembersToServerRole 新增服务器身份组成员后，继承自该服务器身份组的频道身份组成员也会作相应变化。完整 TS 定义参见 QChatRoleServiceInterface-addMembersToServerRole

注意

该接口需要 manageRole 权限。
欲想加入的 account 需要已经在此服务器 server 中，才能被允许加入某个服务器身份组。

/**
 * 将某些人加入某服务器身份组
 */
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}}"]
// }

将用户加入某服务器身份组会触发系统通知。具体的触发条件和接收条件请参考圈组系统通知。

将某些人移出某服务器身份组

可通过 removeMembersFromServerRole 删除服务器身份组成员，删除后继承自该服务器身份组的频道身份组成员也会作相应变化。完整 TS 定义参见 QChatRoleServiceInterface-removeMembersFromServerRole

该接口需要 manageRole 权限。

/**
 * 将某些人移除某服务器身份组
 */
removeMembersFromServerRole(options: RemoveMembersFromServerRoleOptions): Promise<RemoveMembersFromServerRoleResult>

其中 removeMembersFromServerRole 需要传入操作的 serverId、serverRole 的 roleId 和 accid 列表。

示例代码

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": []
// }

将用户移出某服务器身份组会触发系统通知。具体的触发条件和接收条件请参考圈组系统通知。

查询某服务器身份组的成员列表

getMembersFromServerRole 定义参见 TS QChatRoleServiceInterface-getMembersFromServerRole

仅自定义身份组（即 ERoleType 为 CUSTOM 的身份组）支持调该方法查询其成员列表。创建身份组时默认创建的 @everyone 身份组（即 ERoleType 为 EVERYONE 的身份组）不支持调用该方法查询成员列表。如调用该方法查询 @everyone 身份组的成员信息，将报错（错误码 403）。

/**
 * 查询某服务器下某身份组下的成员列表
 */
getMembersFromServerRole(options: GetMembersFromServerRoleOptions): Promise<QChatServerRoleMember[]>

其中 GetMembersFromServerRoleOptions 需要传入ServerId、ServerRole 的 roleId、查询锚点时间戳和查询数量限制。其中查询下一页时需要传入查询锚点 accid。

查询两页，示例代码

const page1 = await qchat.qchatRole.getMembersFromServerRole({
  "serverId": "{{YOUR_SERVER_ID}}",
  "roleId": "{{YOUR_CHANNEL_ID}}",
})

const lastMember = page1[page1.length - 1]

const page2 = await qchat.qchatRole.getMembersFromServerRole({
  "serverId": "{{YOUR_SERVER_ID}}",
  "roleId": "{{YOUR_CHANNEL_ID}}",
  "timetag": lastMember.createTime,
  "accid": lastMember.accid
})

通过 accid 查询服务器身份组列表

getServerRolesByAccid 可以通过 accid 查询该 accid 所属的服务器身份组 ServerRole，结果会分页。查询结果只会返回自定义 custom 身份组，不包含 everyone 的身份组。

完整 TS 定义参见 QChatRoleServiceInterface-getServerRolesByAccid

/**
 * 通过 accid(account ID) 查询 QChatServerRole 列表，结果会分页
 */
getServerRolesByAccid(options: GetServerRolesByAccidOptions): Promise<QChatServerRole[]>

示例代码：

await qchat.qchatRole.getServerRolesByAccid({
  "serverId": "{{YOUR_SERVER_ID}}",
  "accid": "{{YOUR_ACCOUNT_ID}}",
})

通过一批 accid 查询服务器身份组列表

getExistingServerRolesByAccids 可以通过一组 accid 查询这些 accid 所属的服务器身份组 ServerRole 列表。查询结果只会返回自定义 custom 身份组，不包含 everyone 身份组。

注意，结果不分页，且只能拿第一页的数据。

完整 TS 定义参见 QChatRoleServiceInterface-getExistingServerRolesByAccids

/**
 * 通过一批 accids(account ID) 查询 QChatServerRole 列表，结果不分页并且只拿第一页。
 */
getExistingServerRolesByAccids(options: GetExistingServerRolesByAccidsOptions): Promise<GetExistingServerRolesByAccidsResult>

示例代码

await qchat.qchatRole.getExistingServerRolesByAccids({
  "serverId": "{{YOUR_SERVER_ID}}",
  "accids": ["{{YOUR_ACCOUNT_ID}}"],
})

查询一批 accid 在某服务器身份组下的成员列表

getExistingAccidsInServerRole 支持通过 accid 查询某个 ServerRole 下的身份组成员信息。

完整的 TS 定义参见 QChatRoleServiceInterface-getExistingAccidsInServerRole

/**
 * 查询一批 accids 是否在某个服务器身份组（ServerRole）。
 * 
 * 返回在此服务器身份组下的 accid（account id） 列表，查询结果不分页
 */
getExistingAccidsInServerRole(options: GetExistingAccidsInServerRoleOptions): Promise<string[]>

示例代码

const accids = await qchat.qchatRole.getExistingAccidsInServerRole({
  "serverId": "{{YOUR_SERVER_ID}}",
  "roleId": "{{YOUR_ROLE_ID}}",
  "accids": ["{{YOUR_ACCOUNT_ID}}"],
})

查询一批服务器身份组的频道身份组列表

getExistingChannelRolesByServerRoleIds 支持通过传入一组 serverRole 的 roleId 查询这些服务器身份组被添加到频道后的 channelRole 的 roleId 列表。只会返回已经配置在该频道的 roleId 列表。

完整的 TS 定义参见 QChatRoleServiceInterface-getExistingChannelRolesByServerRoleIds

/**
 * 通过一批服务器身份组（serverRoleIds）来查询频道的身份组信息（QChatChannelRole）。返回某服务器身份加入过频道，该频道的身份组信息。结果不分页
 */
getExistingChannelRolesByServerRoleIds(options: GetExistingChannelRolesByServerRoleIdsOptions): Promise<QChatChannelRole[]>

需要传入需要查询的 serverId、channelId 和 roleIds。

示例代码

const channelRoles = await qchat.qchatRole.getExistingChannelRolesByServerRoleIds({
  "serverId": "{{YOUR_SERVER_ID}}",
  "channelId": "{{YOUR_CHANNEL_ID}}",
  "accids": ["{{YOUR_ACCOUNT_ID}}"],
})

查询一批用户在该频道下的成员定制权限的 accid 列表

getExistingAccidsOfMemberRoles 支持通过传入 accid 列表查询在频道中的成员定制权限的 accid 列表。查询只会返回已经存在的成员定制权限 accid 列表。

完整的 TS 定义参见 QChatRoleServiceInterface-getExistingAccidsOfMemberRoles

/**
 * 通过一批 accids(account ID) 查询是否有定制权限（QChatMemberRole）。
 * 
 * 返回有定制权限的 accid（account id） 列表，查询结果不分页
 */
getExistingAccidsOfMemberRoles(options: GetExistingAccidsOfMemberRolesOptions): Promise<string[]>

需要传入需要查询的 serverId、channelId 和 accid 列表。

示例代码:

const accids = await qchat.qchatRole.getExistingAccidsOfMemberRoles({
  "serverId": "{{YOUR_SERVER_ID}}",
  "channelId": "{{YOUR_CHANNEL_ID}}",
  "accids": ["{{YOUR_ACCOUNT_ID}}"],
})

查询查询自己是否拥有某个权限

checkPermission 支持通过传入服务器ID，频道ID和需要查询的权限查询自己有无该权限，返回true/false。

/**
  * 查询自己是否拥有某个权限
  */
checkPermission(options: CheckPermissionOptions): Promise<boolean>

需要传入需要查询的 serverId、channelId 和 auth。

示例代码:

const accids = await qchat.qchatRole.checkPermission({
  "serverId": "{{YOUR_SERVER_ID}}",
  "channelId": "{{YOUR_CHANNEL_ID}}",
  "auth": "{{YOUR_AUTH}}",
})

查询自己是否拥有某些权限

调用checkPermissions方法查询自己是否拥有某些权限（单次最多可查 10 个权限）。

原型

checkPermissions(options: CheckPermissionsOptions): Promise<checkPermissionsResult>

示例代码

// 初始化SDK
const qchat = new QChatSDK({
  ... 
})
// 等待登录完成
await qchat.login()
// 消息搜索
qchat.qchatRole.checkPermissions({
  "serverId": "{{YOUR_SERVER_ID}}",
  "channelId": "{{YOUR_CHANNEL_ID}}",
  "auths": "{{YOUR_AUTH}}",
})

此文档是否对你有帮助？

有帮助

我要吐槽

文档反馈

在线咨询

创建服务器身份组
接口
示例代码
安全通相关
移除服务器身份组
接口
示例代码
更新服务器身份组信息
接口
示例代码
批量更新服务器身份组优先级
接口
查询某服务器下身份组列表
新增频道身份组
接口
删除频道身份组
更新频道下某身份组
查询某频道下的身份组信息列表
为某个人定制某频道的权限
删除频道下某人的定制权限
修改某人的定制权限
查询频道成员定制权限
将某些人加入某服务器身份组
接口
将某些人移出某服务器身份组
查询某服务器身份组的成员列表
通过 accid 查询服务器身份组列表
通过一批 accid 查询服务器身份组列表
查询一批 accid 在某服务器身份组下的成员列表
查询一批服务器身份组的频道身份组列表
查询一批用户在该频道下的成员定制权限的 accid 列表
查询查询自己是否拥有某个权限
查询自己是否拥有某些权限
原型
示例代码