RoomService管理后台接口文档

版本说明

版本

时间

备注

2.0

2019.05.04

实现独立模式账户身份验证下的直播房间管理后台接口

功能说明

功能点

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

请求方式

  • 协议: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混流接口的放回结果

14. 登出账号

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

字段

类型

选项

说明

roomID

String

必填

房间ID

userID

String

必填

用户ID

* 应答示例:

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

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+公司名+需要回调哪个数据。

原创声明,本文系作者授权云+社区发表,未经许可,不得转载。

如有侵权,请联系 yunjia_community@tencent.com 删除。

编辑于

我来说两句

0 条评论
登录 后参与评论

扫码关注云+社区

领取腾讯云代金券