服务端实现 - PK 连麦

更新时间： 2021/11/09 08:01:21

网易云信为您提供连麦 PK 场景方案的 Demo App，在此 Demo 中，我们通过服务端实现了一系列业务层直播过程管理、直播相关信息查看的接口，为 Demo App 提供直播业务管理的功能。您可以参考 Demo 对应的服务端接口设计，在本地服务端开发一套类似的接口，配合您的 App 实现连麦 PK 场景。

本文档介绍网易云信连麦 PK 场景的 Demo App 与应用服务端交互的业务流程，同时列举 Demo App 对应的服务端接口设计。

应用服务端与 App 的业务交互

主播端开播

观众端观看

主播邀请 PK

主播结束 PK

观众打赏

结束直播

应用服务端接口设计

请求结构

Header 中包括用于鉴权的相关参数，如非必要，每个接口单独的接口文档中不再对这些参数进行说明，但每次请求均需要携带这些参数，才能正常发起请求。

参数名称	类型	是否必选	描述
accessToken		是	接口鉴权 Token。

Body

服务端API请求的 Content-Type 为 application/json。其中包含业务相关的参数。

开启直播

主播创建直播房间，开启直播。

注意：调用此接口时，应用服务器需要设置直播相关的信息，并创建直播聊天室房间。

接口请求地址

POST {host}/v1/pkLive/liveRoomCreate HTTP/1.1
Content-Type: application/json;charset=utf-8

请求参数

参数名称	类型	是否必选	描述
roomTopic	String	必选	房间主题。
liveCoverPic	String	必选	封面地址。
liveType	Integer	必选	直播类型。2表示普通单人直播， 3 表示 PK 直播。
parentLiveCid	String	可选	创建 PK 直播时原直播的 liveCid。

返回参数

参数名称	类型	描述
code	int	状态码。200 表示正常调用。其他错误码请查看错误码。
data	Json	返回数据，Json 格式。
requestId	String	请求ID，用于跟踪日志。
costTime	String	请求消耗的时间。

data 参数说明：

参数名称	类型	描述
liveCid	String	直播号。
avRoomUid	String	音视频的个人的 UID。
avRoomCid	String	音视频的房间号。
avRoomCName	String	房间频道名称，即音视频房间的 channelName。
avRoomCheckSum	String	NERTC Token，加入音视频房间用的鉴权手段。
chatRoomId	String	聊天室房间号。
chatRoomCreator	String	聊天室创建者。
liveConfig	Json	直播配置。
liveCoverPic	地址	直播间背景图。
nickname	String	主播昵称。
roomTopic	String	房间主题。
live	int	直播状态。 0 表示未开始，1 表示正在进行普通单人直播，2 表示正在进行 PK 直播，3 表示 PK 直播结束，4 表示普通单人直播结束，5 表示 PK 惩罚。
msg	String	错误信息。

liveConfig 参数说明

参数名称	描述
httpPullUrl	http拉流地址。
rtmpPullUrl	rtmp拉流地址。
hlsPullUrl	hls拉流地址
pushUrl	推流地址。
cid	音视频房间号。
config	配置信息。

返回示例

{
    "code": 200,
    "data": {
        "liveCid": "f98c98***",
        "avRoomCName": "f98c985175***",
        "avRoomCid": "43292300969936",
        "avRoomUid": 160500020379487,
        "avRoomCheckSum": "e8e61b85f4d391***",
        "createTime": 1605000177,
        "roomKey": "YWVzOjA6a2JB*****",
        "nrtcAppKey": "f596afc*****",
        "liveConfig": {
            "httpPullUrl":"",
            "rtmpPullUrl":"",
            "hlsPullUrl":"",
            "pushUrl":"",
            "cid":"",
            "config":{}
        },
        "liveCoverPic": "",
        "nickname": "ss",
        "roomTopic":"sss",
        "status":1
    },
    "requestId": "af2d41*****",
    "costTime": "144ms"
}

结束直播

主播结束个人直播。

Demo App 调用此服务端接口时，服务端将此主播间状态标记为直播结束，并关闭聊天室和直播频道。

接口请求地址

POST {host}/v1/pkLive/liveRoomClose/ HTTP/1.1
Content-Type: application/json;charset=utf-8

请求参数

