UPRTC

Rest API #

服务端Rest API，其他业务服务器调用接口，创建媒体房间等其他相关操作

说明与约定 #

  • 默认前缀/uprtc/api/v2，下面每个请求的地址都需要拼接前缀
  • Content-Type: application/json
  • 鉴权，在请求头中添加，key:authorization，value:key=AppSecret，AppSecret的值在开发者控制台项目信息中查看

应答 #

所有应答为以下格式，其中code为应答状态，message为错误信息，data为请求正确的应答内容，JSON字符串，下面接口说明不再赘述只会给出data的内容描述，未给出返回结果描述的表示data无内容。

{
    "code": 0,
    "data": {},
    "msg": ""
}

参数位置 #

  • 路径参数
    例如：/group/{groupId}/user/{userId}/notification/type/{notifyType}
axios({
  url:"/group/myGroupId/user/myUserId/notification/type/1"
})
  • URL参数
    例如：/group?&groupId=myGroupId&userId=myUserId&type=1
axios({
  url:"/group",
  params: {
    groupId: myGroupId,
    userId: myUserId,
    type: 1
  }
})
  • Body参数
    例如：/group
axios({
  url:"/group",
  data: {
    groupId: myGroupId,
    userId: userId,
    type: 1
  }
})

错误码 #

应答状态 描述
0 成功
10000 系统错误
10001 API认证错误
10002 无效参数
10003 无效请求
50000 非法客户端连接
50001 没有找到房间
50002 不能创建已存在的房间
50003 用户没有被邀请加入房间
50004 用户已经和房间建立连接
50005 无法建立RTC连接
50006 用户已经加入房间
50007 用户不具备消费某个流媒体的能力
50008 房间拥有者未加入房间
50009 用户不能在房间中生产某个流媒体
50010 没有找到被合并的房间
50011 用户不在房间里
50012 超过会话房间最大人数
50013 指定Work已经创建过此房间的镜像
50014 不能重复合并同一个房间
50015 没有可用的工作进程
50016 没有找到可操作的媒体，没有找到媒体生产者
50017 客户端没有找到路由
50018 超过授权的最大连接数
50019 下载的录像文件不存在
50020 房间正在录制
50021 没有找到可用的录制服务器
50022 房间不可以加入

常量 #

录制状态 #

录制状态 描述
0 未录制
1 准备录制
2 正在录制
3 录制结束
4 等待视频处理
5 正在视频处理
6 视频处理完成
7 录制错误

RTC连接协议 #

RTC连接协议 描述
0 UDP
1 TCP
2 UDP和TCP，优先UDP
3 TCP和UDP，优先TCP

房间 #

房间相关操作接口说明


创建多方会话房间 #

只有被邀请的用户才能进入房间，加入房间的用户默认可以生产媒体流。

POST /room/convo
参数名 参数类型 参数位置 必需 描述
masterId String Body 是 房间所有者ID
memberIds String[] Body 否 房间成员ID数组
maxMemberNum Integer Body 否 最大会话人数，默认按服务端配置，0为无限制
roomId String Body 否 房间ID，参照roomId详解
protocol Number Body 否 默认为0, 参照RTC连接协议
minBitrate Number Body 否 房间内单个用户最小比特率，默认为600000，60+kb/s
maxBitrate Number Body 否 房间内单个用户最大比特率，默认为3000000，300+kb/s

返回结果:

{
  "roomId": "N6QAwbs",                           // 房间ID，房间唯一标示
  "serverUrl": "wss://devel.uprtc.cmcim.com:6016/", // 客户端连接的URL
  "serverUrl6": "",                             // serverUrl的ipv6地址，如果配置了ipv6才会存在
  "serverAddress": "192.168.6.189:6017",        // 主机地址信息
  "serverAlias": "rtc-1:cluster-1",             // 主机别名  
  "invitationCode": 229937516   // 客户端可使用邀请码加入到房间，地址为 serverUrl + invitationCode
}

roomId参数详解

roomId由系统创建，不支持在系统外构建roomId，请不要把任意字符串作为roomId入参。创建直播房间接口roomId参数不再赘述。

  • 不设置roomId， 系统会自动生成roomId，并创建房间。
  • 设置roomId时
  1. 如果不存在此房间，直接使用roomId创建房间
  2. 如果房间存在，房主不是masterId时新生成roomId并创建房间，如果房主是masterId返回错误应答(表示房间重复被创建)
  3. roomId只能在创建它的服务上复用，如果roomId不属于此服务，则新生成roomId并创建房间

