服务器身份组
更新时间: 2024/07/17 17:57:34
身份组是圈组功能的权限管理系统。您可通过身份组,实现对服务器成员和频道成员的精细化权限控制。
服务器身份组负责在服务器维度对用户进行权限控制。服务器身份组包括服务器下的@everyone 身份组和自定义身份组。创建服务器时,@everyone 身份组默认自动创建。而服务器自定义身份组则需要用户手动创建。此外,拥有相应权限(具体见下文)的用户还可调整服务器身份组的优先级。
身份组相关的功能概述,请参见 身份组概述。
本文包含如下 API 的说明:
使用限制
单个服务器内可创建的服务器身份组数量上限,默认为 20 个。
可在云信控制台配置单个服务器内的身份组数量上限。(在云信控制台选择应用,进入IM 即时通讯 > 功能配置 > 圈组 > 子功能配置 > 单server可创建的身份组即可配置。
创建服务器身份组
调用如下 API 可创建服务器自定义身份组。自定义身份组创建后,其权限项的状态(开启或关闭)默认继承已有的身份组的权限之和,具体计算规则为:取有(即“开启”)不取无(即“关闭”)、多组取并集。如需调整权限项的状态,需要拥有管理角色权限的用户手动修改(具体见下文的修改服务器身份组)。
除服务器创建者以外的用户调用本 API 需要拥有管理角色权限。
URL
httpPOST https://api.netease.im/nimserver/qchat/createServerIdentify.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
请求参数
-
POST 请求中 Headers 的设置请参考 API 调用方式。
-
POST 请求中 Body 的设置如下:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
accid | String | 是 | 操作者的 IM 账号 |
serverId | Long | 是 | 服务器 ID |
type | int | 是 | 类型:2为自定义身份组,目前只能设置为2 |
name | String | 是 | 身份组名称 |
icon | String | 否 | 身份组图标url |
ext | String | 否 | 自定义扩展,最大长度1024 |
priority | String | 否 | 优先级数值,正数。数值越小,优先级越大,最小为1,@everyone 身份组为 0,但不参与比较 |
bid | String | 否 | 安全通的自定义反垃圾(即内容审核)业务的 ID,可转换 JSON 格式,如: {"textbid":"","picbid":""} |
示例
cURL请求示例
curlcurl -X POST -H "AppKey: go9dn**03mgq3" -H "Nonce: 4tg**23t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'serverId=1513535&accid="accid"&type=2&name="新身份组1"&icon="iconurl"&ext="ext"&priority=12' 'http://api.netease.im/nimserver/qchat/createServerIdentify.action'
返回示例
请求成功的返回示例如下:
http 响应:json
json"Content-Type": "application/json; charset=utf-8"
{
"code": 200,
"identify": {
"ext": "ext",//扩展字段
"membercount": 1,//身份组的成员数
"createtime": 1,//创建时间
"roleId": 1,//身份组的唯一标识
"auths": "{\"1\":-1, \"2\":1}",//身份组的权限,key为权限的枚举值,value为1允许,-1拒绝,服务器身份组只有允许和拒绝
"name": "name",//身份组名称
"icon": "icon",//身份组图标url
"priority": 1,//身份组的优先级,优先级数字越小优先级越高,1为最高,everyone为特殊身份组为0不参与其他身份组的比较
"type": 1,//身份组的类型1:@everyone身份组,2:自定义身份组
"updatetime": 1//更新时间
}
}
状态码
该 API 在 HTTPS Body 中返回请求的状态码,状态码详情请参见 状态码。
修改服务器身份组
调用本 API 可修改自定义服务器身份组信息,包括身份组权限项的状态、身份组名称、身份组图标等
- 除服务器创建者以外的用户调用本 API 需要拥有管理角色权限。
- 仅自定义身份组(即
type
为2
的身份组)支持调用该接口更新身份组信息。创建服务器时默认创建的 @everyone 身份组 (即type
为1
的身份组)不支持调用该接口更新其信息。@everyone 身份组仅支持修改其权限。如果调用该接口更新 @everyone 身份组的信息(身份组的名称,图标,自定义扩展,优先级), 将报错(错误码 403)。
URL
httpPOST https://api.netease.im/nimserver/qchat/updateServerIdentify.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
请求参数
-
POST 请求中 Headers 的设置请参考 API 调用方式。
-
POST 请求中 Body 的设置如下:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
accid | String | 是 | 操作者的 IM 账号 |
serverId | String | 是 | 服务器 ID |
roleId | String | 是 | 服务器身份组 ID |
name | String | 否 | 身份组名称 |
icon | String | 否 | 身份组图标url |
ext | String | 否 | 自定义扩展,最大长度1024 |
auths | String | 否 | 用于修改权限的 JSON 字段, 其格式为 {resource1:type1,resource2:type2,resource3:type3}。
注:单次最多可批量更新当前身份组的所有权限。 |
bid | String | 否 | 安全通的自定义反垃圾(即内容审核)业务的 ID,可转换 JSON 格式,如: {"textbid":"","picbid":""} |
返回参数
参数 |
说明 |
---|---|
code | 状态码 |
identify | 修改后的身份组,具体字段信息见下表 |
identify 的字段 |
说明 |
---|---|
ext | 身份组的扩展字段 |
membercount | 身份组的成员数量 |
createtime | 身份组的创建时间 |
roleId | 身份组 ID |
auths | 身份组的权限配置列表,示例:"{"1":-1, "2":1}",其中 key为权限项的枚举值,value 为该权限项的配置状态:
|
name | 身份组名称 |
icon | 身份组的图标 URL |
priority | 身份组的优先级,优先级数字越小优先级越高,1 为最高。默认的 @everyone身份组 为特殊身份组,其优先级为 0。 当用户拥有管理身份组的权限后,可对等级低于自身最高优先级身份组的其他身份组进行操作(如修改权限配置),也可创建一个新的自定义身份组,并对其进行优先级排序 |
type | 身份组类型,1:@everyone身份组,2:自定义身份组 |
updatetime | 身份组的更新时间 |
示例
cURL请求示例
curlcurl -X POST -H "AppKey: go9dnk49**kglw0803mgq3" -H "Nonce: 4tggg**t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'serverId=1513535&accid="accid"&roleId=2&name="新身份组1"&icon="iconurl"&ext="ext"&auths="{\"1\":1}"' 'http://imtest.netease.im/nimserver/qchat/updateServerIdentify.action'
返回示例
请求成功的返回示例如下:
json"Content-Type": "application/json; charset=utf-8"
{
"code": 200,
"identify": {
"ext": "ext",
"membercount": 1,
"createtime": 1,
"roleId": 1,
"auths": "{\"1\":-1, \"2\":1}",
"name": "name",
"icon": "icon",
"priority": 1,
"type": 1,
"updatetime": 1
}
}
状态码
该 API 在 HTTPS Body 中返回请求的状态码,状态码详情请参见 状态码。
删除服务器身份组
如果需要删除某个服务器身份组,可通过本 API 进行删除。
- 服务器创建者以外用户调用该方法必须先拥有管理角色权限,且必须是相应服务器的成员。
- @everyone 身份组默认不可删除。
- 用户无法删除优先级高于自己已有身份组的最高优先级的身份组。
URL
httpPOST https://api.netease.im/nimserver/qchat/removeServerIdentify.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
请求参数
-
POST 请求中 Headers 的设置请参考 API 调用方式。
-
POST 请求中 Body 的设置如下:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
accid | String | 是 | 操作者的 IM 账号 |
serverId | String | 是 | 服务器 ID |
roleId | int | 是 | 身份组 ID |
示例
curl请求示例
curlcurl -X POST -H "AppKey: go9dnk4**803mgq3" -H "Nonce: 4tg**323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'serverId=1513535&accid="accid"&roleId=2' 'http://imtest.netease.im/nimserver/qchat/removeServerIdentify.action'
返回示例
http 响应:json
json"Content-Type": "application/json; charset=utf-8"
{
"code":200
}
状态码
该 API 在 HTTPS Body 中返回请求的状态码,状态码详情请参见 状态码。
批量更新服务器身份组优先级
IM 服务端提供 API 支持指定某个服务器批量更新该服务器的身份组优先级。身份组有优先级高低之分,拥有管理角色权限的高优先级身份组成员,才可修改较低优先级身份组的权限配置。
功能介绍
当用户拥有管理角色权限后,可对优先级低于自身最高优先级身份组的其他身份组进行操作(如修改权限配置),也可创建一个新的自定义身份组,并对其进行优先级排序。新的自定义身份组被创建后,其优先级默认为用户所属自定义身份组中最低。
注意事项
- 调用该方法必须拥有管理角色权限。且当拥有该权限的用户想去变更某个低优先级身份组的某项权限时,首先该用户自身必须有该权限项,即该用户所在的所有身份组中,至少有一个身份组的该权限项的状态为开启。
- 自定义身份优先级永远高于@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)。
URL
POST http://api.netease.im/nimserver/qchat/batchUpdateServerIdentifyPriority.action HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8
请求参数
-
POST 请求中 Headers 的设置请参考 API 调用方式。
-
POST 请求中 Body 的设置如下:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
accid | String | 是 | 操作者的云信 IM 账号 |
roleIdPriorities | String | 是 | 服务器身份组 ID 和优先级的列表,JSON 数组(roleId|priority),示例"["12345|2", "45678|1"]" 最佳实践:建议把 priority 为 1 的身份组空出来,不要用在业务上。可以把这个 priority 为 1 的身份组专门留给最高管理员使用,方便后面调整其他身份组的优先级
|
serverId | long | 是 | 服务器 ID |
返回参数
参数 |
类型 |
说明 |
---|---|---|
code | int | 状态码 |
identifies | String | 身份组信息 |
其中 identifies 包含的参数说明如下:
参数 |
类型 |
说明 |
---|---|---|
ext | String | 身份组自定义扩展 |
membercount | Number | 身份组成员数量 |
createtime | Number | 创建时间 |
roleId | long | 身份组 ID |
auths | String | 身份组权限 |
name | String | 身份组名称 |
icon | String | 身份组图标的 URL |
priority | String | 身份组的优先级,正数。数字越小,优先级越大,最小为1,everyone 身份组为 0,但不参与比较 |
type | int | 身份组类型 |
updatetime | String | 更新时间 |
ismember | int | 当前用户是否在该身份组中, 0-否,1-是 |
示例
cURL 请求示例
curl -X POST -H "AppKey: go9dnk49bkd9jd9*****kglw0803mgq3" -H "Nonce: 4tg**ow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962c*****7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'serverId=1513535&accid="accid"&serverIdAccids=%5B%2254321|11%22%2C%2254322|22%22%5D' 'http://api.netease.im/nimserver/qchat/batchUpdateServerIdentifyPriority.action'
返回示例
"Content-Type": "application/json; charset=utf-8"
{
"code":200,
"identifies":[{
"ext": "ext", //身份组自定义扩展
"membercount": 1, //身份组成员数量
"createtime": 1, //创建时间
"roleId": 1, //身份组ID
"auths": "{\"1\":-1, \"2\":1}", //身份组权限
"name": "name", //身份组名称
"icon": "icon", //身份组图标
"priority": 1, //身份组优先级
"type": 1, //身份组类型
"updatetime": 1, //更新时间
"ismember": 0 //自己是否在该身份组中,0否1是
}]
}
状态码
该接口在 HTTPS Body 中返回请求的状态码,状态码列表请参考 状态码。
分页查询服务器身份组
分页查询服务器身份组信息,包括权限项状态、创建时间、更新时间等。
URL
httpPOST https://api.netease.im/nimserver/qchat/getServerIdentifyPages.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
请求参数
-
POST 请求中 Headers 的设置请参考 API 调用方式。
-
POST 请求中 Body 的设置如下:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
accid | String | 是 | 操作者的云信 IM 账号(accid) |
serverId | String | 是 | 服务器 ID |
priority | Long | 否 | 按照**优先级的数值**从小到大排序。查询结果起始的优先级。如果不传或者传 0 默认为首页,首页会返回@everyone 身份组放在返回结果集的首条 |
limit | Integer | 否 | 每页限制查询多少条,不传时默认为200,最大限制为200 |
channelId | String | 否 | 可选,以channelId的名义查询。若设置该字段,则只需要有该channel的管理权限即可,否则需要有server的管理权限 |
categoryId | String | 否 | 可选,以categoryId的名义查询。若设置该字段,则只需要有该channel category的管理权限即可,否则需要有server的管理权限 |
示例
curl请求示例
curlcurl -X POST -H "AppKey: go9dn**1kglw0803mgq3" -H "Nonce: 4tgggerg**t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'serverId=1513535&accid="accid"&priority=1&limit=10' 'http://api.netease.im/nimserver/qchat/getServerIdentifyPages.action'
返回示例
http 响应:json
json"Content-Type": "application/json; charset=utf-8"
{
"code":200,
"serverIdentifies":[{
"ext": "ext",//扩展字段
"membercount": 1,//身份组的成员数
"createtime": 1,//创建时间
"roleId": 1,//身份组的唯一标识
"auths": "{\"1\":-1, \"2\":1}",//身份组的权限。key为权限项的枚举值,value为 1 时表示“开启”,为 -1 表示“关闭”,服务器身份组的权限状态只有“开启”和“关闭”
"name": "name",//身份组名称
"icon": "icon",//身份组图标url
"priority": 1,//身份组的优先级,优先级数字越小优先级越高,1 为最高。@everyone为默认身份组,优先级的值为0,不参与其他身份组的比较
"type": 1,//身份组的类型1:@everyone身份组,2:自定义身份组
"updatetime": 1,//更新时间
"ismember": 0//操作者是否属于服务器成员,0不属于,1属于
}]
}
@everyone 身份组不返回 membercount 和 isMember。
状态码
该 API 在 HTTPS Body 中返回请求的状态码,状态码详情请参见 状态码。