实时音视频云

  • API 参考

    最近更新时间:2018-08-03 18:38:05

    1. 概述

    Qiniu RTC Server API 为七牛实时音视频云提供权限验证和房间管理功能,API 均采用 REST 接口。

    2. HTTP请求鉴权

    Qiniu RTC Server API 通过 Qiniu Authorization 方式进行鉴权,每个房间管理 HTTP 请求头部需增加一个 Authorization 字段:

    Authorization: "<QiniuToken>"
    

    QiniuToken: 管理凭证,用于鉴权。

    使用七牛颁发的AccessKeySecretKey,对本次 http 请求的信息进行签名,生成管理凭证。签名的原始数据包括http请求的 Method, Path, RawQuery, Content-TypeBody 等信息,这些信息的获取方法取决于具体所用的编程语言,建议参照七牛提供的 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" 时,拥有将其他用户移除出房间等特权.

    以上内容是否对您有帮助?
  • Close