参数名称	类型	是否必选	描述
liveCid	String	必选	直播号。

返回参数

参数名称	类型	描述
code	int	状态码。200 表示正常调用。其他错误码请查看错误码。
data	boolean	true or false，表示操作是否成功。
requestId	String	请求ID，用于跟踪日志。
costTime	String	请求消耗的时间。

返回示例

{  
    "code": 200,
    "data": true,
    "requestId": "af2d416202011101723237570050000",
    "costTime": "144ms"
}

查询主播直播列表

查看正在直播的主播列表，结果可以分页展示。

当直播为 PK 直播时，pkLiveMembers 中有两个主播的信息。

接口请求地址

POST {host}/v1/pkLive/getLiveRoomList/ HTTP/1.1
Content-Type: application/json;charset=utf-8

请求参数

参数名称	类型	是否必选	描述
live	int	可选	直播类型。-1 表示全部；1 表示直播；2 表示 PK 直播。为空或者-1是查询全部直播列表。
pageNum	int	必选	第几页。
pageSize	int	必选	每页大小。

返回参数

参数名称	类型	描述
endRow	int	每页大小。
hasNextPage	boolean	是否有下一页。
hasPreviousPage	boolean	是否上一页。
isLastPage	boolean	最后一页。
isFirstPage	boolean	第一页。
list	JSONArray	直播房间列表。
liveCid	String	直播号或者PK直播号。
avRoomCName	String	房间频道名称 - 音视频房间的channelName。
avRoomUid	String	音视频的房间号。
status	int	房间状态状态: 0.未开始，1.房间中。
live	int	直播状态。 0 表示未开始，1 表示正在进行普通单人直播，2 表示正在进行 PK 直播，3 表示 PK 直播结束，4 表示普通单人直播结束，5 表示 PK 惩罚。
chatRoomId	String	聊天室频道号。
liveConfig	Json	直播配置。
chatRoomCreator	String	聊天室创建者。
liveCoverPic	String	直播房间封面。
nickname	String	主播昵称。
avatar	String	头像。
accountId	String	主播账号。
imAccid	String	IM AccId。
roomTopic	String	房间主题。
coinTotal	Long	打赏总量。
chatRoomId	String	聊天室频道号。
type	int	直播类型 2：直播 3 PK。
audienceCount	int	观众数量。
pageNum	int	第几页。
pageSize	int	每页大小。

liceConfig参数说明：

参数名称	描述
httpPullUrl	http拉流地址。
rtmpPullUrl	rtmp拉流地址。
hlsPullUrl	hls拉流地址
pushUrl	推流地址。
cid	音视频房间号。
config	配置信息。

返回示例

{
    "endRow": 2,
    "hasNextPage": false,
    "hasPreviousPage": false,
    "isFirstPage": true,
    "isLastPage": true,
    "liveRoomList": [{
        "liveCid": "f98c985175714270b2***",
        "avRoomCName": "f98c985175714270b2d1****",
        "avRoomCid": "43292300969936",
        "avRoomUid": 160500020379487,
        "createTime": 1605000177,
        "status": 2,
        "live": 2,
        "roomKey": "YWVzOj*****",
        "nrtcAppKey": "f596afcb74***",
        "liveConfig": {
            "httpPullUrl":"",
            "rtmpPullUrl":"",
            "hlsPullUrl":"",
            "pushUrl":"",
            "cid":"",
            "config":{}
        },
        "liveCoverPic": "",
        "nickname": "ss",
        "roomTopic": "sss",
        "accountId": "ssss",
        "type": "2",
        "audienceCount": 1111
    }],
    "navigateFirstPage": 1,
    "navigateLastPage": 1,
    "navigatePages": 8,
    "navigatepageNums": [1],
    "nextPage": 0,
    "pageNum": 1,
    "pageSize": 1000,
    "pages": 1,
    "prePage": 0,
    "size": 2,
    "startRow": 1,
    "total": 2
}

发起直播 PK

邀请其他主播开启 PK。

注意：调用此接口时，应用服务器需要：

更新PK直播房间状态为 PK 状态。
发送系统消息给PK中的主播，信息包括 pkStartTime 和 pkDuration。

接口请求地址

POST {host}/v1/pkLive/livePk HTTP/1.1
Content-Type: application/json;charset=utf-8

