多人音视频房间 SDK
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 多人音视频房间 SDK > 旧版文档 > REST API（旧） > REST API 简介

REST API 简介

最近更新时间：2023-08-08 14:54:52

我的收藏

本页目录：

REST API 是多人音视频房间 SDK 的后台 HTTP 管理接口，其主要目的在于为开发者提供一套简单的管理入口。
为了安全性，REST API 仅提供 HTTPS 接口。

前提条件

要调用 REST API，您必须购买或领取 RoomSdk 所需的套餐包。

调用方法

请求 URL

REST API 的 URL 格式入下：
https://xxxxxx/$service/$version/$kind/$command?sdkappid=$SDKAppID&identifier=$identifier&usersig=$usersig&random=99999999&contenttype=json
其中各个参数的含义以及取值如下（参数名称及其取值均区分大小写）：
参数
含义
取值
https
请求协议
请求协议为 HTTPS，请求方式为 POST
xxxxxx
专属域名
中国 roomkit.trtc.tencent-cloud.com
service
服务名
固定为 room_api
version
协议版本号
固定为 v1
kind
管理分类
示列：
v1/roomctl/create，其中 roomctl 为 kind
command
命令字，与 kind 组合用来表示具体的业务功能
示列： v1/roomctl/create，其中 create 为 command
sdkappid
在控制台获取的应用标识
在申请接入时获得
identifier
用户名，调用 REST API 时必须为 App 管理员账号
使用 IM 的管理员账号
usersig
用户名对应的密码
参见 生成 UserSig
random
标识当前请求的随机数参数
32位无符号整数随机数，取值范围 0 - 4294967295
contenttype
请求格式
固定值为 json
注意：
领取或购买套餐包后会在 IM 账号系统中创建 administrator 管理员账号，在请求中的identifier参数中请使用 administrator，如果您在 IM 账号管理 中取消或删除管理员，请正确指定管理员账号以及对应的 userSig。
App 可以在每次调用 REST API 时都生成管理员账号的 UserSig，亦可生成一个固定的 UserSig 重复使用，但需特别注意 UserSig 的有效期。
在创建房间以及进入房间等操作时，系统会在 IM 系统中自动导入 IM 账号，敬请知悉。

HTTP 请求包体格式

REST API 仅支持 POST 方法，其请求包体为 JSON 格式，具体的包体格式参见每个 API 的详细描述。
注意：
POST 包体不能为空，即使某条协议包体中不用携带任何信息，也必须要携带一个空的 JSON 对象，即{}。

HTTP 返回码

除非发生网络错误（例如502错误），否则 REST API 的调用结果均为200，实际 API 调用的错误码与错误信息在 HTTP 应答包体中返回。

HTTP 应答包体格式

REST API 的应答包体也是 JSON 格式，其格式符合如下特征：
{
    "errorCode": 0, // 错误码，0为成功，其余为失败
    "errorMessage": "Success", // 错误信息
    "requestId": "1c8960ac38d61be38b6fb219db0182d1", // 请求唯一标识符
    "data": {} // REST API 返回的数据
}

调用示例

以下为通过 REST API 来 创建房间示例。
HTTPS 请求：
POST /room_api/v1/roomctl/create?usersig=xxx&identifier=admin&sdkappid=88888888&random=99999999&contenttype=json HTTP/2
Host: roomkit.trtc.tencent-cloud.com
Content-Length: 89
{
    "ownerId": "alice", 
    "roomId": "xxx", 
    "roomInfo": {
        "maxSeatCount": "5",
        "roomName": "Alice's room"
    }
}
HTTPS 应答：
HTTP/2 200 OK
Date: Fri, 21 Apr 2023 06:06:16 GMT
Content-Length: 112
Connection: keep-alive

{
    "errorCode": 0,
    "errorMessage": "Success",
    "requestId": "e7463d9ce6ae8e41b8e7d148bdf2fa82",
    "data": {}
}

REST API 公共错误码

错误码
含义说明
0
请求成功
70001
请求参数无效，请检查必填参数是否缺失或填错
70002
UserSig 无效
70003
UserSig 过期
70004
请求用户非超级管理员
70005
请求被限频
未知错误码
系统内部错误，请联系技术人员

常见问题

REST API 请求有概率超时，收不到任何响应

1. 后台 REST 接口设置的超时时间是 3s，调用方设置的超时时间应该长于 3s。
2. telnet roomkit.trtc.tencent-cloud.com 443 确认能否连接服务端口。
3. 使用 curl -I https://roomkit.trtc.tencent-cloud.com 简单测试看状态码是否为200。
4. 确认机器的 dns server 配置是内网 dns server，还是公共 dns server。如果是内网 dns server，请确保 dns server 网络出口和本机器网络出口 IP 所在地域运营商一致。
5. 建议业务调用方使用长连接+连接池模式。
中国站