REST API 简介
REST API 是在线直播房间 SDK 的后台 HTTP 管理接口,其主要目的在于为开发者提供一套简单的管理入口。
为了安全性,REST API 仅提供 HTTPS 接口。
前提条件
要调用 REST API,您必须购买或领取 LiveSdk 所需的套餐包。
调用方法
请求 URL
REST API 的 URL 格式如下:
https://console.tim.qq.com/$ver/$servicename/$command?sdkappid=$SDKAppID&identifier=$identifier&usersig=$usersig&random=99999999&contenttype=json
其中各个参数的含义以及取值如下(参数名称及其取值均区分大小写):
参数 | 含义 | 取值 |
https | 请求协议 | 请求协议为 HTTPS,请求方式为 POST |
console.tim.qq.com | 请求域名 | 固定为 console.tim.qq.com |
ver | 协议版本号 | 固定为 v4 |
servicename | 内部服务名,不同的 servicename 对应不同的服务类型 | |
command | 命令字,与 servicename 组合用来标识具体的业务功能 | |
sdkappid | App 在即时通信 IM 控制台获取的应用标识 | 在申请接入时获得 |
identifier | 用户名,调用 REST API 时必须为 App 管理员账号 | |
usersig | 用户名对应的密码 | |
random | 标识当前请求的随机数参数 | 32位无符号整数随机数,取值范围0 - 4294967295 |
contenttype | 请求格式 | 固定值为 json |
注意:
App 服务端在调用 REST API 时,identifier 必须为 App 管理员账号。
App 可以在每次调用 REST API 时都生成管理员账号的 UserSig,亦可生成一个固定的 UserSig 重复使用,但请特别注意 UserSig 的有效期。
HTTP 请求包体格式
REST API 仅支持 POST 方法,其请求包体为 JSON 格式,具体的包体格式参见每个 API 的详细描述。
需要特别注意的是,POST 包体不能为空,即使某条协议包体中不需要携带任何信息,也需要携带一个空的 JSON 对象,即
{}
。HTTP 返回码
除非发生网络错误(例如502错误),否则 REST API 的调用结果均为200,真正的 API 调用错误码与错误信息在 HTTP 应答包体中返回。
HTTP 应答包体格式
REST API 的应答包体也是 JSON 格式,其格式符合如下特征:
{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0,"RequestId": "Id-70e312f1de024af5a36714b7b71da224-O-Seq-63504"// REST API 其他应答内容}
应答包体中必然包含 ActionStatus、ErrorInfo、ErrorCode、RequestId 这三个属性,其含义如下:
REST API 公共错误码
错误码 | 含义说明 |
60002 | HTTP 解析错误 ,请检查 HTTP 请求 URL 格式 |
60003 | HTTP 请求 JSON 解析错误,请检查 JSON 格式 |
60004 | 请求 URL 或 JSON 包体中账号或签名错误 |
60005 | 请求 URL 或 JSON 包体中账号或签名错误 |
60006 | SDKAppID 失效,请核对 SDKAppID 有效性 |
60007 | REST 接口调用频率超过限制,请降低请求频率 |
60008 | 服务请求超时或 HTTP 请求格式错误,请检查并重试 |
60009 | 请求资源错误,请检查请求 URL |
60010 | 请求需要 App 管理员权限 |
60011 | SDKAppID 请求频率超限,请降低请求频率 |
60012 | REST 接口需要带 SDKAppID,请检查请求 URL 中的 SDKAppID |
60013 | HTTP 响应包 JSON 解析错误 |
60014 | 置换账号超时 |
60015 | 请求包体账号类型错误,请确认账号为字符串格式 |
60016 | SDKAppID 被禁用。 |
60017 | 请求被禁用。 |
60018 | 请求过于频繁,请稍后重试。 |
60019 | 请求过于频繁,请稍后重试。 |
60020 | 您的专业版套餐包已到期并停用,请登录 [即时通信 IM 购买页面](https://buy.cloud.tencent.com/avc) 重新购买套餐包。购买后,将在5分钟后生效。 |
60021 | RestAPI 调用来源 IP 非法。 |
FAQ
REST API 请求有概率超时,收不到任何响应?
1. Live 后台 REST 接口设置的超时时间是3s,调用方设置的超时时间应该长于3s。
2.
telnet console.tim.qq.com 443
确认能否连接服务端口。3. 使用
curl -I https://console.tim.qq.com
简单测试看状态码是否为200。4. 确认机器的 dns server 配置是内网 dns server,还是公共 dns server。如果是内网 dns server,请确保 dns server 网络出口和本机器网络出口 IP 所在地域运营商一致。
5. 建议业务调用方使用“长连接+连接池”模式。
说明:
由于 HTTPS 短连接建连耗时比较大,每次请求都有 TCP + tls 握手开销,所以建议 REST API 长连接接入。
使用标准 HTTP 库的场景:HTTP1.0 需要指定请求头部 Connection: keep-alive,HTTP1.1 默认支持长连接;基于 TCP 封装 HTTPS 请求的场景,可以复用 TCP 连接来收发请求。