请求参数

参数名称	类型	是否必选	描述
liveCid	String	必选	PK 直播号。

返回参数

参数名称	类型	描述
code	int	状态码。200 表示正常调用。其他错误码请查看错误码。
data	boolean	true false
requestId	String	请求ID，用于跟踪日志。
costTime	String	请求消耗的时间。

返回示例

{  
    "code": 200,
    "data": true,
    "requestId": "af2d416202011101723237570050000",
    "costTime": "144ms"
}

获取直播房间中的主播信息

获取直播房间信息，包括房间类型等房间本身的状态与设置信息、房间中的主播用户信息等。

接口请求地址

POST {host}/pkLive/liveRoom/info HTTP/1.1
Content-Type: application/json;charset=utf-8

请求参数

参数名称	类型	是否必选	描述
liveCid	String	是	直播频道号。

返回参数

参数名称	类型	描述
code	int	状态码。200 表示正常调用。其他错误码请查看错误码。
data	Json	业务数据。
requestId	String	请求ID，用于跟踪日志。
costTime	String	请求消耗的时间。

data 数据结构：

参数名称	类型	描述
type	int	房间类型 1：多人语音 2：直播 3：PK直播。
liveCid	String	直播频道号。
avRoomCid	String	音频Cid。
avRoomCName	String	频道名称。
creatorAccountId	String	多人房间创建者账号id 邀请者账号。
status	String	成员状态，1-未开始，2- 直播中，3-结束直播。
pkStartTime	Long	PK直播开始时间。
pkRecord	Json	Pk直播记录。
members	JsonArrray	成员信息。

pkRecord 参数说明：

参数名称	类型	描述
invitee	String	被邀请者账号。
inviteeLiveCid	String	被邀请者原直播房间号。
inviteeRewards	String	被邀请者打赏总额。
inviter	String	邀请者账号。
inviterLiveCid	String	邀请者原直播房间号。
inviterRewards	Long	邀请者打赏总额。
liveCid	String	直播号。
pkEndTime	Long	PK结束时间。
pkStartTime	String	PK开始时间。
punishmentStartTime	Long	PK惩罚开始时间。
roomCid	Strng	音视频房间cid。
status	int	直播状态。1.正在直播， 2.PK直播，3.PK直播结束 4 直播结束 5 PK惩罚。

members 参数说明：

参数名称	类型	描述
accountId	String	用户id
appId	int	APP 的 ID。
audienceCount	int	观众数量。
avRoomCName	String	音视频房间的 channelName。
avRoomUid	String	音视频房间的用户id。
chatRoomCreator	String	聊天室创建者。
chatRoomId	String	聊天室频道号。
imAccd	String	IM 账号。
liveCid	String	直播号。
liveConfig	Json	直播配置。
liveCoverPic	String	直播房间封面。
nickName	String	昵称。
roomTopic	String	房间主题。
roomUid	String	房间 UID。
status	int	成员状态，1-未开始直播，2- 直播中，3-结束直播
live	int	直播状态。1.正在直播， 2.PK直播，3.PK直播结束 4 直播结束 5 PK惩罚。
parentLiveCid	String	PK直播时原直播频道号。

liveConfig 参数说明

参数名称	描述
httpPullUrl	http拉流地址。
rtmpPullUrl	rtmp拉流地址。
hlsPullUrl	hls拉流地址
pushUrl	推流地址。
cid	音视频房间号。
config	配置信息。

返回示例

{
    "code": 200,
    "data": {
        "avRoomCName": "string",
        "avRoomCid": "string",
        "liveCid": "string",
        "members": [{
            "accountId": "string",
            "appId": 0,
            "audienceCount": 0,
            "avRoomCName": "string",
            "avRoomUid": "string",
            "chatRoomCreator": "string",
            "chatRoomId": "string",
            "imAccd": "string",
            "liveCid": "string",
            "liveConfig": {
            "httpPullUrl":"",
            "rtmpPullUrl":"",
            "hlsPullUrl":"",
            "pushUrl":"",
            "cid":"",
            "config":{}
            },
            "liveCoverPic": "string",
            "nickname": "string",
            "roomTopic": "string",
            "roomUid": "string",
            "status": 0
        }],
        "pkRecord": {
            "invitee": "string",
            "inviteeLiveCidString": "string",
            "inviteeRewards": "string",
            "inviter": "string",
            "inviterLiveCid": "string",
            "inviterRewards": "string",
            "liveCid": "string",
            "pkEndTime": 0,
            "pkStartTime": 0,
            "punishmentStartTime": 0,
            "roomCid": "string",
            "status": 0
        },
        "pkStartTime": "string",
        "status": "string",
        "type": 0
    },
    "requestId": "af2d416202011101723237570050000",
    "costTime": "144ms"
}

