服务端API详情

本文档主要说明音视频2.0提供给开发者服务端频道管理相关RESTful API接口。需要注意的是,每个RESTful API接口都有频控限制,每位用户每秒钟可调用不超过1200次。

API概述

调用说明

全部 说明
协议 仅支持HTTPS
接入点 https://logic-dev.netease.im/v2/api
请求Header 参见 请求Header
Content-Type application/json;charset=utf-8

注:接口中的{cid}为通话id,关于通话id的说明,请参阅音视频通话ID

请求Header

参数 参数说明
AppKey 开发者平台分配的appkey
Nonce 随机数(最大长度128个字符)
CurTime 当前UTC时间戳,从1970年1月1日0点0 分0 秒开始到现在的秒数(String)
CheckSum SHA1(AppSecret + Nonce + CurTime),三个参数拼接的字符串,进行SHA1哈希计算,转化成16进制字符(String,小写)

CheckSum有效期:出于安全性考虑,每个checkSum的有效期为5分钟(用CurTime计算),建议每次请求都生成新的checkSum,同时请确认发起请求的服务器是与标准时间同步的,比如有NTP服务。

API详情

频道管理

创建频道

请求方法 URL 协议
POST https://logic-dev.netease.im/v2/api/room HTTP/1.1
{
    "channelName": "xxx",          // 频道名称
    "mode": 2,                     // 当前请直接传2
    "uid": 163,                    // 频道创建者ID
    "webrtc": 1                    // 当前请直接传1
}
    200: 成功
    400:请求无效
    401:鉴权失败
    404:cid对应频道不存在
    429:请求个数超过频控限制
    500:服务器内部错误
{ 
    "code": 200,         //状态码
    "cid": 12345         //频道id
}

查询频道信息

请求方法 URL 协议
GET https://logic-dev.netease.im/v2/api/rooms/{cid} HTTP/1.1

无。

    200: 成功
    400:请求无效
    401:鉴权失败
    404:请求不存在
    429:请求个数超过频控限制
    500:服务器内部错误
{
    "cid":6207760637435905,             //频道ID【int64】
    "cname":"netease",                  //频道名称
    "uid": 193992653091841,             //频道创建者ID
    "total":3,                          //频道内活跃用户总数
    "stats":1,                          //频道状态【1:初始状态,2:进行中,3:正常结束,4:异常结束】
    "createtime":1513145726,            //频道创建时间【int64】
    "destroytime":1513145926            //频道结束时间【int64】
}

查询频道内成员信息

请求方法 URL 协议
GET https://logic-dev.netease.im/v2/api/rooms/{cid}/members HTTP/1.1

无。

    200: 成功
    400:请求无效
    401:鉴权失败
    404:请求不存在
    429:请求个数超过频控限制
    500:服务器内部错误
{
    "cname": "netease",                 //频道名称
    "cid" : 6207760637435905,          //频道ID【int64】
    "total" : 1,                        //频道活跃人数
    "members":[                         //频道活跃成员信息
        {
            "uid":193992653091841,      //成员ID
            "starttime":1513145926      //成员加入时间【int64】
        }
    ]
}

删除频道

请求方法 URL 协议
DELETE https://logic-dev.netease.im/v2/api/rooms/{cid} HTTP/1.1

无。

    200: 成功
    400:请求无效
    401:鉴权失败
    404:请求不存在
    429:请求个数超过频控限制
    500:服务器内部错误

踢出成员

被踢出后,该成员将无法再次进入本次通话。

请求方法 URL 协议
POST https://logic-dev.netease.im/v2/api/kicklist/{cid}/members/{uid} HTTP/1.1

无。

    200: 成功
    400:请求无效
    401:鉴权失败
    404:cid对应频道或uid对应用户不存在
    429:请求个数超过频控限制
    500:服务器内部错误

获取被踢人员列表

请求方法 URL 协议
GET https://logic-dev.netease.im/v2/api/kicklist/{cid} HTTP/1.1

无。

    200: 成功
    400:请求无效
    401:鉴权失败
    404:cid对应频道不存在
    429:请求个数超过频控限制
    500:服务器内部错误
{
    "uids":[                         //被踢出成员的成员uid列表
        193992653091841,
        193992653091842
    ]
}

撤销踢人操作

请求方法 URL 协议
DELETE https://logic-dev.netease.im/v2/api/kicklist/{cid}/members/{uid} HTTP/1.1

