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

更新时间： 2024/03/14 17:08:36

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

@everyone 身份组的权限配置，只有服务器创建者可修改。@everyone 身份组的其他信息（身份组的名称、图标、自定义扩展和优先级）不支持修改。
Web SDK最大可以设置的整型是9007199254740991。如果超过，接收方是Web SDK时会溢出。

服务器身份组定义

服务器身份组由NIMQChatServerRole类定义。该类的参数说明如下：

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

参数	类型	说明
`roleId`	unsigned long long	身份组 ID
`serverId`	unsigned long long	身份组所属服务器的 ID
`name`	NSString	身份组名称
`icon`	NSString	身份组图标的 URL
`ext`	NSString	身份组的扩展字段
`auths`	NSArray<NIMQChatPermissionStatusInfo*>	`NIMQChatPermissionStatusInfo`类表示身份组权限信息，包含`type`和`status`两个参数: `type`：权限类型，在`NIMQChatPermissionType`内定义，具体权限说明请参见身份组权限类型 `status`：`NIMQChatPermissionStatus`内定义了权限的配置状态，包括 `NIMQChatPermissionStatusDeny`:无权限 `NIMQChatPermissionStatusExtend`：继承 `NIMQChatPermissionStatusAllow`：有权限
`type`	`NIMQChatRoleType`	返回身份组的类型，`NIMQChatRoleTypeEveryOne` 表示 @everyone 身份组，`NIMQChatRoleTypeCustom` 表示自定义身份组
`memberCount`	NSInteger	身份组的成员数量，@ everyone 身份组的成员数量数量默认为-1
`priority`	NSNumber	身份组优先级（具体见下文的批量更新服务器身份组优先级），用于判定身份组成员是否能修改其他身份组的权限配置。自定义身份组优先级取值大于0，数字越小优先级越高。高优先级身份组中拥有管理角色权限的用户，可修改低优先级身份组的权限，但无法修改更高优先级身份组的权限。 @everyone 身份组优先级取值为 0 且不能更改，默认低于自定义身份组优先级
`createTime`	NSTimeInterval	身份组的创建时间
`updateTime`	NSTimeInterval	身份组配置的更新时间

前提条件

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

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

使用限制

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

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

实现流程

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

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

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

调用createServerRole:completion:方法创建自定义身份组。调用成功后，可以从返回的NIMQChatGetServerRolesResult中获得新建的服务器身份组NIMQChatServerRole。

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

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

API 原型

- (void)createServerRole:(NIMQChatCreateServerRoleParam *)param
                completion:(nullable NIMQChatCreateServerRoleHandler)completion;

示例代码

id<NIMQChatRoleManager> qchatRoleManager = [[NIMSDK sharedSDK] qchatRoleManager];
NIMQChatCreateServerRoleParam *param = [[NIMQChatCreateServerRoleParam alloc] init];
param.serverId = 123456;
param.type = NIMQChatRoleTypeCustom;
param.name = @"云信服务器自定义身份组";
//反垃圾业务id
param.antispamBusinessId = @"{\"picbid\": \"804265342b7425324f53425c343454\", \"txtbid\": \"804265342b7425324f53425c343454\"}";
[qchatRoleManager createServerRole:param
            completion:^(NSError *__nullable error, NIMQChatServerRole *__nullable result) {
    // your code
}];

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

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

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

API 原型

- (void)updateServerRole:(NIMQChatUpdateServerRoleParam *)param
                completion:(nullable NIMQChatUpdateServerRoleHandler)completion;

示例代码

id<NIMQChatRoleManager> qchatRoleManager = [[NIMSDK sharedSDK] qchatRoleManager];
NIMQChatUpdateServerRoleParam *param = [[NIMQChatUpdateServerRoleParam alloc] init];
param.serverId = 123456; // 身份组所属服务器的 ID
param.roleId = 111; //身份组 ID
param.name = @"修改后的服务器身份组名称";
// 修改优先级需要注意已经有的优先级
param.priority = @(10);
//反垃圾业务id
param.antispamBusinessId = @"{\"picbid\": \"804265342b7425324f53425c343454\", \"txtbid\": \"804265342b7425324f53425c343454\"}";
[qchatRoleManager updateServerRole:param
            completion:^(NSError *__nullable error, NIMQChatServerRole *__nullable result) {
    // your code
}];

步骤3：添加身份组成员

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

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

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

调用该方法必须先拥有管理角色权限（NIMQChatPermissionTypeManageRole）。如果没有该权限，调用该方法将返回 403 错误码。

API 原型

- (void)addServerRoleMembers:(NIMQChatAddServerRoleMembersParam *)param
                        completion:(nullable NIMQChatAddServerRoleMembersHandler)completion;

示例代码