场景举例：

  1. 为主播A创建直播房间，第一次创建不传roomId，创建成功返回roomId，存储房间信息，第二次开播复用此roomId创建房间，可保持房间地址不变。
  2. 开发阶段，先创建一个房间记录下roomId，下次测试时可复用此roomId创建房间，避免每次创建房间都要对不同平台的客户端反复设置roomId。

添加会话成员 #

POST /room/{roomId}/convo/members
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID
memberIds String[] Body 是 被添加用户ID数组

房间中广播消息 #

POST /room/{roomId}/message
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID
* JSON Body 是 消息内容，自定义JSON格式数据

对指定peers发送消息 #

POST /room/{roomId}/peers/message/
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID
msg JSON Body 是 消息内容，自定义JSON格式数据
peers String[] Body 是 用户ID数组

删除/关闭指定房间 #

DELETE /room/{roomId}
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID

取得房间信息 #

GET /room/{roomId}
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID

返回结果:

{
  "roomId": "N6QAwbs",                // 房间ID
  "serverUrl": "wss://devel.uprtc.cmcim.com:6016/s1/c1/",   // 客户端连接地址
  "serverUrl6": "",                   // serverUrl的ipv6地址
  "serverAddress": "192.168.6.189:6017",   // 主机地址信息
  "serverAlias": "rtc-1:cluster-1",  // 主机别名
  "total": 0,                         // 总人数
  "masterId": "xxx",                  // 房间所有者ID
  "invitedUserIds": ["xxx", "xxx"],   // 被邀请的成员ID（会话房间）
  "memberIds": ["xxx", "xxx"],        // 房间所有成员ID，不包括观众
  "maxMemberNum" : 16,                // 最大会话人数（会话房间）
  "mergeRoomIds": [],                 // 合并房间的ID集合（直播房间）
  "mirrorServers": []                 // 房间镜像所在服务器别名集合 （直播房间）
}

房间是否存在 #

GET /room/{roomId}/exist
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID

返回结果:

{
  "exist": true    // 房间存在为true，不存在为false
}

设置房间是否可被加入 #

POST /room/{roomId}/join/enbale/{enable}
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID
enable Boolean 路径 是 是否可加入

从房间中移除用户 #

DELETE /room/{roomId}/peer/{peerId}
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID
peerId String 路径 是 用户ID

取得房间中的peer #

GET /room/{roomId}/peer/{peerId}
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID
peerId String 路径 是 用户ID

返回结果:

{
  "joined": true    // true在房间中，false不在房间中
}

创建直播房间 #

POST /room/live
参数名 参数类型 参数位置 必需 描述
masterId String Body 是 主播用户ID
roomId String Body 否 房间ID，参照roomId详解
protocol Number Body 否 默认为0, 参照RTC连接协议
minBitrate Number Body 否 房间内单个用户最小比特率，默认为600000，60+kb/s
maxBitrate Number Body 否 房间内单个用户最大比特率，默认为3000000，300+kb/s

返回结果:

{
  "roomId": "N6QAwbs",                          // 房间ID，房间唯一标示
  "serverUrl": "wss://devel.uprtc.cmcim.com:6016/", // 客户端连接的URL
  "serverUrl6": "",                             // serverUrl的ipv6地址，如配置了ipv6才会存在
  "serverAddress": "192.168.6.189:6017",       // 主机地址信息
  "serverAlias": "rtc-1:cluster-1"             // 主机别名
}

手动为直播房间在指定服务器上创建镜像房间 #

镜像房间是直播房间在其他服务器上的slave room，当前系统压力过大时会自动在其他服务器创建镜像房间用来负载。当有特殊业务场景需要时开发者也可调用此接口手动创建镜像房间。同一个服务器只能指定直播房间创建一个镜像房间。

POST /room/{roomId}/live/mirror
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID
serverAlias String Body 是 指定镜像房间服务器
pid Integer Body 否 指定镜像房间服务器的work进程，默认取负载最小的

取得直播房间所有镜像房间所在的服务器 #

GET /room/{roomId}/live/mirrors
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID

