本站点除 Legacy 产品与方案外，已迁移至声网新文档中心，当前页面不再维护

文档中心





全部产品

Console 官网社区技术支持





控制台 RESTful API

更新时间 2023/01/12 08:43:31

1. 认证

RESTful API 仅支持 HTTPS。用户必须通过 basic HTTP 认证:

用户名: Customer ID
密钥: Customer Certificate

与声网 SDK 所使用的 App ID 和 App 证书不同，Customer ID 和 Customer Certificate 仅用于访问 RESTful API。

你可以登录控制台，点击右上角账户名，进入下拉菜单 RESTFUL API 页面获取 Customer ID 和 Customer Certificate。Vender Key 和 Sign Key 在控制台里已分别改名为 App ID 和 App 证书，但本文代码里仍沿用 vendor_key 和 sign_key。

2. 接入点

所有请求都发送给 BaseUrl：https://api.agora.io/dev/v1

请求：参数格式必须为 JSON ，内容类型: application/json
响应：响应内容的格式为 JSON。以下为定义的响应状态：

Status 200 请求处理成功

Status 400 输入格式错误

Status 401 未经授权的(App ID/Customer Certificate匹配错误)

Status 404 API调用错误

Status 500 服务器内部错误

3. 项目相关的 API

BaseUrl：https://api.agora.io/dev/v1

下图展示了项目相关 API 的使用逻辑。

获取所有项目 (GET)

方法：GET
路径：BaseUrl/projects/
参数：None

响应：

{
  "projects":[

              {

                "id": 'xxxx',
                "name": 'project1',
                "vendor_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
                "sign_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
                "recording_server": '10.2.2.8:8080',
                "status": 1,
                "created": 1464165672

              }

           ]
}

状态：
- 1: 启用
- 0: 禁用

获取单个项目（GET）

方法：GET
路径：BaseUrl/project/
参数：
```
{
  "id":'xxxx',
  "name":'xxxx'
}
```

响应：

{
  "projects":[

           {

                "id": 'xxxx',
                "name": 'project1',
                "vendor_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
                "sign_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
                "recording_server": '10.2.2.8:8080',
                "status": 1,
                "created": 1464165672

              }

           ]
}

状态：
- 1: 启用
- 0: 禁用

创建项目（POST）

方法：POST
路径：BaseUrl/project/

参数：

{
  "name":'projectx',
  "enable_sign_key": true
}

响应：

{
  "project":
          {

             "id": 'xxxx',
             "name": 'project1',
             "vendor_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
             "sign_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
             "status": 1,
             "created": 1464165672

          }
}

禁用或启用项目（POST）

方法：POST
路径：BaseUrl/project_status/
参数：
```
{
  "id":'xxx',
  "status": 0
}
```

响应：

成功:

{
  "project":
          {

           "id": 'xxxx',
           "name": 'project1',
           "vendor_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
           "sign_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
           "status": 0,
           "created": 1464165672

           }

 }

如果指定的项目不存在 (被删除或不存在):

status 404
content:
{

  "error_msg": "project not exist"

}

删除项目（DELETE）

方法：DELETE
路径：BaseUrl/project/
参数：
```
{
  "id":'xxxx'
}
```

响应：

项目已删除：
```
{
  "success": true
}
```

未找到项目：

status 404

 {
    "error_msg": "project not exist"
 }

设置项目的录制项目服务器 IP（POST）

方法：POST
路径：BaseUrl/recording_config/

参数：

{
  "id":'xxxx',
  "recording_server": '10.12.1.5:8080'
}

如果您使用的 Recording SDK 版本 <= v1.9.0，请关注 recording_server 字段；

如果您使用的 Recording SDK 版本 >= v1.11.0，请忽略 recording_server 字段。

响应：

成功
```
{
  "success": true
}
```

项目未找到或已禁用：

status 404

 {
   "error_msg": "project not exist"
 }

启用项目 App 证书（POST）

方法：POST
路径：BaseUrl/signkey/
参数：
```
{
  "id": `xxx`,
  "enable": true
}
```

响应：

成功
```
{

  "success": true

}
```

项目未找到或已禁用：

status 404
{

  "error_msg": "project not exist"

}

重置项目的 App 证书（POST）

方法：POST
路径：BaseUrl/reset_signkey/
参数：
```
{ "id": “xxx”} // 项目 id
```

响应：

成功
```
{
  "success": true
}
```

项目未找到或已禁用：

status 404
  {
    "error_msg": "project not exist"
  }

如果该项目的 App 证书尚未启用，调用该方法会启用 App 证书。

4. 用量相关的 API

BaseUrl：https://api.agora.io/dev/v1

下图展示了用量相关 API 的使用逻辑。

获取用量数据（GET)

