# 创建规则 (/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
}
```