Server 开发指南

    注意:融云提供的 Server API 功能接口,必须通过您的 App Server 进行调用,不支持通过客户端直接调用。通过客户端直接调用融云 Server API 接口而引起的问题,融云不负责解决。
    在调用 Server API 时,建议不使用 KeepAlive 方式,如有特殊情况需要使用 KeepAlive 建议在此基础上,每个 HTTP 连接使用建议小于 60 秒,断开重连,不要长期复用一个 HTTP 连接,长期使用会导致 API 负载均衡失效,影响故障转移策略。

    如果您需要额外的服务端接口能力,请联系我们的销售团队,或提交需求工单给我们。

    通用 API 接口签名规则

    API 调用签名规则

    本文档中所有请求融云服务端 API 接口的请求均使用此规则校验,以下不再重复说明。

    每次请求 API 接口时,均需要提供 4 个 HTTP Request Header,具体如下:

    名称 类型 说明
    App-KeyRC-App-Key String 开发者平台分配的 App Key。
    NonceRC-Nonce String 随机数,无长度限制。
    TimestampRC-Timestamp String 时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数。
    SignatureRC-Signature String 数据签名。

    Signature (数据签名)计算方法:将系统分配的 App Secret、Nonce (随机数)、Timestamp (时间戳)三个字符串按先后顺序拼接成一个字符串并进行 SHA1 哈希计算。如果调用的数据签名验证失败,接口调用会返回 HTTP 状态码 401。其他状态码请参见状态码表

    RC- 前缀的 HTTP Header 是为了适应某些 PaaS 平台(如 SAE)过滤特定 HTTP Header 的机制而考虑的,如果您使用这些平台时遇到问题,可以使用 RC- 前缀,一般情况下使用默认的 HTTP Header 即可。

    签名生成代码示例

    PHP 语言的代码示例:

    // 重置随机数种子。
    srand((double)microtime()*1000000);
    
    $appSecret = 'Y1W2MeFwwwRxa0'; // 开发者平台分配的 App Secret。
    $nonce = rand(); // 获取随机数。
    $timestamp = time()*1000; // 获取时间戳(毫秒)。
    
    $signature = sha1($appSecret.$nonce.$timestamp);
    

    HTTP 请求示例:

    POST /user/getToken.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408710653000
    Signature: 30be0bbca9c9b2e27578701e9fda2358a814c88f
    Content-Type: application/x-www-form-urlencoded
    Content-Length: 78
    
    userId=jlk456j5&name=Ironman&portraitUri=http%3A%2F%2Fabc.com%2Fmyportrait.jpg
    

    API 接收签名规则

    融云服务器向应用服务器推送数据(调用应用服务器接口)时会添加 3 个 GET 请求参数(在 URL 上添加的参数),具体如下:

    名称 类型 说明
    nonce String 随机数,无长度限制。
    signTimestamp String 时间戳,从1970年1月1日0点0分0秒开始到现在的毫秒数。
    signature String 数据签名。

    Signature (数据签名)计算方法:将系统分配的 App Secret、Nonce (随机数)、signTimestamp (时间戳)三个字符串按先后顺序拼接成一个字符串并进行 SHA1 哈希计算。

    签名校验代码示例

    PHP 语言的代码示例:

    $appSecret = 'Y1W2MeFwwwRxa0'; // 开发者平台分配的 App Secret。
    $nonce = $_GET['nonce']; // 获取随机数。
    $timestamp = $_GET['signTimestamp']; // 获取时间戳。
    $signature = $_GET['signature']; // 获取数据签名。
    $local_signature = sha1($appSecret.$nonce.$timestamp); // 生成本地签名。
    if(strcmp($signature, $local_signature)===0){
        // TODO: 此处添加业务逻辑。
        echo 'OK';
    } else {
        echo 'Error';
    }
    

    用户服务

    获取 RTCToken 方法

    使用会场模式的 RTCLib SDK 集成实时音视频服务,需要获取用户的实时音视频 RTCToken,必须通过服务器端获取,不支持客户端获取,因为获取 RTCToken 时需要提供 App Key 和 App Secret 。如果在客户端获取 App 代码一旦被反编译,则会导致 App Key 和 App Secret 泄露。

    如集成通话模式的 CallLib SDK、CallKit SDK 时,则不需要获取 RTCToken。

    方法名:/rtc/user/getToken

    签名方法:请参考 通用 API 接口签名规则

    URL:http://api.cn.ronghub.com/rtc/user/getToken.[format]

    [format] 表示返回格式,可以为 jsonxml,注意不要带 [ ]。

    HTTP 方法:POST

    表单参数

    名称 类型 说明
    userId String 用户 Id,支持大小写英文字母、数字、部分特殊符号 + | = - _ 的组合方式,最大长度 64 字节。是用户在 App 中的唯一标识,必须保证在同一个 App 内不重复,重复的用户 Id 将被当作是同一用户。(必传)

    返回值

    名称 类型 说明
    code Int 返回码,200 为正常。
    rtcToken String 用户 RTCToken,可以保存应用内,长度在 256 字节以内。
    userId String 用户 Id,与输入的用户 Id 相同。

    示例

    HTTP 请求:

    POST /rtc/user/getToken.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408710653491
    Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
    Content-Type: application/x-www-form-urlencoded
    
    userId=jlk456j5
    

    HTTP 响应:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    
    {"code":200, "userId":"jlk456j5", "rtcToken":"sfd9823ihufi"}
    

    音视频状态同步服务

    在融云开发者平台开启服务端录像功能后,才能使用此服务。

    此服务用于向第三方同步音视频会话的会场状态信息。音视频会话过程中,房间的创建,销毁,人员的进出房间等状态信息会通过 HTTP 请求发送到第三方的 Server。

    设计参考

    开发者可以参考 Demo 快速集成。

    该项目实现了订阅接口、接收消息接口,开发者通过实现 ChannelEventListener 来接收房间事件处理自身业务逻辑。

    订阅/取消订阅接口

    API 接口签名规则,详细信息请参考通用 API 接口签名规则

    • 订阅接口
        POST /channel/subscribe
    
        返回结果:
        {
            "msg": "OK",
            "code": 200
        }
    

    此订阅接口应每三分钟应调用一次,超时未调用则认为已经失效,Server 将不再发送房间的动态信息。

    表单参数:

    参数名称 类型 说明
    addr String 消息接收 url

    返回值:

    参数名称 类型 说明
    msg String 结果信息
    code int 返回码 200 为正常

    HTTP 请求示例:

    POST /channel/subscribe HTTP/1.1
    Host: rtc.ronghub.com
    App-Key: c9kqb3rdkbb8j
    Nonce: 14314
    Timestamp: 1408710653491
    Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
    Content-Type: application/x-www-form-urlencoded
    
    addr=http%3a%2f%2fwww.xxxx.com
    
    • 取消订阅接口
        DELETE /channel/subscribe
    
        返回结果:
        {
            "msg": "OK",
            "code": 200
        }
    

    HTTP 请求示例:

    DELETE /channel/subscribe HTTP/1.1
    Host: rtc.ronghub.com
    App-Key: c9kqb3rdkbb8j
    Nonce: 14314
    Timestamp: 1408710653491
    Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
    Content-Type: application/x-www-form-urlencoded
    

    消息接收接口

    消息格式:
    {
        "appid":"1234567890abcdefg",
        "cid":"xxxx",
        "event": {
            "eventType":15,
            "uid": "cccc",
            "data": "192.168.1.1:9099",
            "timestamp": 111111111
        },
        "channelInfo": {
            "members": [{
                    "uid": "cccc",
                    "mediaServer": "192.168.1.1:9099",
                    "memberType": 1,
                },
                {
                    "uid": "bbbb",
                    "mediaServer": "",
                    "memberType": 1,
                },
                {
                    "uid": "zzzz",
                    "mediaServer": "",
                    "memberType": 1,
                }
            ]
        }
    }
    

    参数说明:

    参数名称 类型 说明 备注
    appid String 应用 id
    cid String 房间号
    event Object 当前事件
    event.eventType Int 事件类型 1 同步房间信息,11 成员加入房间,12 成员离开房间,13 成员被强制离开,14 成员更新角色类型,15 成员选定的媒体服务器,21 房间创建,22 房间销毁,23 白板创建
    event.uid String 用户 id
    event.data Object 数据信息 当事件类型为 15,此字段值为选定的 mediaserver 网络地址,当事件类型为11,此字段值为 memberType
    event.timestamp Long 毫秒时间戳 标记当前事件发生的事件
    channelInfo Object 房间信息
    channelInfo.members Array 成员列表
    channelInfo.members.uid String 成员用户id
    channelInfo.members.mediaServer String 成员选定的 mediaserver 地址
    channelInfo.members.memberType Int 成员类型 1 与会人 2 观察者 3 主持人

    API 方法返回值说明

    HTTP 状态码

    code 描述 详细解释
    200 成功 成功
    400 错误请求 该请求是无效的,详细的错误信息会说明原因
    401 未授权 验证失败,详细的错误信息会说明原因
    403 服务器拒绝请求 被拒绝调用,详细的错误信息会说明原因
    404 未找到 服务器找不到请求的地址
    405 方法禁用 群容量超出上限,禁止调用
    429 太多的请求 超出了调用频率限制,详细的错误信息会说明原因
    500 服务器内部错误 服务器内部出错了,请联系我们尽快解决问题
    504 网关超时 服务器在运行,本次请求响应超时,请稍后重试

    业务返回码

    code 描述 详细解释 HTTP 状态码
    404 未找到 服务器找不到请求的地址 404
    1000 服务内部错误 服务器端内部逻辑错误,请稍后重试 500
    1001 App Secret 错误 App Key 与 App Secret 不匹配 401
    1002 参数错误 参数错误,详细的描述信息会说明 400
    1003 无 POST 数据 没有 POST 任何数据 400
    1004 验证签名错误 验证签名错误 401
    1005 参数长度超限 参数长度超限,详细的描述信息会说明 400
    1006 App 被锁定或删除 App 被锁定或删除 401
    1007 被限制调用 该方法被限制调用,详细的描述信息会说明 401
    1008 调用频率超限 调用频率超限,详细的描述信息会说明,广播消息未开通时也会返回此状态码。 429
    1009 服务未开通 未开通该服务,请到开发者管理后台开通或提交工单申请。 430
    1015 删除的数据不存在 要删除的保活聊天室 ID 不存在。 200
    1016 设置保活聊天室个数超限 设置的保活聊天室个数超限。 403
    1017 实时音视频 SDK 版本不支持 音视频 SDK 版本不支持,请使用 2.9.0 及之后的实时音视频 SDK。 403
    1018 实时音视频服务未开启 未开启服务,请到开发者管理后台开通实时音视频服务。 403
    1050 内部服务超时 内部服务响应超时 504
    2007 测试用户数量超限 测试用户数量超限 403