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

2022-01-14 18:30:05 浏览数 (1)

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

特别注意：

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

版本说明

版本

时间

备注

2.0

2019.05.04

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

功能说明

功能点

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

请求方式

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

获取登录信息：

代码语言：javascript复制
//demo中获取腾讯云直播服务的测试账号
https://room.zijiebao.com/weapp/utils/get_login_info?userID=james

登录请求：

代码语言：javascript复制
https://liveroom.zijiebao.com/weapp/live_room/login?sdkAppID=1400042982&userID='james'&userSig='xxxxxxx'

其他请求：

代码语言：javascript复制
https://liveroom.zijiebao.com/weapp/live_room/interface_name?userID='james'&token='xxxxxxx'

接口示例

1. 登录账号

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

* 接口名：login

* 请求示例：

* 应答示例：

代码语言：json复制
{
    "code": 0,
    "message": "Success!",
    "timestamp": 1565610959661,
    "token": "c9527c191598662c6f392146f65ae520*1400047134",
    "userID": "user_dda36c3f_7c91"
}

字段

类型

选项

说明

userID

String

必填

用户ID（业务确保唯一性）

token

String

必填

用户登录票据（后续其它请求需要带上用于对用户鉴权）

2. 获取直播推流地址

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

* 接口名：get_anchor_url

* 请求示例：

代码语言：json复制
{    "userID":"james"}

字段

类型

选项

说明

userID

String

必填

用户唯一ID

* 应答示例：

代码语言：json复制
{
    "code":0,
    "message":"Success!",
    "timestamp":1566448332598,
    "accelerateURL":"rtmp://3891.liveplay.myzijiebao.com/live/1400047134_james?txSecret=40272756aadc118f00b7e571eac89527&txTime=5D5F6C4C&bizid=3891",
    "pushURL":"rtmp://3891.livepush.myzijiebao.com/live/1400047134_james?txSecret=40272756aadc118f00b7e571eac89527&txTime=5D5F6C4C"
}

字段

类型

选项

说明

pushURL

String

必填

包含userID信息的推流地址

3. 创建直播房间

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

* 接口名：create_room

* 请求示例：

代码语言：json复制
{
    "userID": "james",
    "roomInfo": "美食大侦探",
    "roomID": ""
}

字段

类型

选项

说明

userID

String

必填

用户唯一ID

roomInfo

String

必填

房间信息（可以是json格式的字符串，用于存放多个信息字段，后台不会修改该字段）

roomID

String

可选

房间ID

* 应答示例：

代码语言：json复制
{
    "code":0,
    "message":"Success!",
    "timestamp":1566448711741,
    "admin":"",
    "roomID":"room_user_dda36c3f_7c91"
}

字段

类型

选项

说明

roomID

String

必填

直播房间ID（同时也是聊天群ID）

4. 销毁直播房间

  • 接口名：destroy_room
  • 请求示例：
代码语言：json复制
{
	"roomID": "room_1341431_1344",
	"userID": "james"
}

字段

类型

选项

说明

roomID

Int

必填

直播房间ID

userID

String

必填

用户唯一ID（第一个进入房间成为主播的人才有权限销毁直播房间）

* 应答示例：

代码语言：json复制
{
	"code": 0,
	"message": "请求成功"
}

5. 获取直播房间列表

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

* 接口名：get_room_list

* 请求示例：

代码语言：json复制
{
	"cnt": 10,
	"index": 0
}
  • 应答示例：
