====== 服务端集成 ====== ''本文档已不再维护。'' ------- 直播聊天室提供REST API形式的管理接口，下面是关于服务端直播聊天室的管理功能说明。 ===== 服务端介绍 ===== 环信直播聊天室是基于环信REST聊天室服务开发的针对直播场景的直播聊天室服务，直播聊天室服务端已开源，仓库链接：[[https://github.com/easemob/easemob-im-app-server|环信直播聊天室服务端]] 可将该服务部署到自己的服务器，进行直播聊天室的集成。环信服务器部署的“easemob-im-app-server”服务，使用的appkey为easemob-demo#chatdemoui，仅作为“直播聊天室demo”的服务端使用。 服务端接口请求都需要设置Request Headers: === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| token获取方式请参考：[[im:100serverintegration:20users|用户体系集成]] ==== 聊天室 ==== 即环信的聊天室功能，每一个直播聊天室，都唯一对应一个聊天室（反过来不成立）。 直播聊天室复用了对应聊天室的所有资源，包括聊天室的成员列表等。 强烈不建议调用解散聊天室接口。将直播聊天室对应的聊天室解散，这将导致该直播聊天室不可使用。 关于聊天室REST API，请参考[[im:server:basics:chatroom|聊天室管理]]。 ==== 直播聊天室 ==== 直播聊天室对聊天室进行了包装，复用了聊天室的所有数据，并增加了直播场景特有的属性，如直播聊天室封面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、用户进入一个未在直播的直播聊天室，并成功开始一场直播，则该用户成为该直播聊天室的主播。 ==== 主播 ==== 直播聊天室的主播，与该直播聊天室对应聊天室的群主是同一人。一个直播聊天室只能有一个主播。 ===== REST API介绍 ===== ==== 直播聊天室管理 ==== === 创建直播聊天室 === == 调用说明 == * 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" } ==== 管理员/禁言/黑名单/白名单 ==== 对直播聊天室的管理员、禁言、黑名单、白名单等操作，即为对该直播间对应的聊天室的相关操作，直接调用该聊天室的接口即可。 [[im:100serverintegration:70chatroommgmt|聊天室管理]] ---- 上一页：[[im:extensions:live:intro|产品介绍]] 下一页：[[im:extensions:live:android|Android客户端集成]]