无。

    200: 成功
    400:请求无效
    401:鉴权失败
    404:cid对应频道或uid对应用户不存在
    429:请求个数超过频控限制
    500:服务器内部错误

服务端录制管理

请求方法 URL 协议
POST https://logic-dev.netease.im/v2/api/record/{cid} HTTP/1.1
{   
    "a_record": true,                  //必填 bool,设置频道音频录制开关
    "v_record": true,                  //必填 bool,设置频道视频录制开关
    "type" : 0,                        //选填 uint,设置频道所有用户的录制类型:0-混录单人 1-只混录 2-只单人
    "uid" : 123                           //选填 uint64 设置频道内录制主讲人uid
}
    200: 成功
    400:请求无效
    401:鉴权失败
    404:cid对应频道不存在
    429:请求个数超过频控限制
    500:服务器内部错误

推流任务管理

当需要使用互动直播功能时,必须要设置推流任务。推流任务可以调用服务端接口进行设置,也可以调用客户端接口进行设置。

增加推流任务

请求方法 URL 协议
POST https://logic-dev.netease.im/v2/api/rooms/{cid}/task HTTP/1.1
{
    "taskId" : "stream_1",                          //推流任务ID,string格式
    "streamUrl": "rtmp://test.url",                 //推流地址
    "layout":{...},                                 //layout参数,json格式
    "record":true,                                  //录制开关
    "version": 1                                    //推流任务版本
}
    200: 成功
    400:请求无效
    401:鉴权失败
    404:cid对应频道不存在
    429:请求个数超过频控限制
    500:服务器内部错误
{
    "code": 200     
}       

删除推流任务

请求方法 URL 协议
DELETE https://logic-dev.netease.im/v2/api/rooms/{cid}/task HTTP/1.1
{
    "taskId" : "stream_1"   //推流任务ID,string格式
}
    200: 成功
    400:请求无效
    401:鉴权失败
    404:cid对应频道不存在
    429:请求个数超过频控限制
    500:服务器内部错误
{
    "code": 200           

获取指定推流任务

请求方法 URL 协议
GET https://logic-dev.netease.im/v2/api/rooms/{cid}/task/{taskId} HTTP/1.1

无。

    200: 成功
    400:请求无效
    401:鉴权失败
    404:cid对应频道不存在
    429:请求个数超过频控限制
    500:服务器内部错误
{   
    "code" : 200,                         //必填,200-成功,400-客户请求错误,500-服务器内部错误   
    "status" : "active",                  //任务状态, deleted为已被删除, active为活跃
    "rtmpTask": {
         "taskId": "stream_1",            //推流任务ID,string格式
         "streamUrl": "rtmp://test.url",  //推流地址
         "layout": {...},                 //layout参数,json格式
         "record": true,                  //录制开关
         "version": 1                     //推流任务版本
    }
}

获取所有推流任务

请求方法 URL 协议
GET https://logic-dev.netease.im/v2/api/rooms/{cid}/tasks HTTP/1.1

无。

    200: 成功
    400:请求无效
    401:鉴权失败
    404:cid对应频道不存在
    429:请求个数超过频控限制
    500:服务器内部错误
{   
    "code" : 200,                          //必填,200-成功,400-客户请求错误,500-服务器内部错误   
    "errmsg" : "invalid params",           //选填,失败时返回的错误信息
    "rtmpTasks": [{
         "taskId": "stream_1",             //推流任务ID,string格式
         "streamUrl": "rtmp://test.url",   //推流地址
         "layout": {...},                  //layout参数,json格式
         "record": true,                   //录制开关
         "version": 1                      //推流任务版本
    }]
}

修改推流任务

请求方法 URL 协议
POST https://logic-dev.netease.im/v2/api/rooms/{cid}/update/task HTTP/1.1
{
    "taskId" : "stream_1",              //推流任务ID,string格式
    "streamUrl": "rtmp://test.url",     //推流地址
    "layout":{...},                     //layout参数,json格式
    "record": true                      //录制开关
}
    200: 成功
    400:请求无效
    401:鉴权失败
    404:cid对应频道不存在
    429:请求个数超过频控限制
    500:服务器内部错误
{   
    "code" : 200,                          //必填,200-成功,400-客户请求错误,500-服务器内部错误   
    "errmsg" : "invalid params"            //失败时返回的错误信息
}