返回结果:

[
  {
    "name": "",
    "serverUrl": "wss://devel.urtc.cmcim.com:6020/s2/c1/",
    "serverUrl6": "",
    "serverAddress": "192.168.6.99:6017",
    "serverAlias": "rtc-2:cluster-1"
  },
  {
    "name": "",
    "serverUrl": "wss://devel.urtc.cmcim.com:6020/s3/c1/",
    "serverUrl6": "",
    "serverAddress": "192.168.6.100:6017",
    "serverAlias": "rtc-3:cluster-1"
  },

  ....
]

添加连麦成员 #

添加观众用户为直播成员，此用户可以生产流媒体

POST /room/{roomId}/live/member
参数名 参数类型 参数位置 必需 描述
peerId String Body 是 观众用户ID
kind String Body 否 可生产流媒体类型，audio或video，默认audio，为video时也生产audio
maxBitrate Number Body 否 连麦用户最大比特率，默认为3000000，300+kb/s

取得所有连麦成员 #

GET /room/{roomId}/live/members
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID

返回结果:

[
  "liubei", "guanyu", "zhangfei", ....
]

移除连麦成员 #

DELETE /room/{roomId}/live/member/{peerId}
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID
peerId String 路径 是 用户ID

连接直播间 #

主播连线/互动/PK，连接两个直播间

POST /room/{roomId}/live/merge
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 直播房间ID
roomId String Body 是 被合并的直播房间ID

连接直播间说明

  • 假如路径参数的roomId为房间A，Body参数的roomId为房间B，意思是连接A,B两个房间的媒体流，A,B的观众客户端能接收它们媒体流，也就是能看到2个主播在互动。构建请求URL时要注意房间A是请求的操作对象。
  • 当房间A又连接房间C，那么A,B,C的观众都能接收到它们的媒体流，也就是能看到3个主播在互动。
  • 当房间B又连接房间D（不考虑真实业务场景房间B是否有权限这么做），那么A,B,C,D的观众都能接收到它们的媒体流，也就是能看到4个主播在互动。实际应用时建议由一个房间发起连接这样更好维护。
  • 当房间A分离房间B时，B的观众只能看到B，其他A,C,D观众看到剩余的3个主播在互动。
  • 房间连接可跨服务器，跨集群
  • 只对直播房间有效

取得和指定房间连接的所有房间信息 #

GET /room/{roomId}/live/merge
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID

返回结果:

[
  {
    "roomId": "N6QAwbs",                  // 连接的房间ID
    "serverAlias": "rtc-1:cluster-1",     // 房间所在服务器别名
    "serverAddress": "192.168.6.189:6017" // 房间所在服务器地址
  },
  ......
]

分离直播间（主动分离） #

主播主动离开连线

POST /room/{roomId}/live/master/:peerId/separate
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID
peerId String 路径 是 主播(用户)ID

分离直播间（被动分离） #

由其他连线主播分离，例如在多个连线主播中，在业务上存在管理员，那么管理员分开某个直播间可调用此方法

POST /room/{roomId}/live/separate
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID
roomId String Body 是 被合并的房间ID

暂停/恢复合并直播间指定媒体 #

直播间连接后，主播可以暂停/恢复另外主播的媒体，比如不听对方语音。

POST /room/{roomId}/live/{action}/mergeTrack/{trackId}
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID
action String 路径 是 pause 或 resume
trackId String 路径 是 Peer媒体Track ID

取得房间录制状态 #

服务端录制状态，不包含客户端录制状态

GET /room/{roomId}/record/status
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID

返回结果:
录制状态参照

{
  "status": 0
}


录制 #

取得一个可用的录制服务器 #

GET /record/server

返回结果:

{
  "name": "",                       // 服务名
  "serverAlias": "rtc-1:cluster-1", // 服务器别名
  "serverAddress": "192.168.6.189:6017", // 服务器地址 
  "serverUrl": "wss://devel.uprtc.cmcim.com:6016/" // 客户端访问URL
}

创建录制、开始录制 #