随机获取直播间主题

随机获取直播间的主题。

接口请求地址

POST {host}/v1/pkLive/liveRoom/getRandomRoomTopic HTTP/1.1
Content-Type: application/json;charset=utf-8

请求参数

无

返回参数

参数名称	类型	描述
code	int	状态码。200 表示正常调用。其他错误码请查看错误码。
data	String	主题文案。
requestId	String	请求ID，用于跟踪日志。
costTime	String	请求消耗的时间。

返回示例

{  
    "code": 200,
    "data": "sssssss",
    "requestId": "af2d416202011101723237570050000",
    "costTime": "144ms"
}

查询直播 PK 结果

查询指定直播的 PK 结果信息。

接口请求地址

POST {host}/v1/pkLive/getPkResult HTTP/1.1
Content-Type: application/json;charset=utf-8

请求参数

参数名称	类型	是否必选	描述
liveCid	String	必选	PK 直播号。

返回参数

参数名称	类型	描述
code	int	状态码。200 表示正常调用。其他错误码请查看错误码。
data	Json	PK直播数据。
requestId	String	请求ID，用于跟踪日志。
costTime	String	请求消耗的时间。

data 参数说明：

参数名称	类型	描述
invitee	String	被要请者账号。
inviteeLiveCid	String	被邀请者的直播房间号。
inviteeRewards	Long	被邀请者打赏总额。
liveCid	String	直播房间号。
inviterRewards	Long	邀请者打赏总额。
pkEndTime	Long	PK结束时间。
pkStartTime	Long	PK开始时间。
punishmentStartTime	Long	惩罚开始时间。
roomCid	String	直播房间CId。
status	int	直播状态。
inviter	String	邀请者账号。
inviterLiveCid	String	邀请者原直播号。

{
    "code": 200,
    "data": {
        "invitee": "string",
        "inviteeLiveCid": "string",
        "inviteeRewards": "string",
        "inviter": "string",
        "inviterLiveCid": "string",
        "inviterRewards": "string",
        "liveCid": "string",
        "pkEndTime": 0,
        "pkStartTime": 0,
        "punishmentStartTime": 0,
        "roomCid": "string",
        "status": 0
    },
    "requestId": "af2d416202011101723237570050000",
    "costTime": "144ms"
}

直播PK时段打赏主播贡献排行榜查询

查询直播 PK 过程中，打赏主播的贡献排行榜。

接口请求地址

POST {host}/v1/pkLive/getPkLiveContriList HTTP/1.1
Content-Type: application/json;charset=utf-8

请求参数

参数名称	类型	是否必选	描述
liveCid	String	必选	直播频道号。
liveType	int		直播类型是否为是否 PK 直播。 2表示普通单人直播；3表示 PK 直播。
anchorAccountId	String	必选	主播账号 id。

返回参数

参数名称	类型	描述
code	int	状态码。200 表示正常调用。其他错误码请查看错误码。
data		业务数据。
requestId	String	请求ID，用于跟踪日志。
costTime	String	请求消耗的时间。

data 参数说明：

参数名称	类型	描述
rewardCoinTotal	Long	打赏总数。
rewardRankVOList	ArrayList	打赏贡献榜。

rewardRankVOList 参数说明：

参数名称	类型	描述
accountId	String	账号。
imAccId	String	IM 账号。
nickname	String	昵称。
avatar	String	头像。
rewardCoin	Long	打赏。

返回示例

{
    "code": 200,
    "data": {
        "rewardRankVOList": [
            {
                "accountId": "xx",
                "imAccid": "xxx",
                "nickname": "xx",
                "avatar": "xx",
                "rewardCoin": xx
            },
            {
                "accountId": "xxx",
                "imAccid": "xxx",
                "nickname": "xx",
                "avatar": "xx",
                "rewardCoin": xx
            }
        ],
        "rewardCoinTotal": xx
    },
    "requestId": "xxx",
    "costTime": "2092ms"
}

