跳到主要内容

服务端集成概述

融云为音视频通话（呼叫）、音视频会议、低延迟直播等实时音视频产品提供一套服务端 API（或称为 Server API）与多种服务端回调，可配合客户端 SDK 特性，构建完整和丰富的业务体验。

集成入门​

Server API 具备以下功能：

  • App 用户接入融云实时音视频服务。

    您需要从应用服务器（App Server）调用 Server API 的注册用户接口，使用 App 的用户 ID 换取 Token。客户端必须持有有效的 Token 才可连接融云服务器。参见注册用户。

  • 提供高级、扩展特性。

    例如封禁用户、直播合流、转推第三方 CDN、云端录制（增值服务）、内容审核（增值服务）等，可配合客户端 SDK 特性，构建完整和丰富的业务体验。Server API 接口提供的这些特性，您可根据业务需求选择使用。

音视频服务端回调，包括：

  • 房间状态同步：实时将音视频房间状态变化同步到您指定的回调地址。
  • CDN 推流回调：在推流到融云 CDN 或第三方 CDN 时，支持将推流的状态变化实时同步到您指定的回调地址。
  • 云端录制状态回调：需配合云端录制 API 使用，实时将状态变化同步到您指定的回调地址。
  • 云播放器状态回调：需配合云播放器 API 使用，实时将状态变化同步到您指定的回调地址。
  • 内容审核结果回调：实时将音视频审核任务命中的违规事件以及审核任务状态同步到您指定的回调地址。

注意事项​

重要

  • 注册用户接口是集成融云实时音视频服务的必要条件，否则融云无法为您的 App 用户提供实时音视频服务。您可以认为该接口是唯一必须使用的 Server API 接口。
  • 为避免 App Secret 泄漏等问题，所有 Server API 接口必须通过 App Server 进行调用。切勿通过客户端直接调用 Server API 接口。
  • 在调用 Server API 时，建议不要使用 KeepAlive 方式。如有特殊情况需要使用 KeepAlive，建议每条长连接空闲超时小于 55 秒，并且复用次数小于 80 次。建议在一次连接空闲 55 秒或复用 80 次时切换新连接。长期使用同一条连接会导致 API 负载均衡失效，影响故障转移策略。

Server API 域名​

您在融云创建应用时，可根据业务所在的环境选择 国内数据中心 或 海外数据中心（参见数据中心）。不同数据中心使用独立的服务端 API 地址。应用服务器在调用 Server API 时必须使用与数据中心对应的 Server API 地址，否则 API 请求将无法正确返回结果。

国内数据中心 API 地址​

融云为国内数据中心的应用提供了两个独立的服务端 API 地址：

  • api.rong-api.com
  • api-b.rong-api.com

注意

建议您实现默认域名与备用域名自动切换的逻辑，尽量避免因单一 CDN 服务商问题，导致访问融云 Server API 受阻，进而影响您业务。

以下 Server API 域名已过时，目前仍然可以使用，但已不推荐使用。

  • api.cn.ronghub.com
  • rtcapi.rong-api.com

海外数据中心 API 地址​

海外数据中心（北美或新加坡）的应用，请使用对应的服务端 API 地址：

  • 新加坡：api.sg-light-api.com（主）、api-b.sg-light-api.com（备）
  • 北美：api.us-light-api.com（主）、api-b.us-light-api.com（备）

重要

使用海外数据中心的应用还需要配置客户端 SDK 的数据中心地址。详见知识库文档融云海外数据中心使用指南。

域名切换最佳实践​

注意

域名切换仅针对使用国内数据中心的应用。

使用单一服务端 API 地址时，可能会因为 CDN 服务商问题，导致访问 Server API 延时，对自身业务造成影响。针对使用国内数据中心的应用，我们提供了两个域名，建议开发者实现默认域名与备用域名的切换逻辑。

  1. 开发者调用融云 Server API 时，需要保存当前使用的域名。

  2. 调用过程中，如访问出现超时或不可用时，立即切换至另一备用域名进行访问，同时更新当前使用域名，如此循环，避免对业务造成影响。

API 调用签名规则​

所有请求融云音视频 Server API 接口的请求均使用以下规则校验。

规则说明​

App Server 每次请求 API 接口时，需要提供以下 HTTP Request Header。

默认名称带 RC-前缀类型说明
App-KeyRC-App-KeyString您可以从 控制台 获取应用和环境（开发/生产）的 App Key。
NonceRC-NonceString随机数，不超过 18 个字符。
TimestampRC-TimestampString时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数。
SignatureRC-SignatureString数据签名。参见下文的计算 Signature。
Room-Id无String音视频或直播的房间 ID。

注意

  • Room-Id 为音视频或直播的房间 ID。获取 Token 时无需传入。其他情况下除非具体业务接口明确说明无需传入，否则均需要携带。
  • 带 RC- 前缀的 HTTP Request Header：某些 PaaS 平台（如 SAE）可能会过滤特定的 HTTP Header。如果您使用这些平台时遇到问题，可以使用带 RC- 前缀的 HTTP Request Header，一般情况下使用默认的 HTTP Header 即可。

计算 Signature (数据签名)​

将以下三个字符串按顺序（App Secret + Nonce + Timestamp）拼接成一个字符串，进行 SHA1 哈希计算。

  • App Secret：请登录控制台，获取与该应用 App Key 所对应的 App Secret。
  • Nonce：随机数
  • Timestamp：时间戳

如果调用的数据签名验证失败，接口调用会返回 HTTP 状态码 401。

生成示例​

PHP 语言的代码示例：

// 重置随机数种子。
srand((double)microtime()*1000000);

$appSecret = 'your-own-app-secret'; // 开发者平台分配的 App Secret。
$nonce = rand(); // 获取随机数。
$timestamp = time()*1000; // 获取时间戳（毫秒）。

$signature = sha1($appSecret.$nonce.$timestamp);

HTTP 请求示例：

POST /user/getToken.json HTTP/1.1
Host: api.rong-api.com
App-Key: your-own-app-key
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
最后于 更新