服务端集成

直播聊天室提供REST API形式的管理接口,下面是关于服务端直播聊天室的管理功能说明。

环信直播聊天室是基于环信REST聊天室服务开发的针对直播场景的直播聊天室服务,直播聊天室服务端已开源,仓库链接:环信直播聊天室服务端

可将该服务部署到自己的服务器,进行直播聊天室的集成。环信服务器部署的“easemob-im-app-server”服务,使用的appkey为easemob-demo#chatdemoui,仅作为“直播聊天室demo”的服务端使用。

服务端接口请求都需要设置Request Headers:

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

token获取方式请参考:用户体系集成

聊天室

即环信的聊天室功能,每一个直播聊天室,都唯一对应一个聊天室(反过来不成立)。 直播聊天室复用了对应聊天室的所有资源,包括聊天室的成员列表等。

强烈不建议调用解散聊天室接口。将直播聊天室对应的聊天室解散,这将导致该直播聊天室不可使用。

关于聊天室REST API,请参考聊天室管理

直播聊天室

直播聊天室对聊天室进行了包装,复用了聊天室的所有数据,并增加了直播场景特有的属性,如直播聊天室封面URL、直播状态、场次ID等,具体如下:

属性名称类型描述
id String 直播聊天室ID,即对应的聊天室 ID,聊天室唯一标识符,创建直播间时由环信服务器生成返回。
name String 直播聊天室名称,即对应的聊天室名称,任意字符串。
description String 直播聊天室描述,即对应的聊天室描述,任意字符串。
maxusers Integer 直播聊天室成员上限,即对应的聊天室成员上限,创建聊天室的时候设置,可修改。
affiliations_count Integer 现有成员总数。因聊天室成员离线2分钟自动离开聊天室,故也可认为当前在线人数。
owner String 直播聊天室主播的username,也是对应聊天室的所有者。例如:{“owner”: “13800138001”}。
cover String 直播聊天室封面Url。
status String 直播状态,未直播:offline,直播中:ongoing
showid String 当前直播场次ID,初始值为0,每开始一场直播,场次ID自增1。
ext Map 直播聊天室自定义属性
affiliations Array 现有成员列表,包含了 owner 和 member。例如: “affiliations”:[{“owner”: “13800138001”},{“member”:”v3y0kf9arx”},{“member”:”xc6xrnbzci”}]。

直播场次

直播聊天室是以直播场次为基本单位的。每开始一场新的直播,直播聊天室详情中的场次ID会自增1。可以基于该场次ID记录每场直播的统计信息。

直播聊天室的直播状态:ongoing:正在直播中;offline:未直播。

限制条件:

1、每开始一场直播,直播间的当前状态必须是offline,或者当前直播聊天室主播已离线(该策略主要是为了避免,当主播未正确关闭直播聊天室的直播状态,导致直播聊天室无法被其他主播使用)。如当前状态是ongoing,且当前主播在线,则不允许重新开始一场直播。

2、用户进入一个未在直播的直播聊天室,并成功开始一场直播,则该用户成为该直播聊天室的主播。

主播

直播聊天室的主播,与该直播聊天室对应聊天室的群主是同一人。一个直播聊天室只能有一个主播。

直播聊天室管理

创建直播聊天室

调用说明
  • HTTP Method: POST
  • Path: /appserver/liverooms
权限要求

app管理员

请求字段说明
属性名称类型是否必选描述
name String 直播聊天室名称,即对应的聊天室名称,任意字符串。
description String 直播聊天室描述,即对应的聊天室描述,任意字符串。
maxusers Integer 直播聊天室成员上限,即对应的聊天室成员上限,创建聊天室的时候设置,可修改。
owner String 直播聊天室主播的username,也是对应聊天室的所有者。例如:{“owner”: “13800138001”}。
members Array 直播间成员,此属性为可选的,但是如果加了此项,数组元素至少一个
cover String 直播聊天室封面Url。
ext Map 直播聊天室自定义属性
API示例

请求:

curl -X POST http://localhost:8080/appserver/liverooms -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8_bc0eAAAAAAAA' -H 'Content-Type: application/json' -d '{"name":"test1","description":"server create chatroom","maxusers":300,"owner":"hxtest1","cover":"http://172.0.0.1:8080/cover/pictiure"}'

响应:

{
    "id": "107776865009665",
    "name": "test1",
    "description": "server create chatroom",
    "owner": "hxtest1",
    "created": 1582182428511,
    "mute": false,
    "cover": "http://172.0.0.1:8080/cover/pictiure",
    "status": "offline",
    "showid": 0,
    "maxusers": 300,
    "affiliations_count": 1,
    "affiliations": [
        {
            "owner": "hxtest1"
        }
    ]
}

