新手接入指南
更新时间: 2024/03/25 11:00:43
网易云信音视频通话 2.0 产品提供了一整套服务端接口(RESTful API),可配合客户端 NERTC SDK 的特性,构建完整、丰富的业务体验。您可以向云信服务端发起 HTTP/HTTPS 网络请求,通过使用 GET、POST 或 DELETE 方法调用服务端 API 实现与云信服务端的信息交互,实现房间信令、媒体服务、音视频混流等一系列后台服务。
服务端 API 介绍
服务端 API 具备以下功能:
-
App 用户接入云信实时音视频服务。
您需要从您的业务服务器调用服务端 API 的申请 Token 接口,使用 uid(用户在您应用中的 ID) 申请 Token。用户在客户端登录时必须持有有效的 Token 才能连接云信服务器。具体请参考Token 鉴权。
-
提供高级、扩展特性。
您可以根据业务需求选择使用服务端提供的服务,例如房间管理、旁路推流、安全通审核(增值服务)、云端播放(增值服务)、云端录制(增值服务)等,可配合客户端 SDK 特性,构建完整、丰富的业务体验。
调用服务端 API 后,云信服务器会实时返回相关回调并抄送至您指定的回调地址,服务器回调包括:
-
支持将音视频房间状态变化及房间用户状态变化实时同步到您指定的回调地址。
-
开通安全通审核服务后,支持将音视频、云端录制审核任务检测到的违规事件以及审核任务状态实时同步到您指定的回调地址。
接收云端录制审核任务结果的抄送的前提是开通云端录制服务,具体请参考实现云端录制。
-
调用云端播放 API 时,支持将云端播放任务状态变化实时同步到您指定的回调地址。
-
开通云端录制服务后,支持将云端录制任务状态变化实时同步到您指定的回调地址。
-
在推流至第三方 CDN 时,支持将推流的状态变化实时同步到您指定的回调地址。
服务端 API 使用流程
请参考以下流程,快速向网易云信服务端发起请求:
- 确认请求的 URL 地址;
- 根据签名生成规则,获取签名信息;
- 配置公共请求参数(Header);
- 根据需求配置 API 相关业务参数(Body);
- 在您的业务服务器通过指定 URL 地址,携带请求信息(包含公共及业务参数、签名信息等),访问云信服务端;
- 云信服务端返回响应结果。
步骤一 确认 URL 地址
云信服务端根据不同的 URL 地址区分不同的业务请求,各 URL 地址由三个部分的参数拼接而成。
在访问云信服务端之前,请先到对应功能的接口文档中获取对应的请求 URL 地址。
以创建房间的 URL 地址为例:
https://logic-dev.netease.im/v2/api/room
其中:
https:指定请求通信协议。网易云信所有服务端接口均支持通过 HTTPS 协议进行通信,保障更高的安全性。
logic-dev.netease.im/v2/api:指定云信服务端的接入地址。
room:指定要调用的 API 接口为 room。
步骤二 生成签名信息
为保证服务端 API 的安全调用,云信服务端会对每个 API 的访问请求进行身份验证。您在调用每个服务端 API 前,需要先生成签名 CheckSum 信息。
CheckSum 的计算方式为:将 AppSecret、Nonce 和 CurTime 三个参数拼接的字符串经过 SHA1 哈希计算,并将结果转化成 16 进制字符,即 CheckSum = sha1(AppSecret + Nonce + CurTime)。
您可以参考调用方式里的示例代码计算 CheckSum,使用创建应用后获取到的 App Secret,生成您自己的签名信息。
步骤三 配置公共请求参数(Header)
您在调用云信服务端 API 时,需要在请求中配置 API 的公共请求参数。
公共请求参数指调用每个服务端接口都需要使用到的请求参数,包含了 App Key、CheckSum(指生成的签名信息、Nonce(随机数)、CurTime(时间戳)等鉴权参数,具体参数介绍请参考调用方式。
步骤四 配置 API 相关业务参数(Body)
配置完请求的公共参数后,您需要根据业务需求选择是否继续配置 API 相关的业务参数,因为部分服务端 API 的 Body 部分无需传参。
步骤五 在您的业务服务器发起请求
在您完成以上配置后,即可通过指定 URL 地址向云信服务端发起业务请求。
以创建房间的业务请求为例,请求示例如下:
curl --location --request POST 'http://logic-dev.netease.im/v2/api/room' \
--header 'AppKey: 6acf024e********85905444b6e57dd7' \
--header 'Nonce: frujy' \
--header 'CurTime: 1658298498' \
--header 'CheckSum: cd018042********6ababe33e97e5ef9031fbf48' \
--header 'RequestId: b0******-3f33-44c9-8fd4-f4b217b3aa20' \
--header 'Content-Type: application/json' \
--data-raw '{
"channelName": "c58d016674d043e08260d|0|215!@#$%^&*()_+=-09",
"uid":1111
}'
步骤六 云信服务端响应请求
云信服务端接收到您发起的业务请求并解析请求信息后,会向您返回响应信息,您可根据返回的错误码或状态码判断接口调用是否成功。
以创建房间的请求响应为例,返回示例如下:
{
"code": 200, //返回 code 为 200 表示调用成功
"cid": 12345
}
至此,您与云信服务端成功完成一次信息交互,实现了一次业务请求。