API 参考
1. 概述
Qiniu RTC Server API 为七牛实时音视频云提供权限验证和房间管理功能,API 均采用 REST 接口。
2. HTTP请求鉴权
Qiniu RTC Server API 通过 Qiniu Authorization 方式进行鉴权,每个房间管理 HTTP 请求头部需增加一个 Authorization 字段:
Authorization: "<QiniuToken>"
QiniuToken: 管理凭证,用于鉴权。
使用七牛颁发的AccessKey
和SecretKey
,对本次 http 请求的信息进行签名,生成管理凭证。签名的原始数据包括http请求的 Method
, Path
, RawQuery
, Content-Type
及 Body
等信息,这些信息的获取方法取决于具体所用的编程语言,建议参照七牛提供的 SDK 代码。
计算过程及伪代码如下:
// 1.构造待签名的 Data
// 添加 Method 和 Path
data = "<Method> <Path>"
// 添加 Query,如果Query不存在或者为空,则跳过此步
if "<RawQuery>" != "" {
data += "?<RawQuery>"
}
// 添加 Host
data += "\nHost: <Host>"
// 添加 Content-Type,如果Content-Type不存在或者为空,则跳过此步
if "<Content-Type>" != "" {
data += "\nContent-Type: <Content-Type>"
}
// 添加回车
data += "\n\n"
// 添加 Body, 如果Content-Length, Content-Type和Body任意一个不存在或者为空,则跳过此步;如果Content-Type为application/octet-stream,也跳过此步
bodyOK := "<Content-Length>" != "" && "<Body>" != ""
contentTypeOK := "<Content-Type>" != "" && "<Content-Type>" != "application/octet-stream"
if bodyOK && contentTypeOK {
data += "<Body>"
}
// 2. 计算 HMAC-SHA1 签名,并对签名结果做 URL 安全的 Base64 编码
sign = hmac_sha1(data, "Your_Secret_Key")
encodedSign = urlsafe_base64_encode(sign)
// 3. 将 Qiniu 标识与 AccessKey、encodedSign 拼接得到管理凭证
<QiniuToken> = "Qiniu " + "Your_Access_Key" + ":" + encodedSign
3. app 操作接口
app 是客户在七牛实时音视频云的业务配置集合。一个 app 帐号下的连麦房间(频道)拥有独立的命名空间,并且这些房间的可配置功能选项遵从 app 的配置,例如人数限制、是否允许抢流、合流、旁路直播等。一个客户允许创建多个不同的 app ,以实现不同的配置需求;不同 app 下面所属的同名房间并不互通。
3.1 CreateApp
Host rtc.qiniuapi.com
POST /v3/apps
Authorization: qiniu mac
Content-Type: application/json
{
"hub": "<Hub>",
"title": "<Title>",
"maxUsers": <MaxUsers>,
"noAutoKickUser": <NoAutoKickUser>
}
Hub: 绑定的直播 hub,可选,使用此 hub 的资源进行推流等业务功能,hub 与 app 必须属于同一个七牛账户。
Title: app 的名称,可选,注意,Title 不是唯一标识,重复 create 动作将生成多个 app。
MaxUsers: int 类型,可选,连麦房间支持的最大在线人数。
NoAutoKickUser: bool 类型,可选,禁止自动踢人(抢流)。默认为 false ,即同一个身份的 client (app/room/user) ,新的连麦请求可以成功,旧连接被关闭。
200 OK
{
"appId": "<AppID>",
"hub": "<Hub>",
"title": "<Title>",
"maxUsers": <MaxUsers>,
"noAutoKickUser": <NoAutoKickUser>,
"createdAt": <CreatedAt>,
"updatedAt": <UpdatedAt>
}
616
{
"error": "hub not match"
}
AppID: app 的唯一标识。
Hub: 绑定的直播 hub,使用此 hub 的资源进行推流等业务功能,hub 与 app 必须属于同一个七牛账户。
Title: app 的名称,注意,Title不是唯一标识。
MaxUsers: int 类型,连麦房间支持的最大在线人数。
NoAutoKickUser: bool 类型,禁止自动踢人。
CreatedAt: time 类型,app 创建的时间。
UpdatedAt: time 类型,app 更新的时间。
3.2 GetApp
Host rtc.qiniuapi.com
GET /v3/apps/<AppID>
Authorization: qiniu mac
AppID: app 的唯一标识,创建的时候由系统生成。
200 OK
{
"appId": "<AppID>",
"hub": "<Hub>",
"title": "<Title>",
"maxUsers": <MaxUsers>,
"noAutoKickUser": <NoAutoKickUser>,
"mergePublishRtmp": {
"enable": <Enable>,
"audioOnly": <AudioOnly>,
"height": <OutputHeight>,
"width": <OutputHeight>,
"fps": <OutputFps>,
"kbps": <OutputKbps>,
"url": "<URL>",
"streamTitle": "<StreamTitle>"
},
"createdAt": <CreatedAt>,
"updatedAt": <UpdatedAt>
}
612
{
"error": "app not found"
}
AppID: app 的唯一标识。
UID: 客户的七牛帐号。
Hub: 绑定的直播 hub,使用此 hub 的资源进行推流等业务功能,hub 与 app 必须属于同一个七牛账户。
Title: app 的名称,注意,Title不是唯一标识。
MaxUsers: int 类型,连麦房间支持的最大在线人数。
NoAutoKickUser: bool 类型,禁止自动踢人。
MergePublishRtmp: 连麦合流转推 RTMP 的配置。
CreatedAt: time 类型,app 创建的时间。
UpdatedAt: time 类型,app 更新的时间。
3.3 DeleteApp
Host rtc.qiniuapi.com
DELETE /v3/apps/<AppID>
Authorization: qiniu mac
AppID: app 的唯一标识,创建的时候由系统生成。
200 OK
612
{
"error": "app not found"
}
3.4 UpdateApp
Host rtc.qiniuapi.com
Post /v3/apps/<AppID>
Authorization: qiniu mac
{
"hub": "<Hub>",
"title": "<Title>",
"maxUsers": <MaxUsers>,
"noAutoKickUser": <NoAutoKickUser>,
"mergePublishRtmp": {
"enable": <Enable>,
"audioOnly": <AudioOnly>,
"height": <OutputHeight>,
"width": <OutputHeight>,
"fps": <OutputFps>,
"kbps": <OutputKbps>,
"url": "<URL>",
"streamTitle": "<StreamTitle>"
}
}
AppID: app 的唯一标识,创建的时候由系统生成。
Title: app 的名称, 可选。
Hub: 绑定的直播 hub,可选,用于合流后 rtmp 推流。
MaxUsers: int 类型,可选,连麦房间支持的最大在线人数。
NoAutoKickUser: bool 类型,可选,禁止自动踢人。
MergePublishRtmp: 连麦合流转推 RTMP 的配置,可选择。其详细配置包括如下
- Enable: 布尔类型,用于开启和关闭所有房间的合流功能。
- AudioOnly: 布尔类型,可选,指定是否只合成音频。
- Height, Width: int64,可选,指定合流输出的高和宽,默认为 640 x 480。
- OutputFps: int64,可选,指定合流输出的帧率,默认为 25 fps 。
- OutputKbps: int64,可选,指定合流输出的码率,默认为 1000 。
- URL: 合流后转推旁路直播的地址,可选,支持魔法变量配置按照连麦房间号生成不同的推流地址。如果是转推到七牛直播云,不建议配置。
- StreamTitle: 转推七牛直播云的流名,可选,支持魔法变量配置按照连麦房间号生成不同的流名。例如,配置 Hub 为
qn-zhibo
,配置 StreamTitle 为$(roomName)
,则房间 meeting-001 的合流将会被转推到 rtmp://pili-publish.qn-zhibo.***.com/qn-zhibo/meeting-001地址。详细配置细则,请参考 www.portal.com 配置页面,或咨询七牛技术支持。
备注:以上关于合流画面的配置项仅用于配置合流的输出效果,对某一个特定输入的画面的配置(例如位置、大小、层级等),请参考相关客户端 sdk 说明文档。
200 OK
{
"appId": "<AppID>",
"hub": "<Hub>",
"title": "<Title>",
"maxUsers": <MaxUsers>,
"noAutoKickUser": <NoAutoKickUser>,
"mergePublishRtmp": {
"enable": <Enable>,
"audioOnly": <AudioOnly>,
"height": <OutputHeight>,
"width": <OutputHeight>,
"fps": <OutputFps>,
"kbps": <OutputKbps>,
"url": "<URL>",
"streamTitle": "<StreamTitle>"
},
"createdAt": <CreatedAt>,
"updatedAt": <UpdatedAt>
}
612
{
"error": "app not found"
}
616
{
"error": "hub not match"
}
AppID: app 的唯一标识。
UID: 客户的七牛帐号。
Hub: 绑定的直播 hub,使用此 hub 的资源进行推流等业务功能,hub 与 app 必须属于同一个七牛账户。
Title: app 的名称,注意,Title不是唯一标识。
MaxUsers: int 类型,连麦房间支持的最大在线人数。
NoAutoKickUser: bool 类型,禁止自动踢人。
MergePublishRtmp: 连麦合流转推 RTMP 的配置。
CreatedAt: time 类型,app 创建的时间。
UpdatedAt: time 类型,app 更新的时间。
4. room 操作接口
一次连麦过程,多个终端音视频通信行为的管理是通过 room 进行的。一个连麦房间必然属于某一个 app。房间无需主动创建或删除,用户直接使用客户端 sdk 指定某个 app 和 room 进行连麦即可加入房间。通过接口可以查询 app 下所有的活跃房间,也可以对某一个房间做相关的业务操作。
4.1 ListUser
Host rtc.qiniuapi.com
GET /v3/apps/<AppID>/rooms/<RoomName>/users
Authorization: qiniu mac
AppID: 连麦房间所属的 app 。
RoomName: 操作所查询的连麦房间。
200 OK
{
"users": [
{
"userId": "<UserID>"
},
]
}
612
{
"error": "app not found"
}
UserID: 连麦房间里在线的用户,如果无在线用户,则返回空数组。
4.2 KickUser
Host rtc.qiniuapi.com
DELETE /v3/apps/<AppID>/rooms/<RoomName>/users/<UserID>
Authorization: qiniu mac
AppID: 连麦房间所属的 app 。
RoomName: 连麦房间。
UserID: 操作所剔除的用户。
200 OK
612
{
"error": "app not found"
}
612
{
"error": "user not found"
}
615
{
"error": "room not active"
}
4.3 StopMerge
Host rtc.qiniuapi.com
DELETE /v3/apps/<AppID>/rooms/<RoomName>/merge
Authorization: qiniu mac
AppID: 连麦房间所属的 app 。
RoomName: 连麦房间。
用于停止某个房间的服务端合流。
不建议客户使用此接口,使用客户端信令可以更灵活准确地控制合流的启停。
200 OK
612
{
"error": "app not found"
}
615
{
"error": "room not active"
}
4.4 ListActiveRoom
Host rtc.qiniuapi.com
GET /v3/apps/<AppID>/rooms?prefix=<RoomNamePrefix>&offset=<Offset>&limit=<Limit>
Authorization: qiniu mac
AppID: 连麦房间所属的 app 。
RoomNamePrefix: 所查询房间名的前缀索引,可以为空。
Offset: int 类型,分页查询的位移标记。
Limit: int 类型,此次查询的最大长度。
200 OK
{
"end": <IsEnd>,
"offset": <Offset>,
"rooms": [
"<RoomName>",
...
]
}
612
{
"error": "app not found"
}
IsEnd: bool 类型,分页查询是否已经查完所有房间。
Offset: int 类型,下次分页查询使用的位移标记。
RoomName: 当前活跃的房间名。
5. RoomToken 的计算
连麦用户终端通过房间管理鉴权获取七牛连麦服务,该鉴权包含了房间名称、用户ID、用户权限、有效时间等信息,需要通过客户的业务服务器使用七牛颁发的AccessKey和SecretKey进行签算并分发给手机APP。手机端SDK以拟定的用户ID身份连接服务器,加入该房间进行视频会议。若用户ID或房间与token内的签算信息不符,则无法通过鉴权加入房间。
计算方法:
// 1. 定义房间管理凭证,并对凭证字符做URL安全的Base64编码
roomAccess = {
"appId": "<AppID>"
"roomName": "<RoomName>",
"userId": "<UserID>",
"expireAt": <ExpireAt>,
"permission": "<Permission>"
}
roomAccessString = json_to_string(roomAccess)
encodedRoomAccess = urlsafe_base64_encode(roomAccessString)
// 2. 计算HMAC-SHA1签名,并对签名结果做URL安全的Base64编码
sign = hmac_sha1(encodedRoomAccess, <SecretKey>)
encodedSign = urlsafe_base64_encode(sign)
// 3. 将AccessKey与以上两者拼接得到房间鉴权
roomToken = "<AccessKey>" + ":" + encodedSign + ":" + encodedRoomAccess
AppID: 房间所属帐号的 app 。
RoomName: 房间名称,需满足规格 ^[a-zA-Z0-9_-]{3,64}$
UserID: 请求加入房间的用户 ID,需满足规格 ^[a-zA-Z0-9_-]{3,50}$
ExpireAt: int64 类型,鉴权的有效时间,传入以秒为单位的64位Unix绝对时间,token 将在该时间后失效。
Permission: 该用户的房间管理权限,"admin" 或 "user",默认为 "user" 。当权限角色为 "admin" 时,拥有将其他用户移除出房间等特权.