# 创建规则 (/zh-CN/api-reference/api-ref/rtc/create-ban-rule) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 创建用于封禁指定用户权限的规则。 - OpenAPI: /openapi/rtc/channel-management.zh-CN.yaml - Operation ID: post-dev-v1-kicking-rule - Method: POST - Path: /dev/v1/kicking-rule - Endpoint: https://api.sd-rtn.com/dev/v1/kicking-rule ## Servers - https://api.sd-rtn.com 该方法创建封禁用户权限的规则。 可封禁的用户权限(`privileges`)包括: - `join_channel`:加入频道 - `publish_audio`:发送音频流 - `publish_video`:发送视频流 封禁用户权限的规则通过 `cname`、`uid` 和 `ip` 三个字段实现过滤。 当 `privileges` 设为 `join_channel` 时: | ip | cname | uid | 过滤规则 | | --- | --- | --- | --- | | ✔ | ✘ | ✘ | 所有使用该 `ip` 的用户都无法登录 App 中的任何频道。使用 `ip` 作为过滤字段,可能会错误地封禁不该被封禁的用户,例如多人共享一个 IP 地址。 | | ✘ | ✔ | ✘ | 任何人都无法登录 App 中该 `cname` 对应的频道。使用 `cname` 作为过滤字段,相当于封禁该 `cname` 对应的频道。 | | ✘ | ✘ | ✔ | 该 `uid` 无法登录 App 中的任何频道。 | | ✘ | ✔ | ✔ | 该 `uid` 无法登录 App 中该 `cname` 对应的频道。 | 当 `privileges` 设为 `publish_audio` 或 `publish_video` 时,过滤规则如下: | ip | cname | uid | 过滤规则 | | --- | --- | --- | --- | | ✔ | ✘ | ✘ | 所有使用该 `ip` 的用户都无法在 App 中的任何频道内发送音频或视频流。 | | ✘ | ✔ | ✘ | 任何人都无法在该 `cname` 对应的频道内发送音频或视频流。 | | ✘ | ✘ | ✔ | 该 `uid` 无法在 App 中的任何频道内发送音频或视频流。 | | ✘ | ✔ | ✔ | 该 `uid` 无法在该 `cname` 对应的频道发送音频或视频流。 | 用户被踢出频道后(即 `privileges` 设置为 `join_channel`),会收到网络连接已被服务器禁止回调: - Android:`onConnectionStateChanged` 回调报告 `CONNECTION_CHANGED_BANNED_BY_SERVER(3)`。 - iOS/macOS:`connectionChangedToState` 回调报告 `AgoraConnectionChangedBannedByServer(3)`。 - Web 3.x:`Client.on("client-banned")`。 - Web 4.x:`Client.on("connection-state-change")` 回调报告 `UID_BANNED` 或 `IP_BANNED`。 - Windows:`onConnectionStateChanged` 回调报告 `CONNECTION_CHANGED_BANNED_BY_SERVER(3)`。 - Electron:`AgoraRtcEngine.on("connectionStateChanged")` 回调报告 3。 - Unity:`OnConnectionStateChangedHandler` 回调报告 `CONNECTION_CHANGED_BANNED_BY_SERVER(3)`。 - React Native:`ConnectionStateChanged` 回调报告 `BannedByServer(3)`。 - Flutter:`ConnectionStateChanged` 回调报告 `BannedByServer(3)`。 - Cocos Creator:`onConnectionStateChanged` 回调报告 `CONNECTION_CHANGED_BANNED_BY_SERVER(3)`。 - 小程序:`on(event: "client-banned")`。 :::warning[注意] 为了最大程度保障核心功能创建 (POST)、更新 (PUT) 和删除 (DELETE) 的成功率,在公网质量异常抖动下,查询 (GET) 方法的成功率和准确性会有一定程度降级。查询 (GET) 的返回结果中,可能会缺失部分请求记录。 当你要创建 (POST) 一条封禁规则(`time` 不为 0),并需要在后续更新和删除该规则时,建议: - 在你的服务端保存 POST 请求返回的规则 ID,并依赖该 ID 实现后续更新和解封操作。 - 为确保在公网质量异常时依然能够获取该请求返回的规则 ID,请求超时时间建议设置为 20 秒以上,最低不低于 5 秒。 - 仅当 POST 请求超时或者返回 504 时,可以参考 GET 结果尝试获取对应规则 ID。如果规则存在,说明 POST 请求成功,则在你的服务端保存规则 ID。 ::: ## Authorization This endpoint requires authentication. - `Basic Auth` ## Parameters - `Content-Type` (header, optional, string) - `application/json`。表示所有请求和响应内容的格式均为 JSON。 ## Request body - `appid` (string, required) - 项目的 App ID。可通过以下方式获取: - 从声网控制台获取。 - 调用[获取所有项目信息 API](/zh-CN/api-reference/api-ref/console/list-projects),并读取响应包体中 `vendor_key` 字段的值。 - `cname` (string) - 频道名称。 - `uid` (number) - 用户 ID。不能设为 `0`。 - `ip` (string) - 用户的 IP 地址。不能设为 `0`。 - `time` (number) - 封禁时间,单位为分钟,取值范围为 [1,1440]。 **注意:** - 当设置的值在 `0` 到 `1` 之间时,服务端自动改设为 `1`。 - 当设置的值大于 `1440` 时,服务端自动改设为 `1440`。 - 当设置的值为 `0` 时,表示不封禁。服务端会对频道内符合设定规则的用户进行下线一次的操作。用户可以重新登录进入频道。 - `time` 和 `time_in_seconds` 两个参数只需设置其中的一个。如果同时设置,则 `time_in_seconds` 生效;如果都不设置,服务端会自动将封禁时间设为 60 分钟,即 3600 秒。 - `time_in_seconds` (number) - 封禁时间,单位为秒,取值范围为 [10,86430]。 **注意:** - 当设置的值在 `0` 到 `10` 之间,服务端自动改设为 `10`。 - 当设置的值大于 `86430` 时,服务端自动改设为 `86430`。 - 当设置的值为 `0` 时,表示不封禁。服务端会对频道内符合设定规则的用户进行下线一次的操作。用户可以重新登录进入频道。 - `time` 和 `time_in_seconds` 两个参数只需设置其中的一个。如果同时设置,则 `time_in_seconds` 生效,如果都不设置,服务端会自动将封禁时间设为 60 分钟,即 3600 秒。 - `privileges` (array) - 你想要封禁的用户权限,取值包括: - `join_channel`:加入频道,表示禁止用户加入频道或将用户踢出频道。 - `publish_audio`:发送音频,表示禁止用户发送音频流。可以与 publish_video 同时设置,表示禁止用户发送音视流和视频流。 - `publish_video`:发送视频,表示禁止用户发送视频流。可以与 publish_audio 同时设置,表示禁止用户发送音视流和视频流。 - `privileges.items` (string) ### Request body example ```json { "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2", "cname": "channel1", "uid": 589517928, "ip": "", "time": 60, "privileges": [ "join_channel" ] } ``` ## Responses ### 200 如果状态码为 200,则请求成功。 - `status` (string) - 本次请求的状态。`success` 表示请求成功。 - `id` (number) - 规则 ID。当更新或删除封禁用户权限规则时,需要传入规则 ID。 ### 非 200 如果状态码不为 200,则请求失败。你可以参考[响应状态码](/zh-CN/realtime-media/rtc/reference/response-code)排查问题。 No schema. ## Response examples ### 200 ```json { "status": "success", "id": 1953 } ```