POST /record/start
参数名 参数类型 参数位置 必需 描述
roomId String Body 是 房间ID
serverAlias String Body 否 指定录制服务器别名
all Boolean Body 否 是否录制房间里所有人，默认false
peers Array Body 否 指定录制用户ID数组，直播房间默认录制主播
resolution String Body 否 录制分辨率，1080p, 720p, 480p，默认720p
layout String Body 否 视频整合布局，默认为grid，设置为用户ID时，此ID视频内容会放在C位
fixVideoDirection Boolean Body 否 是否调整视频角度(手机视频会有90度旋转问题)，默认false

返回结果:

{
  "recordId": "GznMWUT",  // 录像唯一标示
  "serverAlias": "rtc-2:cluster-1", // 录制服务器别名(唯一)
  "serverAddress": "192.168.6.99:6017" // 录制服务器地址
}

停止录制 #

POST /record/stop/{roomId}
参数名 参数类型 参数位置 必需 描述
roomId String 路径 是 房间ID

取得录制状态 #

需要对录制服务器发起请求，注意不是房间所在服务器。 一个房间同时只能有一个录制，录制结束后，还可以再次录制，也就是说房间可能存在多段录像。这里是查询某个录制的状态。房间当前的录制状态参照这里。

GET /record/{recordId}/status

返回结果:
录制状态参照

{
  "status": 0
}

创建回放房间 #

回放房间是直播间

POST /record/playback
参数名 参数类型 参数位置 必需 描述
recordId String Body 是 录制唯一标示
serverAlias String Body 是 录像所在服务器别名
startTime Number Body 否 开始直播的时间戳，默认创建即开始
loopPlay Boolean Body 否 是否循环播放，默认false
endTime Number Body 否 结束直播的时间，loopPlay为true时必须赋值
protocol Number Body 否 默认为0, 参照RTC连接协议
minBitrate Number Body 否 房间内单个用户最小比特率，默认为600000，60+kb/s
maxBitrate Number Body 否 房间内单个用户最大比特率，默认为3000000，300+kb/s

返回结果:

{
  "roomId": "N6QAwbs",                           // 房间ID，房间唯一标示
  "serverUrl": "wss://devel.uprtc.cmcim.com:6016/", // 客户端连接的URL
  "serverAddress": "192.168.6.189:6017",        // 主机地址信息
  "serverAlias": "rtc-1:cluster-1",             // 主机别名  
}

创建客户端录制上传URL #

POST /record/client/upload

返回结果:

{
  "recordId": "AWZRoUT", // 录制唯一标示
  "serverUrl": "wss://devel.urtc.cmcim.com:6020/s1/c1/record?recordId=AWZRoUT", // 客户端上传URL
  "serverAlias": "rtc-1:cluster-1", // 录制服务器别名
  "serverAddress": "192.168.6.189:6017" // 录制服务器地址
}

下载录像文件 #

GET /record/download/{recordId}

上传录像文件 #

ffmpeg支持的格式即可，例如mp4,webm等

POST /record/upload
参数名 参数类型 参数位置 必需 描述
file File Form-Data 是 视频文件

返回结果:

{
  "recordId": "AWZRoUT", // 录制唯一标示
  "serverAlias": "rtc-1:cluster-1", // 录制服务器别名
  "serverAddress": "192.168.6.189:6017" // 录制服务器地址
}


服务 #

取得最小负载服务 #

GET /server/miniLoad

返回结果:

{
  "name": "",                       // 服务名
  "serverAlias": "rtc-1:cluster-1", // 服务器别名
  "serverAddress": "192.168.6.189:6017", // 服务器地址 
  "serverUrl": "wss://devel.uprtc.cmcim.com:6016/" // 客户端访问URL
}

取得服务器房间数 #

GET /server/room/num

返回结果:

{
  "num": 100 // 服务器中房间数
}

取得服务器工作进程负载 #

GET /server/cpu/load

返回结果:

// workPid工作进程，cpu使用百分比
[
  { "workPid": 32412, "cpu": 10 },
  { "workPid": 32413, "cpu": 20 },
  ... ...
]

回收服务器 #

被回收的服务器不再参与负载，当所有room都结束后，可以关闭服务器

POST /server/recycle

删除用户 #

被删除的用户不再被计算到用户总数，但也不能再访问系统。如果购买的无用户限制版本可忽略此接口。

DELETE /server/block/peer/:peerId
参数名 参数类型 参数位置 必需 描述
peerId String 路径 是 用户唯一标识

上次更新: 4/16/2024, 6:10:46 PM

共通