1. 认证

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

  • 用户名: Customer ID

  • 密钥: Customer Certificate

与 Agora SDK 所使用的 App ID 和 App Certificate 不同,Customer ID 和 Customer Certificate 仅用于访问 Restful API。

你可以登录 Dashboard,点击右上角账户名,进入下拉菜单 RESTFUL API 页面获取 Customer ID 和 Customer Certificate。Vender Key 和 Sign Key 在 Dashboard 里已分别改名为 App ID 和 App Certificate,但本文代码里仍沿用 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": '4855898a22ae4102a29b81ba76f2eae2',
                    "sign_key": '4855898a22ae4102a29b81ba76f2eae2',
                    "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": '4855898a22ae4102a29b81ba76f2eae2',
                    "sign_key": '4855898a22ae4102a29b81ba76f2eae2',
                    "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": '4855898a22ae4102a29b81ba76f2eae2',
                 "sign_key": '4855898a22ae4102a29b81ba76f2eae2',
                 "status": 1,
                 "created": 1464165672
    
              }
    }

禁用或启用项目(POST)

  • 方法:POST

  • 路径:BaseUrl/project_status/

  • 参数:

    {
      "id":'xxx',
      "status": 0
    }
  • 响应:

    • 成功:

      {
        "project":
                {
      
                 "id": 'xxxx',
                 "name": 'project1',
                 "vendor_key": '4855898a22ae4102a29b81ba76f2eae2',
                 "sign_key": '4855898a22ae4102a29b81ba76f2eae2',
                 "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 Certificate(POST)

  • 方法:POST

  • 路径:BaseUrl/signkey/

  • 参数:

    {
      "id": `xxx`,
      "enable": true
    }
  • 响应:

    • 成功

      {
      
        "success": true
      
      }
    • 项目未找到或已禁用:

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

重置项目的 App Certificate(POST)

  • 方法:POST

  • 路径:BaseUrl/reset_signkey/

  • 参数:

    { "id": “xxx”} // 项目 id
  • 响应:

    • 成功

      {
        "success": true
      }
    • 项目未找到或已禁用:

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

如果该项目的 App Certificate 尚未启用,调用该方法会启用 App Certificate 。

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) 不存在,会直接被忽略。不会报错。

该响应中 audiosdhdhdp 的单位为分钟。

5. 服务端踢人 API

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

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

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

创建规则 (POST)

  • 方法:POST

  • 路径:BaseUrl/kicking-rule/

  • 参数:

    {
                "appid":"",   // dashboard中项目的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":""    // dashboard中项目的appID,必填
     }
  • 响应:

    {
        "status": "success",                                    // 请求状态
        "rules": [
            {
                "id": 1953,                                     // 规则id,如:更新规则是需要带上此id
                "appid": ""                                     // 对应dashboard中项目的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":"",   // dashboard中项目的appID,必填
             "id":"",      // 获取规则列表的规则id,必填
             "time":""     // 需要更新的封人的时间,必填
    }
  • 响应:

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

删除规则 (DELETE)

  • 方法:DELETE

  • 路径:BaseUrl/kicking-rule/

  • 参数:

    {
        "appid":"",   // dashboard中项目的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 必填,dashboard 中项目的 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 必填,dashboard 中项目的 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 必填,dashboard 中项目的 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. 错误代码和警告代码

详见 错误代码和警告代码