id<NIMQChatRoleManager> qchatRoleManager = [[NIMSDK sharedSDK] qchatRoleManager];
NIMQChatAddServerRoleMembersParam *param = [[NIMQChatAddServerRoleMembersParam alloc] init];
param.serverId = 123456; // 服务器ID
param.roleId = 111;  //身份组ID
param.accountArray = @[@"yunxin1", @"yunxin2", @"yunxin3"]; //待添加用户的 IM 账号列表
[qchatRoleManager addServerRoleMembers:param
                completion:^(NSError *__nullable error, NIMQChatAddServerRoleMembersResult *__nullable result) {
    // your code
}];

其他相关 SDK API

移除身份组成员

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

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

调用该方法必须先拥有管理角色权限（NIMQChatPermissionTypeManageRole）。如果没有该权限，调用该方法将返回 403 错误码。

API 原型

- (void)removeServerRoleMember:(NIMQChatRemoveServerRoleMemberParam *)param
                        completion:(nullable NIMQChatRemoveServerRoleMembersHandler)completion;

示例代码

id<NIMQChatRoleManager> qchatRoleManager = [[NIMSDK sharedSDK] qchatRoleManager];
NIMQChatRemoveServerRoleMemberParam *param = [[NIMQChatRemoveServerRoleMemberParam alloc] init];
param.serverId = 123456; // 服务器ID
param.roleId = 111;  //身份组ID
param.accountArray = @[@"yunxin1", @"yunxin2", @"yunxin3"];
[qchatRoleManager removeServerRoleMember:param
                    completion:^(NSError *__nullable error, NIMQChatRemoveServerRoleMembersResult *__nullable result) {
    // your code
}];

删除服务器身份组

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

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

API 原型

- (void)deleteServerRole:(NIMQChatDeleteServerRoleParam *)param
                completion:(nullable NIMQChatDeleteServerRoleHandler)completion;

示例代码

id<NIMQChatRoleManager> qchatRoleManager = [[NIMSDK sharedSDK] qchatRoleManager];
    NIMQChatDeleteServerRoleParam *param = [[NIMQChatDeleteServerRoleParam alloc] init];
    param.serverId = 123456; //身份组所属的服务器 ID
    param.roleId = 111; // 待删除的身份组的 ID
    [qchatRoleManager deleteServerRole:param
                completion:^(NSError *__nullable error) {
        // your code
    }];

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

身份组有优先级高低之分，拥有管理角色权限（NIMQChatPermissionTypeManageRole）的高优先级身份组成员，才可修改低优先级身份组的权限配置。

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

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

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

调用该方法必须拥有NIMQChatPermissionTypeManageRole权限。如果没有该权限，调用该方法将返回 403 错误码。且当拥有NIMQChatPermissionTypeManageRole权限的用户想去变更某个低优先级身份组的某项权限时，首先其自身必须有该权限，即该用户所在的所有身份组中，至少有一个身份组为其赋予过该权限。
自定义身份优先级永远高于@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 原型

- (void)updateServerRolePriorities:(NIMQChatupdateServerRolePrioritiesParam *)param
                    completion:(nullable NIMQChatupdateServerRolePrioritiesHandler)completion;

示例代码

id<NIMQChatRoleManager> qchatRoleManager = [[NIMSDK sharedSDK] qchatRoleManager];
NIMQChatupdateServerRolePrioritiesParam *param = [[NIMQChatupdateServerRolePrioritiesParam alloc] init];
param.serverId = 123456;
NIMQChatUpdateServerRolePriorityItem *updateItem = [[NIMQChatUpdateServerRolePriorityItem alloc] init];
updateItem.serverId = 123456;
updateItem.roleId = 111;
// 更新优先级需要关注已有优先级
updateItem.priority = @(2);
param.updateItems = @[updateItem];
[qchatRoleManager updateServerRolePriorities:param
                        completion:^(NSError *__nullable error, NIMQChatupdateServerRolePrioritiesResult *__nullable result) {
    // your code
}];

查询服务器身份组

API	说明	相关文档
`getServerRoles:completion:`	分页查询服务器身份组列表	分页查询服务器身份组列表
`getServerRoleMembers: completion:`	分页查询某个服务器身份组的成员列表	查询服务器身份组的成员列表
`getServerRolesByAccid:completion:`	根据某用户的accid分页查询该用户所属的服务器身份组列表	查询用户的服务器身份组列表
+ `getExistingServerRolesByAccids:completion:`	通过一批用户的accid查询这些用户所属的自定义服务器身份组列表	批量查询某些用户的服务器身份组列表
`getExistingAccidsInServerRole`	根据一批 accids 查询这些 accid 对应的用户是否为某个服务器身份组的成员，如果是，则返回成员信息	批量查询某些用户是否为指定服务器身份组成员

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

服务器身份组定义

前提条件

使用限制

实现流程

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

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

步骤3：添加身份组成员

其他相关 SDK API

移除身份组成员

删除服务器身份组

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

查询服务器身份组

相关参考

相关系统通知