身份组自定义权限项

IM 即时通讯

API 参考

群组

高级群

聊天室

圈组

更新时间： 2023/02/10 16:04:00

云信本身已提供较为完善的原子化权限，可供开发者调用实现基础的权限管控诉求。但不同行业的产品或同一产品的不同场景，对于用户权限管控的业务需求各有差异。因此云信圈组提供了创建自定义权限项的接口，帮助开发者快速实现符合自身需求的权限管控能力。

使用场景

自定义权限适用于如下业务场景：
- 拓展圈组现有权限
  
  以消息相关权限为例。目前身份组虽然提供了发送消息的基础权限，但仍无法满足关于消息类型发送限制的能力。通过自定义权限，应用层可自定义如文字、图片、地理位置、语音消息、表情等消息体的发送权限。
- 增加圈组权限类型
  
  针对类贴吧微博等非即时通讯频道，通过自定义权限，应用层可设置发帖、评论等行为权限，保持权限的一致性。
- 减少开发者的维护成本
  
  云信提供新建、查询、计算等一系列的权限管理能力，应用层不需要独立维护权限，一个接口解决所有权限管控问题。
典型使用案例：
- 通过自定义权限接口新建发送文字消息的权限、发送图片消息权限等不同消息类型的发送权限。然后在不同身份组中开启相应的权限，实现根据不同的身份组给予不同用户发送不同消息类型的权限。例如身份组A 的成员只能发送文字消息，身份组B 的成员只能发送文本和图片消息，身份组B 的成员可发送文字、图片、语音、自定义表情包等所有消息类型。
- 通过自定义权限接口创建“禁言成员”权限，在应用上层自行实现相应逻辑，使拥有该权限的用户可对频道内其他用户设置禁言时间与禁言效果。

前提条件

已登录圈组。

实现流程

客户端通过增加自定义权限项进行用户操作管控的具体实现流程，请参见：

API 参考

创建自定义权限

创建身份组自定义权限。

URL

POST  http://api.netease.im/nimserver/qchat/createCustomAuth.action  HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8

请求参数

POST 请求中 Headers 的设置请参考API调用方式。
POST 请求中 Body 的设置如下：

参数	类型	是否必填	说明
authBit	Integer	是	自定义权限项，必须大于或等于 10000，示例：10005 authBit值不能重复使用。换而言之，相同的 authBit 值只能给一个自定义权限项使用（注：删除自定义权限项之后，其 authBit 值仍不能二次使用）。
authDesc	String	否	自定义权限项的描述
authType	Integer	是	自定义权限项的类型：0-服务器和频道都有的权限项，1-仅服务器有的权限项
defaultRight	Integer	是	自定义权限的默认状态：-1-关闭（身份组成员无该权限），1-开启（身份组成员有该权限）

示例

cURL请求示例

curl -X POST -H "AppKey: go9dnk49**0803mgq3" -H "Nonce: 4tg**23t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'authBit=10000&authDesc=权限描述&authType=0&defaultRight=0' 'http://api.netease.im/nimserver/qchat/createCustomAuth.action'

请求成功返回示例

"Content-Type": "application/json; charset=utf-8"
{
    "code": 200,
}

请求失败返回示例

"Content-Type": "application/json; charset=utf-8"
{
"code": 414,
"desc": "invalid authBit"  //权限值不合法
}

状态码

该接口在 HTTPS Body 中返回请求的状态码，以下仅列出与接口业务相关的状态码。全量状态码说明，请参见状态码。

状态码	说明	处理建议
414	权限值不合法	请确保 authBit 为大于或等于 10000 的整形数据
417	权限值被占用	替换 authBit 的值，重新调用 API authBit的值，只能被使用一次。即使将某个自定义权限删除，其用过的 authBit 值也不能被其他自定义权限使用。
419	权限数量超出上限	单个应用最多可创建 30 个自定义权限

删除自定义权限项

