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

增加房间流

更新时间:2022-09-30 16:44

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 返回码

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

返回码 说明 处理建议
123 设置流信息失败。 请重试,或联系 ZEGO 技术支持处理。
1012 多个用户操作同一个流。 请检查逻辑。