直播时段打赏总榜 (在线成员)

查看直播过程中的打赏总榜，榜单中只显示在线成员。

接口请求地址

POST {host}/v1/pkLive/getLiveContriList HTTP/1.1
Content-Type: application/json;charset=utf-8

请求参数

参数名称	类型	是否必选	描述
liveCid	String	必选	直播频道号
anchorAccountId	String	必选	主播账号 ID。

返回参数

参数名称	类型	描述
code	int	状态码。200 表示正常调用。其他错误码请查看错误码。
data	ArrayList	打赏贡献榜。
requestId	String	请求ID，用于跟踪日志。
costTime	String	请求消耗的时间。

data参数说明：

参数名称	类型	描述
accountId	String	账号。
imAccId	String	IM 账号。
nickname	String	昵称。
avatar	String	头像。
rewardCoin	Long	打赏。
memberTotal	Long	在线人数。

{
    "code": 200,
    "data": {
        "rewardRankVOList": [
            {
                "accountId": "xx",
                "imAccid": "xxx",
                "nickname": "xx",
                "avatar": "xx",
                "rewardCoin": xx
            },
            {
                "accountId": "xxx",
                "imAccid": "xxx",
                "nickname": "xx",
                "avatar": "xx",
                "rewardCoin": xx
            }
        ],
        "memberTotal": xx
    },
    "requestId": "xxx",
    "costTime": "2092ms"
}

直播间打赏

在直播间中打赏主播。

接口请求地址

POST {host}/v1/pkLive/reward HTTP/1.1 Content-Type: application/json;charset=utf-8

请求参数

参数名称	类型	是否必选	描述
liveCid	String	必选	直播频道号。
liveType	int	必选	直播类型是否为是否 PK 直播。 2表示普通单人直播；3 表示 PK 直播。
anchorAccountId	String	必选	主播编号。
giftId	int	必选	礼物编号。

返回参数

参数名称	类型	描述
code	int	状态码。200 表示正常调用。其他错误码请查看错误码。
data	boolean	true false
requestId	String	请求ID，用于跟踪日志。
costTime	String	请求消耗的时间。

返回示例

{  
    "code": 200,
    "requestId": "af2d416202011101723237570050000",
    "costTime": "144ms"
}

主播结束PK

主播退出 PK 直播。

注意：Demo App 调用此服务端接口时，服务端应标记 PK 直播房间为 PK 结束，并发送系统 IM 消息通知 A B 两主播退出房间。

接口请求地址

POST {host}/v1/pkLive/pkLiveRoomClose HTTP/1.1
Content-Type: application/json;charset=utf-8

请求参数

参数名称	类型	是否必选	描述
liveCid	String	必选	直播号

返回参数

参数名称	类型	描述
code	int	状态码。200 表示正常调用。其他错误码请查看错误码。
data	boolean	true or false
requestId	String	请求ID，用于跟踪日志。
costTime	String	请求消耗的时间。

{  
    "code": 200,
    "data": true
    "requestId": "af2d416202011101723237570050000",
    "costTime": "144ms"
}

加入直播房间

通过房间号和昵称加入直播房间。

若指定房间号的房间不存在则创建并加入，若房间存在则直接加入。

接口请求地址

POST {host}/v1/pkLive/join HTTP/1.1
Content-Type: application/json;charset=utf-8

请求参数

参数名称	类型	是否必选	描述
liveCid	String	是	多人房间号。
parentLiveCid	String	否	如果是 PK 直播，则需要指定原主播的直播房间号。
clientType	Integer	否	客户端类型。 0：UNKNOWN，1：TV，2：IOS，3：AOS，4：PC，5：MAC，6：WEB
liveType	Integer	是	直播类型是否为是否 PK 直播。 2表示普通单人直播；3 表示 PK 直播。

返回参数

参数名称	类型	描述
code	int	状态码。200 表示正常调用。其他错误码请查看错误码。
data	ArrayList	业务参数。
requestId	String	请求ID，用于跟踪日志。
costTime	String	请求消耗的时间。

