服务端 API v2
  • API概览
  • 快速开始
  • 调用方式
  • 房间信令接口
  • 混流接口
  • 媒体服务接口
  • 媒体文件接口
  • 音视频流审核接口
  • 回调说明
  • 全局返回码
  • 使用 Postman 调试

增加房间流

更新时间:2022-03-28 14:08

1 描述

调用本接口可向指定房间增加一路流。多用于“一起看”场景,比如将 CDN 的直播流添加到指定房间,从而让房间内的用户获取流 ID,实现服务端控制指定房间的直播内容。

  1. 往指定房间增加流时需要保证该房间是存在的,本接口无法创建房间。
  2. 本接口一般与 删除房间流 配合使用,比如业务上需要停止向某个房间广播流。

本接口仅用于抛出房间内流增加的相关通知,不会执行实际的推流操作。开发者需要从自己的客户端,调用 startPublishingStream 接口进行推流(或其它的推流方式),该条被增加的流才能被 startPlayingStream 接口拉流到。

客户端接收房间内流增加的通知使用 ZEGO SDK 回调接口:

ZegoExpress SDK LiveRoom SDK
iOS/macOS onRoomStreamUpdate onStreamUpdated
Android onRoomStreamUpdate onStreamUpdated
Windows onRoomStreamUpdate OnStreamUpdated
Web roomStreamUpdate onStreamUpdated

2 接口原型

  • 请求方法:GET
  • 请求地址:https://rtc-api.zego.im/?Action=AddStream
  • 传输协议:HTTPS
  • 调用频率限制(同一个 AppID 下所有房间):10 次/秒(测试环境:1 次/秒)

3 请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表请参考 调用方式 - 公共请求参数

参数 类型 是否必选 描述
RoomId
String
房间 ID。
UserId
String
用户 ID。
UserName
String
用户名。
StreamId
String
流 ID。
StreamTitle
String
流标题,不超过 127 字节。

使用时,请对该参数内容进行 UrlEncode。

ExtraInfo
String
流附加信息,不超过 1024 字节。

调用本服务端接口时:

  • 不建议使用与房间内实际用户相同的 UserId,避免与客户端 SDK 的流新增行为产生冲突。可以使用特定的名称标识为服务端行为,例如:userId = “Server-Administrator”。
  • 如果使用了与房间内实际用户相同的 UserId(不建议)时,需要注意以下事项:
    • 相应操作人 UserId 的客户端不会收到本服务端接口触发的流增加回调。
    • 如果实际房间内用户 UserId 没有推流,会触发相应 StreamId 的流删除逻辑。
    • 如果实际房间内用户 UserId 退出房间,会触发相应 StreamId 的流删除逻辑。

4 请求示例

https://rtc-api.zego.im/?Action=AddStream
&RoomId=123
&UserId=2323
&UserName=df
&StreamId=852
&StreamTitle=%E6%B5%81%E6%A0%87%E9%A2%98&ExtraInfo=%E9%99%84%E5%8A%A0%E4%BF%A1%E6%81%AF
&<公共请求参数>

5 响应参数

参数 类型 描述
Code
Number
返回码。
Message
String
操作结果描述。
RequestId
String
请求 ID。

6 响应示例

{
    "Code":0,
    "Message":"success",
    "RequestId":"4443515903608307334"
}

7 返回码

以下仅列出了接口业务逻辑相关的返回码,完整返回码请参考 全局返回码

返回码 说明 处理建议
104 房间不存在,与 5024、50001 内部判断逻辑相同。 请确认请求房间 RoomId 是否存在。
206 App 请求 QPS 过高被限制。 降低请求频率,或联系 ZEGO 技术支持提高 QPS 限制阈值。
5018 房间状态不一致。 请稍后重试。
5024 房间不存在,与 104、50001 内部判断逻辑相同。 请确认请求房间 RoomId 是否存在。
50001 房间不存在,与 104、5024 内部判断逻辑相同。
  • 当房间内没有用户时,房间会被服务端自动销毁。
  • 当房间内只有一个用户时,该用户退出房间或被踢出房间,房间会被服务端自动销毁。
  • 当用户心跳请求超时 100 秒后,用户会掉线;所有用户都不在房间后,房间会被服务端自动销毁。
请确认请求房间 RoomId 是否存在。
50002 用户账号不存在。 请确认请求用户 UserId 是否在线。
50003 查找用户在线信息失败。 请确认请求用户 UserId 是否在线。
50004 读取用户信息失败。 请确认请求用户 UserId 是否在线。
50009 审核失败。 请稍后重试,或 ZEGO 联系技术支持。
50011 推送自定义消息目的用户个数超过限制。 请检查请求包中的用户个数是否超过限制。
50012 推送自定义消息长度超过限制。 请检查消息长度是否超过限制。
50013 发送自定义消息失败。 请联系 ZEGO 技术支持处理。