# 调用 RTC RESTful API (/zh-CN/realtime-media/rtc/build/setup-and-access/call-api)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

## 前提条件 [#前提条件]

本文介绍声网 RESTful API 的构成，并引导你如何正确地调用 API。

在调用 RESTful API 之前，请确保已获取声网 App ID 和 Token（可选，用于安全鉴权）；对于服务端产品，还需要获取客户 ID 和客户密钥。可参考[开通 RTC 服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)。

## 配置 URL [#配置-url]

以[创建封禁用户权限规则](/zh-CN/api-reference/api-ref/rtc/create-ban-rule)为例，请求 URL 格式如下：

```text
https://api.sd-rtn.com/dev/v1/kicking-rule
```

其中：

- `https`：通信协议。声网使用 HTTPS 协议。

- `api.sd-rtn.com`：声网服务端域名。

- `dev/v1/kicking-rule`：资源路径。其中包括 API 版本和资源名。

以上示例仅作参考，你可以参照要调用的 API 的文档，在代码源文件或调试应用中先选择调用方法（如 GET、POST、PUT、PATCH、DELETE），然后根据 API 文档来配置实际的请求 URL。请求 URL 需要区分大小写。

## 发送请求 [#发送请求]

请求包括请求 Header 和请求 Body 两部分。在配置完 URL 后，你需要设置请求头和包体信息，然后向服务器发送请求。

以下是[创建封禁用户权限规则](/zh-CN/api-reference/api-ref/rtc/create-ban-rule)的请求示例：

```shell
curl --location --request POST 'https://api.sd-rtn.com/dev/v1/kicking-rule' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: <http_basic_auth>' \
--data '{
  "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
  "cname": "channel1",
  "uid": 589517928,
  "ip": "123",
  "time": 60,
  "privileges": [
    "join_channel"
  ]
}'
```

该示例展示了如何通过向指定的 API 地址发送包含 App ID、频道名、用户 ID、用户 IP、封禁时长和权限列表的 POST 请求来创建封禁用户权限规则。以上示例仅作参考，你可以参照要调用的 API 的文档，配置实际的请求头和包体信息。

### 请求头 [#请求头]

请求 Header 包含处理请求所需的信息，例如：

- `Accept`：告知服务器，客户端可以处理哪些类型的响应，如 `application/json`。
- `Authorization`：声网 RESTful API 要求 HTTP 鉴权。每次发送 HTTP 请求时，都必须在请求 Header 部填入 Authorization 字段。关于如何生成该字段的值，请参考[实现 HTTP 基本认证](/zh-CN/realtime-media/rtc/build/setup-and-access/http-basic-auth)。
- `Content-Type`：指定请求 Body 的类型为 `application/json`。

### 请求包体（可选） [#请求包体可选]

请求 Body 包含要发送给服务器的数据。例如，创建一个新的封禁用户权限的规则，你需要在请求包体中包含封禁权限的参数信息，如 App ID、频道名、用户 ID、用户 IP、封禁时长以及封禁的权限等。详情可参考具体 API 文档的参数描述。请求包体需要区分大小写。

## 接收响应 [#接收响应]

在发送请求后，声网服务器会对你的请求进行响应。响应包括响应状态码和响应 Body，频道管理 RESTful API 没有响应 Header。

### 响应状态码 [#响应状态码]

响应的 HTTP 状态码分为 200 和非 200 两种情况，详情可参考[REST 响应状态码](/zh-CN/realtime-media/rtc/reference/response-code)。

- 如果返回的 HTTP 状态码为 200，表示请求成功。
- 如果 HTTP 状态码不为 200，参考响应状态码排查问题。

### 响应包体 [#响应包体]

响应 Body 包含服务器返回的数据。例如，创建封禁用户权限规则的响应包体包括本次请求的状态和规则 ID 等信息。具体信息以每个 API 的返回值为准。

以下是[创建封禁用户权限规则](/zh-CN/api-reference/api-ref/rtc/create-ban-rule)的响应示例：

```json
{
  "status": "success",
  "id": 1953
}
```

## 错误处理 [#错误处理]
当你遇到问题时，可以使用开发者工具查看请求和响应，结合[REST 响应状态码](/zh-CN/realtime-media/rtc/reference/response-code)进行排查。如未能解决问题，可联系[技术支持](https://ticket.shengwang.cn)。