data参数说明：

参数名称	类型	描述
avRoomCName	String	音视频房间的 channelName。
avRoomCid	String	音视频房间id。
avRoomUid	String	成员在音视频房间中用户id。
avRoomCheckSum	String	token，加入音视频房间用的鉴权。
createTime	int	房间的创建时间。
duration	int	房间已经持续的时间。
roomKey	String	appId 和 mpRoomId 加密后的key。
roomUniqueId	int	房间在数据库中的唯一id。
liveCid	String	直播号。
nrtcAppKey	String	NERTC 的 AppKey。

{
    "code": 200,
    "data": {
        "avRoomCName": "f98c9851*****",
        "avRoomCid": "432923009*****",
        "avRoomUid": 160500020*****,
        "avRoomCheckSum": "e8e61b8*****",
        "createTime": 1605000177,
        "duration": 26,
        "roomKey": "YWVzOjA*****",
        "roomUniqueId": 37732,
        "liveCid": "1234567*****",
        "nrtcAppKey": "f596afcb743e*****"
    },
    "requestId": "af2d41620*****",
    "costTime": "144ms"
}

随机获取直播间随机背景图

随机获取直播间的随机背景图片。

接口请求地址

POST {host}/v1/pkLive/liveRoom/getRandomLivePic 
HTTP/1.1
Content-Type: application/json;charset=utf-8

请求参数

无

返回参数

参数名称	类型	描述
code	int	状态码。200 表示正常调用。其他错误码请查看错误码。
data	String	随机背景图。
requestId	String	请求ID，用于跟踪日志。
costTime	String	请求消耗的时间。

{  
    "code": 200,
    "data": "[https://yx-we*](https://yx************.png)**",
    "requestId": "af2d41620201110***",
    "costTime": "144ms"
}

token刷新

刷新 accessToken 和 IMToken。

接口请求地址

POST {host}/auth/tokenRefresh   HTTP/1.1
Content-Type: application/json;charset=utf-8

请求参数

无

返回参数

参数名称	类型	描述
code	int	状态码。200 表示正常调用。其他错误码请查看错误码。
data	String	随机背景图。
requestId	String	请求ID，用于跟踪日志。
costTime	String	请求消耗的时间。

data参数说明：

参数名称	类型	描述
mobile	String	手机号。
accessToken	String	Demo 账号Token。
imAccid	String	IM 账号。
imToken	String	IM Token。
avatar	String	头像。
avRoomUid	String	uid。
nickname	String	昵称。
accountId	String	账号编号。

{
    "code": 200,
    "data": {
        "mobile": "1111",
        "accessToken": "1111",
        "imAccid": "1111",
        "imToken": "1111",
        "avatar": "1111",
        "avRoomUid": "1111",
        "nickname": "1111",
        "accountId": "1111"
    },
    "requestId": "af2d416202011101723237570050000",
    "costTime": "144ms"
}

在线咨询

微信咨询

电话咨询

此文档是否对你有帮助？

有帮助

去反馈

应用服务端与 App 的业务交互
主播端开播
观众端观看
主播邀请 PK
主播结束 PK
观众打赏
结束直播
应用服务端接口设计
请求结构
Header
Body
开启直播
接口请求地址
请求参数
返回参数
返回示例
结束直播
接口请求地址
请求参数
返回参数
返回示例
查询主播直播列表
接口请求地址
请求参数
返回参数
返回示例
发起直播 PK
接口请求地址
请求参数
返回参数
返回示例
获取直播房间中的主播信息
接口请求地址
请求参数
返回参数
返回示例
随机获取直播间主题
接口请求地址
请求参数
返回参数
返回示例
查询直播 PK 结果
接口请求地址
请求参数
返回参数
直播PK时段打赏主播贡献排行榜查询
接口请求地址
请求参数
返回参数
返回示例
直播时段打赏总榜 (在线成员)
接口请求地址
请求参数
返回参数
直播间打赏
接口请求地址
请求参数
返回参数
返回示例
主播结束PK
接口请求地址
请求参数
返回参数
加入直播房间
接口请求地址
请求参数
返回参数
随机获取直播间随机背景图
接口请求地址
请求参数
返回参数
token刷新
接口请求地址
请求参数
返回参数