方法：GET
路径：BaseUrl/usage/
参数 (格式为一个日期到另一个日期的YYYY-MM-DD)：
```
"from_date"=YYYY-MM-DD&to_date=YYYY-MM-DD&projects=id1,id2,id3
"from_date"=2015-01-01&to_date=2015-03-21&projects=id1,id2
```
您可以指定项目，但如果不指定，系统将查询该账户下的全部项目。

响应：

成功：

{
  "usages":[

            { "project": 'xxx',
                        "daily": [
                              { "date": 20150101, "audio": 20, "sd": 100, "hd": 132, "hdp": 225},
                              { "date": 20150102, "audio": 20, "sd": 100, "hd": 132, "hdp": 225},
                          ]
                        },

                        { "project": 'yyy',
                          "daily": [....]
                        }

          ]
}

报错: 如果指定的项目 (projects) 不存在，会直接被忽略。不会报错。

该响应中 audio、sd、hd 及 hdp 的单位为分钟。

5. 服务端踢人 API

BaseUrl: https://api.agora.io/dev/v1

下图展示了服务器踢人相关 API 的使用逻辑。

用户被踢出频道后，会收到网络连接已被服务器禁止回调。

Android: onConnectionBanned

iOS/macOS:ConnectionDidBanned

Web:onclient-banned

Windows:onConnectionBanned

创建规则 (POST)

方法：POST
路径：BaseUrl/kicking-rule/

参数:

{
            "appid":"",   // 控制台中项目的appID，必填
            "cname":"",   // channel name 频道名称，非必填，可以不传，但不能传 cname:""
            "uid":"",     // uid，sdk可以获取到，非必填，可以不传，但不能传 uid:0
            "ip":"",      // IP地址需要封的用户IP，非必填，可以不传，但不能传 ip:0
            "time": 60    //  封人时间，单位是分钟，最大 1440 分钟，最小一分钟。如果大于 1440 分钟，会被处理成 1440 分钟，如果不传默认为 1 小时。非必填。比如：time:60
            "privileges":["join_channel"]
 }

如果 time 字段设置为 0，则表示不封禁，服务端会对频道内符合设定规则的用户进行下线一次的操作。用户可以重新登录进入频道。

踢人规则通过 cname、uid 和 ip 三个字段组合起来过滤实现，规则如下：

如果填写 ip，不填写 cname 或 uid，则该 ip 无法登录 App 中的任何频道

如果填写 cname，不填写 uid 或 ip，则任何人都无法登录 App 中该 cname 对应的频道

如果填写 cname 和 uid，不填写 ip，则该 uid 无法登录 App 中该 cname 对应的频道

响应：

{
    "status": "success",  // 请求状态
    "id": 1953            // 规则id，如：更新规则是需要带上此id
}

获取规则列表 (GET)

方法：GET
路径：BaseUrl/kicking-rule/

参数：

{
   "appid":""    // 控制台中项目的appID，必填
 }

响应：

{
    "status": "success",                                    // 请求状态
    "rules": [
        {
            "id": 1953,                                     // 规则id，如：更新规则是需要带上此id
            "appid": ""                                     // 对应控制台中项目的appID
            "uid": 1,                                       // uid，客户端中看到
            "opid": 1406,                                   // 操作id，用于核对操作记录（查问题时使用）
            "cname": "11",                                  // 频道名
            "ip": null,                                     // ip地址
            "ts": "2018-01-09T07:23:06.000Z",               // 规则生效截止时间
            "createAt": "2018-01-09T06:23:06.000Z",         // 规则创建时间
            "updateAt": "2018-01-09T14:23:06.000Z"          // 规则更新时间
        }
    ]
}

更新规则时间 (PUT)

方法：PUT
路径：BaseUrl/kicking-rule/

参数：

{
         "appid":"",   // 控制台中项目的appID，必填
         "id":"",      // 获取规则列表的规则id，必填
         "time":""     // 需要更新的封人的时间，必填
}

响应：

{
    "result": {
        "id": 1953,                         // 规则id，
        "ts": "2018-01-09T08:45:54.545Z"    // 规则生效截止时间
    },
    "status": "success"                     // 请求状态
}

删除规则 (DELETE)

方法：DELETE
路径：BaseUrl/kicking-rule/

参数：

{
    "appid":"",   // 控制台中项目的appID，必填
    "id":""       // 获取规则列表的规则id，必填
}

响应：

{
    "status": "success",  // 请求状态
    "id": 1953            // 规则id，如：更新规则是需要带上此id
}

6. 在线查询频道信息 API

BaseUrl：http://api.agora.io/dev/v1/

为防止大量异常请求影响其他用户的正常使用，我们对 API 的调用频率做了限制。当达到限流阈值时，会返回 HTTP 错误 429 (Too Many Requests)。我们认为设置的阈值可以满足绝大多数用户的使用场景，如果您被限制，请尝试调整调用频率。如果该限制使您的需求无法得到满足，请联系 sales@agora.io 。