删除某个自定义权限项。

URL

POST  http://api.netease.im/nimserver/qchat/deleteCustomAuth.action  HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8

请求参数

POST 请求中 Headers 的设置请参考API调用方式。
POST 请求中 Body 的设置如下：

参数	类型	是否必填	说明
authBit	Integer	是	自定义权限项

示例

cURL请求示例

curl -X POST -H "AppKey: go9dnk4**1kglw0803mgq3" -H "Nonce: 4tggg**23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'authBit:10000' 'http://api.netease.im/nimserver/qchat/deleteCustomAuth.action'

请求成功返回示例

"Content-Type": "application/json; charset=utf-8"
{
    "code": 200
}

该接口在 HTTPS Body 中返回请求的状态码，以下仅列出与接口业务相关的状态码。全量状态码说明，请参见状态码。

状态码	说明	处理建议
414	参数错误	检查传入的 authBit 是否合法或者不存在

查询所有自定义权限

查询当前应用所有现存的身份组自定义权限项（本接口无请求参数）。

URL

POST  http://api.netease.im/nimserver/qchat/listAllCustomAuth.action  HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8

示例

cURL请求示例

curl -X POST -H "AppKey: go9dnk**0803mgq3" -H "Nonce: 4tgggerg**t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded"  'http://api.netease.im/nimserver/qchat/listAllCustomAuth.action'

请求成功返回示例

"Content-Type": "application/json; charset=utf-8"
{
    "code": 200,
    "customAuthList": [
        {
            "authBit": 10000,
            "authType": 0,
            "authDesc": "",
            "defaultRight": "1",
            "createTime": 0,
            "updateTime": 0
        }
    ]
}

状态码

该接口在 HTTPS Body 中返回请求的状态码，状态码说明请参见状态码。

查询自定义权限项列表

通过传入自定义权限项的 authBit 值的集合（JSON Array），查询这些权限项的信息，包括自定义权限项类型、自定义权限项描述、更新时间等。

URL

POST  http://api.netease.im/nimserver/qchat/listCustomAuthByAuthBits.action  HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8

请求参数

参数	类型	是否必填	说明
authBits	String	是	权限集合（JSON Array），示例：authBits=[10000, 10001, 10002, 10003]

返回参数

参数	类型	说明
authBit	Integer	自定义权限项
authType	Integer	自定义权限项的类型：0-服务器和频道都有的权限，1-仅服务器有的权限
authDesc	String	自定义权限项的描述
defaultRight	Integer	自定义权限项的默认状态：-1-关闭（身份组成员无该权限），1-开启（身份组成员有该权限）
updateTIme	Long	自定义权限项的状态的更新时间

示例

cURL请求示例

curl -X POST -H "AppKey: go9dnk4**03mgq3" -H "Nonce: 4tggg**3t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'authBit=[10000, 10001, 10002, 10003]' 'http://api.netease.im/nimserver/qchat/listCustomAuthByAuthBits.action'

请求成功返回示例

"Content-Type": "application/json; charset=utf-8"
{
    "code": 200,
    "customAuthList": [
        {
            "authBit": 10001,
            "authType": 0,
            "authDesc": "自定义权限项的描述",
            "createTime": 0,
            "defaultRight": "1",
            "updateTime": 0
        }
    ]
}

状态码

该接口在 HTTPS Body 中返回请求的状态码，以下仅列出与接口业务相关的状态码。全量状态码说明，请参见状态码。

状态码	说明	处理建议
414	参数错误	检查传入的 authBits 是否合法

此文档是否对你有帮助？

有帮助

我要吐槽

文档反馈

在线咨询

使用场景
前提条件
实现流程
API 参考
创建自定义权限
URL
请求参数
示例
状态码
删除自定义权限项
URL
请求参数
示例
查询所有自定义权限
URL
示例
状态码
查询自定义权限项列表
URL
请求参数
返回参数
示例
状态码