音视频房间管理API文档
更新时间: 2024/08/06 15:35:28
RESTful API接口功能说明
本文档主要说明网易云信音/视频服务器提供给开发者服务端房间管理相关RESTful API接口。需要注意的是,每个RESTful API接口都有频控限制,每位用户每秒钟可调用不超过1200次。
全部 | 说明 |
---|---|
协议 | 仅支持HTTPS |
接入点 | https://roomserver-dev.netease.im/v1/api |
请求Header | HTTP Header需附带云信Server API认证字段:AppKey、Nonce、CurTime、CheckSum;详见API checksum校验 使用说明。 |
Content-Type | application/json;charset=utf-8 |
RESTful API接口详细说明
注:以下接口中的{id}为通话id,关于通话id的说明,请参阅音视频通话ID。此外通过eventType=5和6的消息抄送的也可以获取到通话id。
1.查询某个房间状态信息
HTTP请求方式:
请求 | 说明 |
---|---|
请求格式 | GET https://roomserver-dev.netease.im/v1/api/rooms/{id} |
请求参数 | 无 |
HTTP 响应Code:
200: 成功
400:请求无效
401:鉴权失败
404:请求不存在
429:请求个数超过频控限制
500:服务器内部错误
HTTP响应内容:
jsonContent-Type: application/json;charset=utf-8
{
"cid":6207760637435905, //房间ID【int64】
"cname":"netease", //房间名称
"accid": "193992653091841", //房间创建者ID
"total":3, //房间内活跃用户总数
"mode":1, //房间模式【1:双人、2:多人】
"stats":1, //房间状态【1:初始状态,2:进行中,3:正常结束,4:异常结束】
"createtime":1513145726, //房间创建时间【int64】
"destroytime":1513145926 //房间结束时间【int64】
}
2.查询某个房间成员信息
HTTP请求方式:
请求 | 说明 |
---|---|
请求格式 | GET https://roomserver-dev.netease.im/v1/api/rooms/{id}/members |
请求参数 | 无 |
HTTP响应Code:
200: 成功
400:请求无效
401:鉴权失败
404:请求不存在
429:请求个数超过频控限制
500:服务器内部错误
HTTP响应内容:
jsonContent-Type: application/json;charset=utf-8
{
"cname" : "netease", //房间名称
"cid" : 6207760637435905, //房间ID【int64】
"total" : 3, //房间活跃人数
"members":[ //房间活跃成员信息
{
"accid":"193992653091841", //成员ID
"starttime":1513145926, //成员加入时间【int64】
"role" : 101 //成员角色【101:点对点用户、201:会议用户、301:互动主播、302:普通观众、99:其它】
}
]
}
3.删除某个房间
HTTP请求方式:
请求 | 说明 |
---|---|
请求格式 | DELETE https://roomserver-dev.netease.im/v1/api/rooms/{id} |
请求参数 | 无 |
HTTP响应Code:
200: 成功
400:请求无效
401:鉴权失败
404:请求不存在
429:请求个数超过频控限制
500:服务器内部错误
HTTP响应内容:
无
4.管理员踢出房间内的指定用户并禁止后续加入
HTTP请求方式:
请求 | 说明 |
---|---|
请求格式 | POST https://roomserver-dev.netease.im/v1/api/kicklist/{cid}/members/{accid} |
请求参数 | 无 |
HTTP响应Code:
200: 成功
400:请求无效
401:鉴权失败
404:cid对应房间或accid对应用户不存在
429:请求个数超过频控限制
500:服务器内部错误
HTTP响应内容:
无
5.管理员获取房间中踢出的人员列表
HTTP请求方式:
请求 | 说明 |
---|---|
请求格式 | GET https://roomserver-dev.netease.im/v1/api/kicklist/{cid} |
请求参数 | 无 |
HTTP响应Code:
200: 成功
400:请求无效
401:鉴权失败
404:cid对应房间不存在
429:请求个数超过频控限制
500:服务器内部错误
HTTP响应内容:
jsonContent-Type: application/json;charset=utf-8
{
"accids":[ //被踢出成员的成员ID列表
193992653091841,
193992653091842
]
}
6.管理员撤销踢人操作
HTTP请求方式:
请求 | 说明 |
---|---|
请求格式 | DELETE https://roomserver-dev.netease.im/v1/api/kicklist/{cid}/members/{accid} |
请求参数 | 无 |
HTTP响应Code:
200: 成功
400:请求无效
401:鉴权失败
404:cid对应房间或accid对应用户不存在
429:请求个数超过频控限制
500:服务器内部错误
HTTP响应内容:
无
7.管理员设置频道录制
HTTP请求方式:
请求 | 说明 |
---|---|
请求格式 | POST https://roomserver-dev.netease.im/v1/api/record/{cid} |
请求参数 | 无 |
HTTP请求体
{
"a_record": true, //必填 bool,设置房间音频录制开关
"v_record": true, //必填 bool,设置房间视频录制开关
"type" : 0 //选填 uint,设置房间所有用户的录制类型:0-混录单人 1-只混录 2-只单人
}
HTTP响应Code:
200: 成功
400:请求无效
401:鉴权失败
404:cid对应房间不存在
429:请求个数超过频控限制
500:服务器内部错误
HTTP响应内容:
无
8.创建房间
参照互动直播服务器API文档。
9.账号全局禁用音视频
请求说明
httpPOST https://api.netease.im/nimserver/user/muteAv.action HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8
请求中Headers的设置请参考接口概述
接口描述
设置或取消账号是否可以发起音视频功能;
账号被设置为禁用音视频后,不能发起点对点音视频、创建多人音视频、发起点对点白板、创建多人白板
参数说明
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
accid | String | 是 | 用户帐号 |
mute | Boolean | 是 |
是否全局禁言: true:全局禁言,false:取消全局禁言 |
curl请求示例
curlcurl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'accid=zhangsan&mute=true' 'https://api.netease.im/nimserver/nimserver/user/mute.action'
返回说明
http 响应:json
json"Content-Type": "application/json; charset=utf-8"
{
"code":200
}
主要的返回码
200、403、414、416、431、500
具体请参考code状态表
10.根据cid查询录制文件信息
请求说明
httpPOST https://api.netease.im/nimserver/history/queryMediaFileByChannelId.action HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8
请求中Headers的设置请参考接口概述
备注:此接口受频控限制,1分钟最多调用60次,建议用户开通录制文件抄送功能来维护录制文件信息,本接口仅作为抄送异常时的补偿手段
参数说明
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
channelId | Long | 是 | 通道号 |
curl请求示例
curlcurl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'channelId=123' 'https://api.netease.im/nimserver/history/queryMediaFileByChannelId.action'
返回说明
http 响应:json
json"Content-Type": "application/json; charset=utf-8"
{
"code": 200,
"fileInfos": [
{
"createTime": 1587718829022,
"objectName": "123-22222222-1589020209203-0.mp4",
"url": "http://vod9abc.nosdn.127.net/123-22222222-1589020209203-0.mp4"
},
{
"createTime": 1587718828946,
"objectName": "0-22222222-1589020209203-0-mix.mp4",
"url": "http://vod9abc.nosdn.127.net/0-22222222-1589020209203-0-mix.mp4"
}
],
"channelId": 52026368004000
}
主要的返回码
200、403、404、414、416、500
具体请参考code状态表
RESTful API接口调用例子
1.获取房间信息示例代码【Go语言】:
//初始化HTTP Client
tr := http.Transport{
TLSClientConfig : &tls.Config{InsecureSkipVerify: true},
}
client := http.Client{
Timeout: 5 * time.Second, //HTTP客户端超时时间
Transport: &tr,
}
//id: 房间号
var id int64 = 6217678937673432431
url := fmt.Sprintf("https://roomserver-dev.netease.im/v1/api/rooms/%d", id)
req, err := http.NewRequest(http.MethodGet, url, nil)
if err != nil {
fmt.Println("http newrequest error:", err)
return
}
//开发者DemoKey
var (
AppkeyDemo = "45c6af309b18a84451215d0bddr6e"
SecretKeyDemo = "37db6b60"
)
//云信Server API认证头信息, nonce, curtime, checksum生成详见:服务器API文档
nonce, curtime, checksum := auth.GetLiveCheckSum(SecretKeyDemo)
req.Header.Set("CheckSum", checksum)
req.Header.Set("AppKey", AppkeyDemo)
req.Header.Set("CurTime", curtime)
req.Header.Set("Nonce", nonce)
//HTTP请求
resp, err := client.Do(req)
if err != nil {
fmt.Println("client do error:", err)
return
}
defer resp.Body.Close()
//HTTP响应
body, err := ioutil.ReadAll(resp.Body);
if err != nil{
fmt.Println("status code:", resp.StatusCode, ", error:", err)
return
}
//HTTP非200错误
if resp.StatusCode != http.StatusOK {
fmt.Println("status code:", resp.StatusCode, ", body:", string(body))
return
}
//房间信息响应描述
type GetRoomRes struct{
Cid int64 `json:"cid"`
Cname string `json:"cname"`
Accid string `json:"accid"`
Total int `json:"total"`
Mode int `json:"mode"`
Stats int `json:"stats"`
CreateTime int64 `json:"createtime"`
DestroyTime int64 `json:"destroytime"`
}
//解析房间信息
var res GetRoomRes
if err = json.Unmarshal(body, &res); err == nil {
fmt.Printf("res = %+v", res)
}
此文档是否对你有帮助?