下图展示了查询频道信息相关 API 的使用逻辑。

关于用户角色

目前通过 RESTful API 查询到的用户角色（即 online role），和调用 SDK 的 setClientRole 指定的角色含义不同。Online role 是根据频道场景，以及用户的上行媒体流类型来区分的，共有以下几种：

Online Role	枚举值
未知	0
通信场景用户	1
直播场景视频主播	2
直播场景观众	3
直播场景纯音频主播	4

目前 直播场景纯音频主播 尚未区分，会被归属到 直播场景观众 中。

查询某个用户在指定频道中的状态 (GET)

该方法查询某个用户是否在指定频道中，如果是，则给出用户在该频道中的角色等状态。

方法：GET
路径：BaseUrl/channel/user/property/
参数: appid, uid, cname

参数描述

appid 必填，控制台中项目的 appID

uid 必填，用户 ID，可以通过 SDK 获取到

cname 必填，channel name，频道名称

如：/channel/user/property/<appid>/<uid>/<channelName>

响应:

{
    "success": true,
    "data": {
        "join": 1549073054,
        "in_channel": true,
        "role": 2
    }
}

参数	描述
join	该用户加入频道的时间戳
success	查询请求状态 true：请求成功 false：请求不成功
in_channel	查询用户是否在频道内 true：用户在频道内 false：用户不在频道内
role	查询用户在频道内的角色 0：未知 1：用户角色为通信用户 2：用户角色为直播场景视频主播 3：用户角色为主播模式观众 4：用户角色为直播场景纯音频主播

查询频道内的分角色用户列表 (GET)

该方法查询指定频道内的分角色用户列表。

方法：GET
路径：BaseUrl/channel/user/
参数: appid, cname

参数描述

appid 必填，控制台中项目的 appID

cname 必填，channel name，频道名称

如：/channel/user/<appid>/<channelName>

响应:

// 如果是通信频道
{
        "success": true,
        "data": {
                "channel_exist": true,
                "mode": 1,
                "total": 1,
                "users": [<uid>]
        }
}

// 如果是直播频道
{
        "success": true,
        "data": {
                "channel_exist": true,
                "mode": 2
                "broadcasters": [<uid>],
                "audience": [<uid>]
                "auience_total": <count>
        }
}

// 如果频道不存在
{
        "success": true,
        "data": {
                "channel_exist": false
        }
}

参数	描述
success	查询请求状态 true：请求成功 false：请求不成功
channel_exsit	查询频道是否存在： true：频道存在 false：频道不存在
mode	查询频道场景： 1：频道为通信场景 2：频道为直播场景
total	频道内的用户总人数
users	频道内所有用户的 uid

查询厂商频道列表 (GET)

该方法查询指定厂商的频道列表。

方法：GET
路径：BaseUrl/channel/appid/
参数：?page_no=0&page_size=100（非必须）

参数描述

page_no 选填，起始页码，默认值为 0

page_size 选填，每页条数，默认值为 100

如: /channel/<appid>

带参数: /channel/<appid>/?page_no=0&page_size=100

响应:

 {
          "success": true,
          "data": {
              "channels": [
                  {
                      "channel_name": "lkj144",
                      "user_count": 3
                  }
              ],
              "total_size": 3
      }

}

参数	描述
success	查询请求状态 true：请求成功 false：请求不成功
channel_name	频道名
user_count	频道内用户数量
total_size	频道总数

使用该方法查询后会将结果缓存 1 分钟。因此一分钟内再次查询会从缓存结果中提取，而不再更新数据。

查询用户是否连麦用户 (GET)

该方法查询指定用户是否是指定频道中的连麦用户。

方法：GET
规则：BaseUrl/channel/business/hostin/
参数：appid, uid, cname

参数描述

appid 必填，控制台中项目的 appID

uid 必填，用户 ID，可以通过 SDK 获取到

cname 必填，channel name，频道名称

如: /channel/business/hostin/<appid>/<uid>/<channelName>

响应：
```
{
     "success": true,
     "data":{
         "isHostIn": false
     }
}
```
参数描述
success
查询请求状态

true：请求成功

false：请求不成功
isHostIn
查询是否在连麦状态

true：用户在连麦状态

false：用户不在连麦状态

7. 错误码和警告码

详见错误码和警告码。

这篇文章对你有帮助吗？

是

否

Status 200	请求处理成功
Status 400	输入格式错误
Status 401	未经授权的(App ID/Customer Certificate匹配错误)
Status 404	API调用错误
Status 500	服务器内部错误

参数	描述
appid	必填，控制台中项目的 appID
uid	必填，用户 ID，可以通过 SDK 获取到
cname	必填，channel name，频道名称

参数	描述
page_no	选填，起始页码，默认值为 0
page_size	选填，每页条数，默认值为 100