创建规则
更新时间不可用
创建用于封禁指定用户权限的规则。
POST
https://api.sd-rtn.com/dev/v1/kicking-rule该方法创建封禁用户权限的规则。
可封禁的用户权限（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")。
注意
为了最大程度保障核心功能创建 (POST)、更新 (PUT) 和删除 (DELETE) 的成功率，在公网质量异常抖动下，查询 (GET) 方法的成功率和准确性会有一定程度降级。查询 (GET) 的返回结果中，可能会缺失部分请求记录。
当你要创建 (POST) 一条封禁规则（time 不为 0），并需要在后续更新和删除该规则时，建议：
- 在你的服务端保存 POST 请求返回的规则 ID，并依赖该 ID 实现后续更新和解封操作。
- 为确保在公网质量异常时依然能够获取该请求返回的规则 ID，请求超时时间建议设置为 20 秒以上，最低不低于 5 秒。
- 仅当 POST 请求超时或者返回 504 时，可以参考 GET 结果尝试获取对应规则 ID。如果规则存在，说明 POST 请求成功，则在你的服务端保存规则 ID。
鉴权
Content-Typestringapplication/json。表示所有请求和响应内容的格式均为 JSON。
appidstring必填
项目的 App ID。可通过以下方式获取：
- 从声网控制台获取。
- 调用获取所有项目信息 API，并读取响应包体中
vendor_key字段的值。
cnamestring频道名称。
uidnumber用户 ID。不能设为 0。
ipstring用户的 IP 地址。不能设为 0。
timenumber封禁时间，单位为分钟，取值范围为 [1,1440]。
注意：
- 当设置的值在
0到1之间时，服务端自动改设为1。 - 当设置的值大于
1440时，服务端自动改设为1440。 - 当设置的值为
0时，表示不封禁。服务端会对频道内符合设定规则的用户进行下线一次的操作。用户可以重新登录进入频道。 time和time_in_seconds两个参数只需设置其中的一个。如果同时设置，则time_in_seconds生效；如果都不设置，服务端会自动将封禁时间设为 60 分钟，即 3600 秒。
time_in_secondsnumber封禁时间，单位为秒，取值范围为 [10,86430]。
注意：
- 当设置的值在
0到10之间，服务端自动改设为10。 - 当设置的值大于
86430时，服务端自动改设为86430。 - 当设置的值为
0时，表示不封禁。服务端会对频道内符合设定规则的用户进行下线一次的操作。用户可以重新登录进入频道。 time和time_in_seconds两个参数只需设置其中的一个。如果同时设置，则time_in_seconds生效，如果都不设置，服务端会自动将封禁时间设为 60 分钟，即 3600 秒。
privilegesarray<string>你想要封禁的用户权限，取值包括：
join_channel：加入频道，表示禁止用户加入频道或将用户踢出频道。publish_audio：发送音频，表示禁止用户发送音频流。可以与 publish_video 同时设置，表示禁止用户发送音视流和视频流。publish_video：发送视频，表示禁止用户发送视频流。可以与 publish_audio 同时设置，表示禁止用户发送音视流和视频流。
响应
如果状态码为 200，则请求成功。
响应 Body
statusstring本次请求的状态。success 表示请求成功。
idnumber规则 ID。当更新或删除封禁用户权限规则时，需要传入规则 ID。
请求示例
curl --request POST \
--url "https://api.sd-rtn.com/dev/v1/kicking-rule" \
--header 'Authorization: Basic <credentials>' \
-H 'Content-Type: application/json' \
-d '{
"appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
"cname": "channel1",
"uid": 589517928,
"ip": "",
"time": 60,
"privileges": [
"join_channel"
]
}'响应示例
{
"status": "success",
"id": 1953
}