MLVBLiveRoom 方案 - 管理后台RoomService接口文档

原创

腾讯云-chaoli

修改于 2022-01-14 18:30:05

21.1K31

修改于 2022-01-14 18:30:05

本文用于介绍移动直播 MLVBLiveRoom 方案的管理后台部分，MLVBLiveRoom 方案包含了两部分内容：客户端 MLVBLiveRoom 组件 + 房间管理服务 RoomService。MLVBLiveRoom 组件说明见 https://cloud.tencent.com/developer/article/1488540

特别注意：
目前腾讯云 MLVBLiveRoom 方案已有方案替代，新的方案效果表现更佳。如您有直播连麦需求请参考文档接入新方案。

版本说明

版本	时间	备注
2.0	2019.05.04	实现独立模式账户身份验证下的直播房间管理后台接口。MLVBLiveRoom组件配套的后台API。

功能说明

功能点

获取登录信息
登录帐号
获取直播推流地址
创建直播房间
销毁直播房间
获取直播房间列表
获取直播房间信息
加入直播间成为主播/小主播
主播退出直播间
直播间主播上报心跳
进入直播间成为观众
观众退出直播间
获取观众列表和观众人数
视频混流
登出账号

请求方式

协议：https
域名：liveroom.qcloud.com
方式：POST(只有get_login_info是get请求)
请求数据格式：json封装
应答数据格式：json封装

获取登录信息：

//demo中获取腾讯云直播服务的测试账号
https://room.qcloud.com/weapp/utils/get_login_info?userID=james

登录请求：

https://liveroom.qcloud.com/weapp/live_room/login?sdkAppID=1400042982&userID='james'&userSig='xxxxxxx'

其他请求：

https://liveroom.qcloud.com/weapp/live_room/interface_name?userID='james'&token='xxxxxxx'

接口示例

1. 登录账号

登录直播房间管理后台获取登录票据token，用于其他接口的访问。登录所需的sdkAppID、userID和userSig需要提前准备好。

* 接口名：login

* 请求示例：

* 应答示例：

{
    "code": 0,
    "message": "Success!",
    "timestamp": 1565610959661,
    "token": "c9527c191598662c6f392146f65ae520*1400047134",
    "userID": "user_dda36c3f_7c91"
}

字段	类型	选项	说明
userID	String	必填	用户ID（业务确保唯一性）
token	String	必填	用户登录票据（后续其它请求需要带上用于对用户鉴权）

2. 获取直播推流地址

向后台请求用于直播推流用的推流地址

* 接口名：get_anchor_url

* 请求示例：

{    "userID":"james"}

字段	类型	选项	说明
userID	String	必填	用户唯一ID

* 应答示例：

{
    "code":0,
    "message":"Success!",
    "timestamp":1566448332598,
    "accelerateURL":"rtmp://3891.liveplay.myqcloud.com/live/1400047134_james?txSecret=40272756aadc118f00b7e571eac89527&txTime=5D5F6C4C&bizid=3891",
    "pushURL":"rtmp://3891.livepush.myqcloud.com/live/1400047134_james?txSecret=40272756aadc118f00b7e571eac89527&txTime=5D5F6C4C"
}

字段	类型	选项	说明
pushURL	String	必填	包含userID信息的推流地址

3. 创建直播房间

向后台请求创建一个空直播房间，稍后第一个通过add_anchor接口进入房间的用户，将成为房间的主播

* 接口名：create_room

* 请求示例：

{
    "userID": "james",
    "roomInfo": "美食大侦探",
    "roomID": ""
}

字段	类型	选项	说明
userID	String	必填	用户唯一ID
roomInfo	String	必填	房间信息（可以是json格式的字符串，用于存放多个信息字段，后台不会修改该字段）
roomID	String	可选	房间ID

* 应答示例：

{
    "code":0,
    "message":"Success!",
    "timestamp":1566448711741,
    "admin":"",
    "roomID":"room_user_dda36c3f_7c91"
}

字段	类型	选项	说明
roomID	String	必填	直播房间ID（同时也是聊天群ID）

4. 销毁直播房间

接口名：destroy_room
请求示例：