获取直播聊天室详情

调用说明
  • HTTP Method: GET
  • Path: /appserver/liverooms/{liveroomid}
权限要求

app user

API示例

请求:

curl -X GET http://localhost:8080/appserver/liverooms/107776865009665 -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8_bc0eAAAAAAAA' -H 'Content-Type: application/json'

响应:

{
    "id": "107776865009665",
    "name": "test1",
    "description": "server create chatroom",
    "owner": "hxtest1",
    "created": 1582182428511,
    "mute": false,
    "cover": "http://172.0.0.1:8080/cover/pictiure",
    "status": "offline",
    "showid": 0,
    "maxusers": 300,
    "affiliations_count": 1,
    "affiliations": [
        {
            "owner": "hxtest1"
        }
    ]
}

修改直播聊天室

调用说明
  • HTTP Method: PUT
  • Path: /appserver/liverooms/{liveroomId}
权限要求

app管理员,当前直播聊天室的主播

可修改字段说明
属性名称类型描述
name String 直播聊天室名称,即对应的聊天室名称,任意字符串。
description String 直播聊天室描述,即对应的聊天室描述,任意字符串。
maxusers Integer 直播聊天室成员上限,即对应的聊天室成员上限。
cover String 直播聊天室封面Url。
ext Map 直播聊天室自定义属性
API示例

请求:

curl -X PUT http://localhost:8080/appserver/liverooms/107776865009665 -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8_bc0eAAAAAAAA' -H 'Content-Type: application/json' -d '{"name":"test1","maxusers":1000,"owner":"hxtest1","cover":"http://172.0.0.1:8080/cover"}'

响应:

{
    "id": "108144876388353",
    "name": "test1",
    "description": "nothing left here",
    "owner": "hxtest1",
    "created": 1582533391279,
    "cover": "http://177.0.0.1:8080/cover",
    "status": "offline",
    "showid": 0,
    "affiliations_count": 1
}

分页获取直播聊天室列表

调用说明
  • HTTP Method: GET
  • Path: /appserver/liverooms
权限要求

app user

接口参数
属性名称类型描述
limit int 不设置该参数则默认为10,可选项。
cursor String 分页返回的游标,可获取下一页数据。获取第一页则不设置。
API示例

请求:

curl -X GET http://localhost:8080/appserver/liverooms?limit=2&cursor=107776865009666 -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8_bc0eAAAAAAAA' -H 'Content-Type: application/json'

响应:

{
    "entities": [
        {
            "id": "107741231251457",
            "name": "test1",
            "owner": "hxtest1",
            "status": "ongoing",
            "showid": 1,
            "affiliations_count": 1
        },
        {
            "id": "107776865009665",
            "name": "test1",
            "owner": "hxtest1",
            "cover": "http://177.0.0.1:8080/cover/pictiure",
            "status": "offline",
            "showid": 0,
            "affiliations_count": 1
        }
    ],
    "count": 2,
    "cursor": "107777290731521"
}

分页获取正在直播的直播聊天室列表

调用说明
  • HTTP Method: GET
  • Path: /appserver/liverooms/ongoing
权限要求

app user

接口参数
属性名称类型描述
limit int 不设置该参数则默认为10,可选项。
cursor String 分页返回的游标,可获取下一页数据。获取第一页则不设置。
API示例

请求:

curl -X GET http://localhost:8080/appserver/liverooms/ongoing?limit=2&cursor=107776865009666 -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8_bc0eAAAAAAAA' -H 'Content-Type: application/json'

响应:

{
    "entities": [
        {
            "id": "107741231251457",
            "name": "test1",
            "owner": "hxtest1",
            "status": "ongoing",
            "showid": 1,
            "affiliations_count": 1
        },
        {
            "id": "107776865009665",
            "name": "test1",
            "owner": "hxtest1",
            "cover": "http://177.0.0.1:8080/cover/pictiure",
            "status": "ongoing",
            "showid": 1,
            "affiliations_count": 1
        }
    ],
    "count": 2,
    "cursor": "107777290731521"
}

开始直播

调用说明
  • HTTP Method: POST
  • Path: /appserver/liverooms/{liveroomId}/users/{username}/ongoing
接口说明

开启直播。开始直播的前提:1、直播聊天室当前状态是未直播的状态;2、直播聊天室当前状态是正在直播,但主播离线,此时其他用户可进入直播间进行直播。否则返回403错误码。

权限要求