代码语言：json复制
{
	"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

* 请求示例：

代码语言：json复制
{
	"roomID": "room_1341431_1344"
}

字段

类型

选项

说明

roomID

String

必填

直播房间ID

* 响应示例：

代码语言：json复制
{
	"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

* 请求示例：

代码语言：json复制
{
	"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

必填

用户头像链接地址

* 应答示例：

代码语言：json复制
{
	"code": 0,
	"message": "请求成功"
}

8. 主播退出直播间

  • 接口名：delete_anchor
  • 请求示例：
代码语言：json复制
{
	"roomID": "room_1341431_1344",
	"userID": "james"
}

字段

类型

选项

说明

roomID

String

必填

房间ID

userID

String

必填

用户ID

* 应答示例：

代码语言：json复制
{
	"code": 0,
	"message": "请求成功"
}

9. 直播间主播上报心跳

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

* 接口名：anchor_heartbeat

* 请求示例：

代码语言：json复制
{
	"roomID": "room_1341431_1344",
	"userID": "james"
}

字段

类型

选项

说明

roomID

String

必填

房间ID

userID

String

必填

用户ID

* 应答示例：

代码语言：json复制
{
	"code": 0,
	"message": "请求成功"
}

10. 进入直播间成为观众

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

* 接口名：add_audience

* 请求示例：

代码语言：json复制
{
	"roomID": "room_1341431_1344",
	"userID": "james",
	"userInfo": ""
}

字段

类型

选项

说明

roomID

String

必填

房间ID

userID

String

必填

用户ID

userInfo

String

必填

用户信息，客户可以自定义（后台不会修改）

* 应答示例：

代码语言：json复制
{
	"code": 0,
	"message": "请求成功"
}

11. 观众退出直播间

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

* 接口名： delete_audience

* 请求示例：

代码语言：json复制
{
	"roomID": "room_1341431_1344",
	"userID": "james"
}

字段

类型

选项

说明

roomID

String

必填

房间ID

userID

String

必填

用户ID

* 应答示例：

代码语言：json复制
{
	"code": 0,
	"message": "请求成功"
}

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

  • 接口名：get_audiences
  • 请求示例：
代码语言：json复制
{
	"roomID": "room_1341431_1344"
}

字段

类型

选项

说明

roomID

String

必填

房间ID

  • 应答示例：
代码语言：json复制
{
	"code": 0,
	"message": "请求成功"
	"count": 128 "audiences": [{
		"userID": "",
		"userInfo": ""
	}]
}

字段

类型

选项

说明

count

Int

必填

直播观众人数

audiences

Array

必填

观众列表

audience.userID

String

必填

用户ID

audience.userInfo

String

必填

用户信息

13. 视频混流

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

* 接口名：merge_stream

* 请求示例：

代码语言：json复制
{
	"roomID": "room_1341431_1344",
	"userID": "james",
	"mergeParams"：
	"{}"
}

字段

类型

选项

说明

roomID

String

必填

房间ID

userID

String

必填

用户ID

mergeParams

String

必填

混流参数，参考common_cgi混流接口参数指定，后台负责转发混流请求到common_cgi

* 应答示例：

代码语言：json复制
{
	"code": 0,
	"message": "请求成功"
	"result": "{}"
}

字段

类型

选项

说明

result

String

必填

common_cgi混流接口的放回结果

14. 设置房间信息

接口名：set_custom_field

请求示例：

代码语言：javascript复制
{
	"roomID": "room_1341431_1344",
	"userID": "james",
	"mergeParams"：
	"{}"
}

字段

类型

选项

说明

roomID

String

必填

房间ID

userID

String

必填

用户ID

mergeParams

String

必填

混流参数，参考common_cgi混流接口参数指定，后台负责转发混流请求到common_cgi

* 应答示例：

代码语言：javascript复制
{
	"code": 0,
	"message": "请求成功"
	"result": "{}"
}

字段

类型

选项

说明

result

String

必填

common_cgi混流接口的放回结果

15. 登出账号

  • 接口名： logout
  • 请求示例： 无

字段

类型

选项

说明

roomID

String

必填

房间ID

userID

String

必填

用户ID

* 应答示例：

代码语言：javascript复制
{
	"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，但是没有做特殊符号的替换。

把=换成_

云直播 移动直播 即时通信IM

0 人点赞