{
	"roomID": "room_1341431_1344",
	"userID": "james"
}

字段	类型	选项	说明
roomID	Int	必填	直播房间ID
userID	String	必填	用户唯一ID（第一个进入房间成为主播的人才有权限销毁直播房间）

* 应答示例：

{
	"code": 0,
	"message": "请求成功"
}

5. 获取直播房间列表

向后台请求直播房间列表，采用分页请求方式

* 接口名：get_room_list

* 请求示例：

{
	"cnt": 10,
	"index": 0
}

应答示例：

{
	"code": 0,
	"message": "请求成功",
	"rooms": [{
		"roomID": "room_1341431_1344",
		"roomInfo": "美食大侦探",
		"roomCreator": "james",
		"mixedPlayURL": "http://1234.mycloud.play.com.cn/live/1234_james_3133.flv",
		"pushers": [{
			"userID": "james",
			"userName": "大王",
			"userAvatar": "https://img.cloud.com/134/134/139184143.png",
			"accelerateURL": "rtmp://1234.mycloud.play.com.cn/live/1234_james_3133?bizid=1234&txSerect=xxxxxx&txTime=21AE9183"
		}]
	}]
}

字段	类型	选项	说明
index	Int	必填	期望的房间索引的开始位置
cnt	Int	必填	期望的房间个数
rooms	Array	必填	直播房间列表
room.roomID	String	必填	直播间ID（）
room.roomInfo	String	必填	房间信息
room.roomCreator	String	必填	房间的大主播
room.mixedPlayURL	String	必填	房间的大主播的流观看地址（也是混流后的地址）
pushers	Array	必填	房间中直播用户（小主播也算直播用户）
pusher.userID	String	必填	用户ID
pusher.userName	String	必填	用户昵称
pusher.userAvatar	String	必填	用户头像
pusher.accelerateURL	String	必填	低延时播放地址（播放会有更低的时延，主要用于实时音视频和连麦场景）

6.获取直播房间信息

获取指定房间的信息

* 接口名：get_anchors

* 请求示例：

{
	"roomID": "room_1341431_1344"
}

字段	类型	选项	说明
roomID	String	必填	直播房间ID

* 响应示例：

{
	"code": 0,
	"message": "请求成功",
	"roomID": "room_1341431_1344",
	"roomInfo": "美食大侦探",
	"roomCreator": "james",
	"mixedPlayURL": "http://1234.mycloud.play.com.cn/live/1234_james_3133.flv",
	"pushers": [{
		"userID": "james",
		"userName": "大王",
		"userAvatar": "https://img.cloud.com/134/134/139184143.png",
		"accelerateURL": "rtmp://1234.mycloud.play.com.cn/live/1234_james_3133?bizid=1234&txSerect=xxxxxx&txTime=21AE9183"
	}]
}

字段	类型	选项	说明
index	Int	必填	期望的房间索引的开始位置
cnt	Int	必填	期望的房间个数
roomID	String	必填	直播间ID
roomInfo	String	必填	房间信息
roomCreator	String	必填	房间的大主播
mixedPlayURL	String	必填	房间的大主播的流观看地址（也是混流后的地址）
pushers	Array	必填	房间中直播用户（小主播也算直播用户）
pusher.userID	String	必填	用户ID
pusher.userName	String	必填	用户昵称
pusher.userAvatar	String	必填	用户头像
pusher.accelerateURL	String	必填	低延时播放地址（播放会有更低的时延，主要用于实时音视频和连麦场景）

7. 加入直播间成为主播/小主播

首个加入直播间成为大主播，否则成为小主播

* 接口名：add_anchor

* 请求示例：

{
	"roomID": "room_1341431_1344",
	"userID": "james",
	"userName": "大王",
	"pushURL": "rtmp://mycloud.com.cn/live/james_2134?bizid=&txSercet=xxxxx&txTime=AE134143",
	"userAvatar": "xxxxxxxx"
}

字段	类型	选项	说明
roomID	String	必填	房间ID
userID	String	必填	用户ID
userName	String	必填	用户昵称
pushURL	String	必填	推流地址
userAvatar	String	必填	用户头像链接地址

* 应答示例：