app user

API示例

请求:

curl -X POST http://localhost:8081/appserver/liverooms/107780133421057/users/hxtest1/ongoing -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8' -H 'Content-Type: application/json'

响应:

{
    "id": "107780133421057",
    "name": "test1",
    "description": "server create chatroom",
    "owner": "hxtest1",
    "created": 1582185545093,
    "mute": false,
    "cover": "http://172.0.0.1:8080/cover/pictiure",
    "status": "ongoing",
    "showid": 4,
    "maxusers": 300,
    "affiliations_count": 1,
    "affiliations": [
        {
            "owner": "hxtest1"
        }
    ]
}

结束直播

调用说明
  • HTTP Method: POST
  • Path: /appserver/liverooms/{liveroomId}/users/{username}/offline
接口说明

结束直播。结束直播条件:需要是直播聊天室主播,且直播聊天室当前直播状态是正在直播,可结束直播。否则返回403错误码。

权限要求

直播聊天室主播

API示例

请求:

curl -X POST http://localhost:8081/appserver/liverooms/107780133421057/users/hxtest1/offline -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8' -H 'Content-Type: application/json'

响应:

{
    "id": "107780133421057",
    "name": "test1",
    "owner": "hxtest1",
    "cover": "http://177.0.0.1:8080/cover/pictiure",
    "status": "offline",
    "showid": 4,
    "affiliations_count": 1
}

删除直播聊天室

调用说明
  • HTTP Method: DELETE
  • Path: /appserver/liverooms/{liveroomId}
权限要求

直播聊天室主播

API示例

请求:

curl -X DELETE http://localhost:8081/appserver/liverooms/107780133421057 -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8' -H 'Content-Type: application/json'

响应:

{
    "id": "107780133421057",
    "name": "test1",
    "description": "server create chatroom",
    "owner": "hxtest1",
    "created": 1583320857682,
    "cover": "http://172.0.0.1:8080/cover/pictiure",
    "status": "offline",
    "showid": 0,
    "affiliations_count": 1
}

转让直播聊天室

调用说明
  • HTTP Method: PUT
  • Path: /appserver/liverooms/{liveroomId}/owner/{newOwner}
权限要求

直播聊天室主播

API示例

请求:

curl -X PUT http://localhost:8081/appserver/liverooms/107780133421057/owner/hxtest2 -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8' -H 'Content-Type: application/json'

响应:

{
    "id": "107780133421057",
    "name": "test1",
    "description": "server create chatroom",
    "owner": "hxtest2",
    "created": 1583320900413,
    "cover": "http://172.0.0.1:8080/cover/pictiure",
    "status": "offline",
    "showid": 0,
    "affiliations_count": 1
}

推拉流管理

获取推流地址

调用说明
  • HTTP Method: GET
  • Path: /appserver/streams/url/publish
权限要求

app用户

请求参数说明
属性名称类型是否必选描述
domain String 推流域名,未设置则取服务中的默认值
hub String 直播空间名,未设置则取服务中的默认值
streamKey String 流名
expire Integer 获取推流url过期时间,单位为秒,默认600秒后过期
API示例

请求:

curl -X GET 'http://localhost:8080/appserver/streams/url/publish?domain=pili-publish.shenchong.com&hub=shenchong-liveroom&streamKey=hxtest1' -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8' -H 'Content-Type: application/json'

响应:

{
    "data": "rtmp://pili-publish.shenchong.com/shenchong-liveroom/hxtest1?e=1589261045&token=xxx:CSErrjZukoIVxBuwlTT0LWcwVF8="
}

获取直播流播放地址

调用说明
  • HTTP Method: GET
  • Path: /appserver/streams/url/play
权限要求

app用户

请求参数说明
属性名称类型是否必选描述
domain String 播放域名,未设置则取服务中的默认值
hub String 直播空间名,未设置则取服务中的默认值
streamKey String 流名
protocol String 播放协议,默认为rtmp;可选的三个值为:rtmp,hls,hdl
API示例

请求:

curl -X GET 'http://localhost:8080/appserver/streams/url/play?domain=pili-publish.shenchong.com&hub=shenchong-liveroom&streamKey=hxtest1' -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8' -H 'Content-Type: application/json'

响应:

{
    "data": "rtmp://pili-publish.shenchong.com/shenchong-liveroom/hxtest1"
}

管理员/禁言/黑名单/白名单

对直播聊天室的管理员、禁言、黑名单、白名单等操作,即为对该直播间对应的聊天室的相关操作,直接调用该聊天室的接口即可。 聊天室管理


上一页:产品介绍