开发者中心

# 封禁用户权限

在服务端创建封禁用户权限规则。 可封禁的用户权限（privileges）包括：

  • join_channel: 加入频道。
  • publish_audio: 发送音频流。
  • publish_video: 发送视频流。

封禁用户权限的规则通过 cname、uid 和 ip 三个字段实现过滤，规则如下：

  • 当 privileges 设为 join_channel 时:
    • 如果填写 ip，不填写 cname 和 uid，则该 ip 无法登录 app 中的任何频道。
    • 如果填写 cname，不填写 uid 和 ip，则任何人都无法登录 app 中该 cname 对应的频道。
    • 如果填写 uid，不填写 cname 和 ip，则该 uid无法登录 app 中的任何频道。
    • 如果填写 cname 和 uid，不填写 ip，则该 uid 无法登录 app 中该 cname 对应的频道。
  • 当 privileges 设为 publish_audio 或 publish_video 时，过滤规则如下：
    • 如果填写 ip，不填写 cname 和 uid，则该 ip 无法在 app 中的任何频道内发送音频或视频流。
    • 如果填写 cname，不填写 uid 和 ip，则任何人都无法在该 cname 对应的频道内发送音频或视频流。
    • 如果填写 uid，不填写 cname 和 ip，则该 uid无法在 app 中的任何频道内发送音频或视频流。
    • 如果填写 cname 和 uid，不填写 ip，则该 uid 无法在该 cname 对应的频道发送音频或视频流。

用户被踢出频道后，会收到网络连接已被服务器禁止回调：

  • Android: onConnectionStateChanged 回调报告 CONNECTION_CHANGED_BANNED_BY_SERVER(3)。
  • iOS/macOS: connectionChangedToState 回调报告 AgoraConnectionChangedBannedByServer(3)。
  • Web: Client.on("client-banned")。
  • Windows: onConnectionStateChanged 回调报告 CONNECTION_CHANGED_BANNED_BY_SERVER(3)。
  • Electron: AgoraRtcEngine.on("connectionStateChanged") 回调报告 3。
  • Unity: OnConnectionStateChangedHandler 回调报告 CONNECTION_CHANGED_BANNED_BY_SERVER(3)。

# 1 创建封禁用户权限规则

接口地址 方法 说明
BaseUrl/api/v1/kicking-rule POST 创建踢人规则

RequestBody： Content-Type="application/json;charset=utf8"

参数 描述
appId 必填，控制台中项目的APP ID（应用标识ID）
cname 频道名称
uid 用户uid
ip 用户ip
time或time_in_seconds 必填，封禁时长
privileges 必填，封禁权限(join_channel,publish_audio,publish_video)

字段说明：

time
	封禁时间，单位是分钟，取值范围为 [0,1440]。
	注意事项：设置的值大于 `1440`，服务端自动改设为 `1440`。设置的值为 `0`， 表示不封禁。服务端会对频道内符合设定规则的用户进行下线一次的操作。用户可以重新登录进入频道。`time` 和 `time_in_seconds` 两个参数只需设置其中的一个。如果同时设置，将使用 `time_in_seconds` 参数。
time_in_seconds
	封禁时间，单位是秒，取值范围为[0]或者[10,86430]。
	注意事项：设置的值在 `0` 到 `10` 之间，服务端自动改设为 `10`。设置的值大于 `86430`，服务端自动改设为 `86430`。设置的值为 `0`， 表示不封禁。服务端会对频道内符合设定规则的用户进行下线一次的操作。用户可以重新登录进入频道。`time` 和 `time_in_seconds` 两个参数只需设置其中的一个。如果同时设置，将使用 `time_in_seconds` 参数。

响应数据：

实例：
[POST] https://192.168.2.251/client/api/v1/kicking-rule
请求json数据：
{
  "appId": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
  "cname": "channel1",
  "uid": 589517928,
  "ip": "",
  "time": 60,
  "privileges": [
    "join_channel"
  ]
}
响应：
{
    "msg": "操作成功",
    "code": 200,
    "data": {
        "id": 2
    }
}

# 2 获取封禁用户权限规则列表

接口地址 方法 说明
BaseUrl/api/v1/kicking-rule GET 获取踢人规则列表

PathVariable：

参数 描述
appId 必填，控制台中项目的APP ID（应用标识ID）

响应数据：

实例：
[GET] https://192.168.2.251/client/api/v1/kicking-rule?appId=6030db678613f149de55d2a7
响应：
{
    "msg": "操作成功",
    "code": 200,
    "data": [
        {
            "id": 4,
            "appId": "6030db678613f149de55d2a7",
            "cname": "channel1",
            "uid": "589517928",
            "ip": "",
            "time": "2021-02-25 18:17:37",
            "createTime": "2021-02-25 17:17:37",
            "updateTime": "2021-02-25 17:17:37",
            "privileges": [
                "join_channel"
            ]
        }
    ]
}

# 3 更新封禁用户权限规则的生效时间

接口地址 方法 说明
BaseUrl/api/v1/kicking-rule PUT 更新踢人规则的生效时间

RequestBody： Content-Type="application/json;charset=utf8"

参数 描述
appId 必填，控制台中项目的APP ID（应用标识ID）
id 规则ID
time或time_in_seconds 必填，封禁时长

响应数据：

实例：
[PUT] https://192.168.2.251/client/api/v1/kicking-rule
请求JSON数据：
{
  "appId": "6030db678613f149de55d2a7",
  "id": 4,
  "time": 600
}
响应：
{
    "msg": "操作成功",
    "code": 200,
    "data": {
        "id": 4
    }
}

# 4 删除封禁用户权限规则

接口地址 方法 说明
BaseUrl/api/v1/kicking-rule DELETE 删除踢人规则

RequestBody： Content-Type="application/json;charset=utf8"

参数 描述
appId 必填，控制台中项目的APP ID（应用标识ID）
id 规则ID

响应数据：

实例：
[DELETE] https://192.168.2.251/client/api/v1/kicking-rule
请求JSON数据：
{
  "appId": "6030db678613f149de55d2a7",
  "id": 4
}
响应：
{
    "msg": "操作成功",
    "code": 200,
    "data": {
        "id": 4
    }
}

← 查询在线频道信息 →