{
	"code": 0,
	"message": "请求成功"
}

8. 主播退出直播间

接口名：delete_anchor
请求示例：

{
	"roomID": "room_1341431_1344",
	"userID": "james"
}

字段	类型	选项	说明
roomID	String	必填	房间ID
userID	String	必填	用户ID

* 应答示例：

{
	"code": 0,
	"message": "请求成功"
}

9. 直播间主播上报心跳

主播上报心跳, 后台定时检查心跳, 心跳超时的将会从房间剔除

* 接口名：anchor_heartbeat

* 请求示例：

{
	"roomID": "room_1341431_1344",
	"userID": "james"
}

字段	类型	选项	说明
roomID	String	必填	房间ID
userID	String	必填	用户ID

* 应答示例：

{
	"code": 0,
	"message": "请求成功"
}

10. 进入直播间成为观众

成为普通直播观众,观众人数加1,和保存前30位的观众信息

* 接口名：add_audience

* 请求示例：

{
	"roomID": "room_1341431_1344",
	"userID": "james",
	"userInfo": ""
}

字段	类型	选项	说明
roomID	String	必填	房间ID
userID	String	必填	用户ID
userInfo	String	必填	用户信息，客户可以自定义（后台不会修改）

* 应答示例：

{
	"code": 0,
	"message": "请求成功"
}

11. 观众退出直播间

观众退出, 观众人数减1并从观众列表删除

* 接口名： delete_audience

* 请求示例：

{
	"roomID": "room_1341431_1344",
	"userID": "james"
}

字段	类型	选项	说明
roomID	String	必填	房间ID
userID	String	必填	用户ID

* 应答示例：

{
	"code": 0,
	"message": "请求成功"
}

12. 获取观众列表和观众人数

接口名：get_audiences
请求示例：

{
	"roomID": "room_1341431_1344"
}

字段	类型	选项	说明
roomID	String	必填	房间ID

应答示例：

{
	"code": 0,
	"message": "请求成功"
	"count": 128 "audiences": [{
		"userID": "",
		"userInfo": ""
	}]
}

字段	类型	选项	说明
count	Int	必填	直播观众人数
audiences	Array	必填	观众列表
audience.userID	String	必填	用户ID
audience.userInfo	String	必填	用户信息

13. 视频混流

视频混流, 大主播接收或结束小主播的连麦后需要对直播流混流, 这样直播观众才能看到大小主播在一起的连麦画面

* 接口名：merge_stream

* 请求示例：

{
	"roomID": "room_1341431_1344",
	"userID": "james",
	"mergeParams"：
	"{}"
}

字段	类型	选项	说明
roomID	String	必填	房间ID
userID	String	必填	用户ID
mergeParams	String	必填	混流参数，参考common_cgi混流接口参数指定，后台负责转发混流请求到common_cgi

* 应答示例：

{
	"code": 0,
	"message": "请求成功"
	"result": "{}"
}

字段	类型	选项	说明
result	String	必填	common_cgi混流接口的放回结果

14. 设置房间信息

接口名：set_custom_field

请求示例：

{
	"roomID": "room_1341431_1344",
	"userID": "james",
	"mergeParams"：
	"{}"
}

字段	类型	选项	说明
roomID	String	必填	房间ID
userID	String	必填	用户ID
mergeParams	String	必填	混流参数，参考common_cgi混流接口参数指定，后台负责转发混流请求到common_cgi

* 应答示例：

{
	"code": 0,
	"message": "请求成功"
	"result": "{}"
}

字段	类型	选项	说明
result	String	必填	common_cgi混流接口的放回结果

15. 登出账号

接口名： logout
请求示例：无

字段	类型	选项	说明
roomID	String	必填	房间ID
userID	String	必填	用户ID

* 应答示例：

{
	"code": 0,
	"message": "请求成功"
}

错误码

errorCode	errorMsg
200100	请求包错误，http方法错误或参数错误
200101	json请求体无法解析
201001	login操作中无sdk_appid或user sig
201002	缺少user id
201003	url中的userid与body中的userid不一致
201004	操作缺少room id参数
201005	获取room列表中，count参数未设置或设置为0
201006	云端混流参数缺少interface等必要参数
201008	不支持的操作
201009	set操作，但是value为空
202001	token鉴权失败
202002	连接IM鉴权server失败
202003	IM鉴权服务器的响应不合法
202004	登出失败，可能是后台删除记录失败
202005	sdkappid没有对应的appid
203002	创建房间失败
203003	销毁房间失败
203004	获取房间列表失败
203005	已经在房间，但是更新房间信息失败
203006	进房失败，可能原因1. 未开通直播 2. 未自定义域名 3. 开通直播，并自定义了域名，可能因为缓存需要等一段时间。
203007	房间内的主播个数太多
203009	房间名长度过长
203010	成员不在房间内
204001	获取推流url失败，可能原因1. 未开通直播 2. 未自定义域名 3. 开通直播，并自定义了域名，可能因为缓存需要等一段时间。
204002	获取主播列表失败
204003	删除主播信息失败，可能原因1. 房间不存在
204004	获取加速流播放地址失败，可能原因1. 未开通直播 2. 未自定义域名 3. 开通直播，并自定义了域名，可能因为缓存需要等一段时间。
205001	观众数目到达上限
205002	新增观众记录时处理失败
205003	删除观众记录失败
205004	获取观众列表失败
206001	设置心跳记录报错

FAQ

如果有对MLVBLiveRoom组件的业务流程进行修改，常会遇到以下几个问题。

1、主播建房成功，直播推流一小会，就会报房间已关闭，退出直播？

答：常见的原因是，把启心跳的步骤改丢了。

建房的流程是：开启摄像头推流、创建roomid、创建gourpid、加入推流房间addanchor、开启心跳。参考MLVBLiveRoom组件源码

roomService后台有房间保护逻辑：①、检测房间里面推流者anchor有没有音视频数据上行；②、检测这个anchor有没有心跳。

通常出现心跳超时，代表终端出现了异常，roomService会去检测音视频流，如果音视频流的上行数据也是0，会把roomid销毁。默认心跳保护时长是30S。

直播后台的音视频空数据0保护时长默认是70S。

建房时主播没有开启摄像头推流，roomService一直收不到直播后台回调的开启推流事件，会判断主播建房失败，也会销毁房间。

2、调试期间，经常遇到某些接口调不通，报错鉴权失败？

答：token过期了

login成功会返回token，之后调用其他接口都要带上userid和这个token。如果用相同userid在其他终端登录了，后台会刷新token，而原终端缓存的token是过期的，所以鉴权失败。

建议不要用相同userid在多终端登录。login接口其实就是IM的登录接口，可以在工程上面加上IM的踢重管理。

3、roomService支持点赞、打赏功能吗？

答：支持。

demo没有实现，但是可以通过发送自定义消息接口实现点赞、打赏。要记录房间当前点赞数，可以通过set_custom_field、get_custom_Info这两个接口读写。在后台是内存存储，当房间销毁后，这些信息就没有了，请注意做持久化。

4、特别提示！

①、如果有观众列表定制需求，请在您后台服务器上完善观众列表管理功能，roomService提供的这三个接口仅仅满足demo展示效果get_audiences、delete_audience、add_audience。

②、roomService暂时没有提供回调功能给您业务服务器，如果有回调需求，请在下方评论注明：appid+公司名+需要回调哪个数据。

4、使用postman调试，get_anchor_url请求有带token，但是返回总是校验token失败，message：verify failed，please check your token。token是用的刚login返回的token，肯定不会错的。

这是已知的坑，postman高版本会对token里面的*转义，导致后台收到的token不对，所以校验失败，建议使用6.0.10以下的postman版本调试，不会转义*。或者使用开发工具发起post请求

5、登录后返回的token，有效期是多久

7天

6、登录时报错：login info is not complete201001]，检查sdkappid、userid、userSig，都是正确的，使用im控制台校验工具能正常校验通过的

检查看看userSig里面是不是有=号，正常加密生成的userSig不会有=号的，一般都是只做了base64_encode，但是没有做特殊符号的替换。

把=换成_

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

云直播

移动直播

即时通信 IM

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

云直播

移动直播

即时通信 IM