文档中心
Agora 平台
Console 官网 社区 技术支持
简体中文
search-icon

水晶球 RESTful API (Beta)

更新时间 2021/07/13 09:52:04

水晶球现在提供 RESTful API，可以让你直接通过网络请求获取水晶球里的数据，在自己的网页或应用中灵活使用。

在阅读本文之前，我们推荐你先在控制台中试用水晶球的界面，以便对各项参数和数据指标有更直观的了解，详情可参考水晶球。

通过 RESTful API，你可以发送请求获取以下数据：

  • 数据洞察
    • 指定时间段的用量指标
    • 指定时间段的质量指标
  • 通话调查
    • 符合指定条件的通话及基本信息
    • 某个通话的详细质量指标

当通话质量出现问题时，你还可以发送请求向 Agora 报告问题。

水晶球 RESTful API 目前处于 BETA 阶段，不对外开放。如需开通服务，请联系 sales@agora.io。

认证

使用 RESTful API 前，你需要通过 HTTP 基本认证。

数据格式

所有的请求都发送给域名：api.agora.io。

  • 请求：请求直接在 URL 中使用查询字符串参数（query String）
  • 响应：响应内容的格式为 JSON

数据洞察

数据洞察可以查询指定时间范围内的用量和质量数据。

API 限制

数据洞察 RESTful API 的调用限制取决于你订阅的水晶球套餐包。

  • 自 2021 年 5 月 20 日起，水晶球提供体验版、标准版、专业版、旗舰版四个档位的套餐包。各套餐包的区别详见套餐包详情。
  • 体验版套餐包不支持调用数据洞察 RESTful API。

    • 标准版、专业版、旗舰版套餐包在数据洞察 RESTful API 的调用限制方面有以下区别：

    • 接入点为 /beta/insight/usage/by_time（查询用量指标）：
    标准版 专业版 旗舰版
    请求次数 每分钟 1 次，每天 10 次 每分钟 3 次，每天 40 次 每分钟 10 次，每天 60 次
    可查询时间范围 最近 3 天 最近 14 天 最近 30 天
    单次查询时间范围 不超过 1 天 不超过 3 天 不超过 7 天
    数据粒度 天 天、小时 天、小时
    数据延迟 24h 12h 6h
    • 接入点为 /beta/insight/quality/by_time（查询质量指标）：
    标准版 专业版 旗舰版
    请求次数 每分钟 1 次，每天 10 次 每分钟 3 次，每天 40 次 每分钟 10 次，每天 60 次
    可查询时间范围 最近 3 天 最近 14 天 最近 30 天
    单次查询时间范围 不超过 1 天 不超过 3 天 不超过 7 天
    数据粒度 天、小时 天、小时、分钟 天、小时、分钟
    数据延迟 12h 6h 6h
    请求次数的计算以服务器的 UTC 时间为准。

    查询用量指标

    获取指定时间范围内的用量指标，包括通话人数、通话人次、频道数、同时在线频道数、同时在线人数。

    • 方法：GET
    • 接入点：/beta/insight/usage/by_time

    请求参数

    你需要在 URL 中传入以下参数：

    参数 类型 描述
    start_ts Number 查询的时间范围起点，Unix 时间戳 （秒）。
    end_ts Number 查询的时间范围终点，Unix 时间戳 （秒）。
    appid String 你的项目使用的 App ID。
    metric String 要查询的指标，支持设为以下值：
  • userCount：通话人数，不同频道中的相同用户 ID 计为多人。
  • sessionCount：通话进出人次，用户每加入一次频道计为一个通话人次。
  • channelCount：频道数，从有用户加入频道到所有用户离开频道计为一个通话频道。
  • peakCurrentChannels：最大同时在线频道数。
  • peakCurrentUsers：最大同时在线人数。
  • totalDuration：通话时长。
  • totalVideoDuration：视频通话时长。
  • totalAudioDuration：音频通话时长。
    		•
    aggregateGranularity String 返回数据的粒度，支持设为以下值：
  • 1d：按天。此时返回查询时间范围内 UTC 时间为零点的数据。
  • 1h：按小时。此时返回查询时间范围内 UTC 时间为整小时的数据。
    		•

    HTTP 请求示例

    以按天查询 2021 年 7 月 1 日早上 8 点到 2021 年 7 月 3 日早上 8 点的通话人数为例，HTTP 请求如下：

    GET /beta/insight/usage/by_time?startTs=1625097600&endTs=1625270400&appid=axxxxxxxxxxxxxxxxxxxx&metric=userCount&aggregateGranularity=1d HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    响应示例

    上述 HTTP 请求的响应示例如下：

    {
    "code": 200,
    "message": "success",
    "data": [
       {
            "userCount": 42,
            "ts": 1625155200
       },
       {
            "userCount": 65,
            "ts": 1625241600
       },
   ]
}

    其中，各响应参数的含义如下：

    • code: Number 类型，响应状态码。200 表示请求成功，详见状态码。
    • message: String 类型，错误消息。
    • data: JSONArray 类型，由指标数据值和 Unix 时间戳组成的数组。由于请求按天查询 2021 年 7 月 1 日早上 8 点到 2021 年 7 月 3 日早上 8 点的通话人数，该数组包含 2 组数据，分别为 7 月 2 日零点和 7 月 3 日零点的通话人数和 Unix 时间戳。
      • userCount: 请求的指标名称，通话人数。
      • ts: Unix 时间戳 （秒）。

    查询质量指标

    获取指定时间范围内的质量指标，包括加入频道成功率、5s 加入频道成功率、音频卡顿率、视频卡顿率、网络延迟。

    • 方法：GET
    • 接入点：/beta/insight/quality/by_time

    请求参数

    你需要在 URL 中传入以下参数：

    参数 类型 描述
    start_ts Number 查询的时间范围起点，Unix 时间戳 （秒）。
    end_ts Number 查询的时间范围终点，Unix 时间戳 （秒）。
    appid String 你的项目使用的 App ID。
    metric String 要查询的指标，支持设为以下值：
  • joinSuccessRate：加入频道成功率。
  • joinSuccessIn5sRate：5s内加入频道成功率。
  • audioFreezeRate：音频卡顿率。
  • videoFreezeRate：视频卡顿率。
  • networkDelay ：网络延迟率。
    		•
    aggregateGranularity String 返回数据的粒度，支持设为以下值：
  • 1d：按天。此时返回查询时间范围内 UTC 时间为零点的数据。
  • 1h：按小时。此时返回查询时间范围内 UTC 时间为整小时的数据。
  • 1m：按分钟。此时返回查询时间范围内 UTC 时间为整分钟的数据。
    		•
    productType String 要查询的产品类型，支持设为以下值：
  • Native：指 Android、iOS、macOS、Windows 平台的 Agora RTC SDK。
  • WebRTC：指 Web 平台的 Agora RTC SDK。
    		•

    HTTP 请求示例

    以按天查询 2021 年 7 月 1 日早上 8 点到 2021 年 7 月 3 日早上 8 点的网络延迟率为例，HTTP 请求如下：

    GET /beta/insight/quality/by_time?startTs=1625097600&endTs=1625270400&appid=axxxxxxxxxxxxxxxxxxxx&metric=networkDelay&aggregateGranularity=1d&productType=Native HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    响应示例

    {
    "code": 200,
    "message": "success",
    "data": [
       {
            "networkDelay": 0.064762,
            "ts": 1625155200
       },
       {
            "networkDelay": 0.046284,
            "ts": 1625241600
       },
   ]
}

    其中，各响应参数的含义如下：

    • code: Number 类型，响应状态码。200 表示请求成功，详见状态码。
    • message: String 类型，错误消息。
    • data: JSONArray 类型，由指标数据值和 Unix 时间戳组成的数组。由于请求按天查询 2021 年 7 月 1 日早上 8 点到 2021 年 7 月 3 日早上 8 点的网络延迟率，该数组包含 2 组数据，分别为 7 月 2 日零点和 7 月 3 日零点的网络延迟率和 Unix 时间戳。
      • networkDelay: 网络延迟率。
      • ts: Unix 时间戳 （秒）。

    通话调查

    通话调查可以搜索出现质量问题的通话并且查询具体的质量指标。

    API 限制

    通话调查 RESTful API 的调用限制取决于你订阅的水晶球套餐包。

  • 自 2021 年 5 月 20 日起，水晶球提供体验版、标准版、专业版、旗舰版四个档位的套餐包。各套餐包的区别详见计费说明。
  • 体验版套餐包不支持调用通话调查 RESTful API。

    • 标准版、专业版、旗舰版套餐包在通话调查 RESTful API 的调用限制方面有以下区别：

    • 接入点为 /beta/analytics/call/lists（获取频道通话列表）：
    标准版 专业版 旗舰版
    请求次数 每秒 1 次，每天 1000 次 每秒 3 次，每天 2000 次 每秒 10 次，每天 10000 次
    数据延迟 60 秒 20 秒 20 秒
    响应内容 每次最多返回 8 小时通话数据 每次最多返回 16 小时通话数据 每次最多返回 24 小时通话数据
    可查询时间范围 最近 3 天 最近 7 天 最近 15 天
    • 接入点为 /beta/analytics/call/sessions（获取用户通话详情）：
    标准版 专业版 旗舰版
    请求次数 每秒 1 次，每天 1000 次 每秒 3 次，每天 2000 次 每秒 10 次，每天 10000 次
    数据延迟 300 秒 150 秒 100 秒
    响应内容 每次最多返回 1 小时通话数据 每次最多返回 3 小时通话数据 每次最多返回 6 小时通话数据
    可查询时间范围 最近 1 天 最近 7 天 最近 15 天
    • 接入点为 /beta/analytics/call/metrics（获取通话质量指标）：
    标准版 专业版 旗舰版
    请求次数 每秒 1 次，每天 1000 次 每秒 3 次，每天 2000 次 每秒 10 次，每天 10000 次
    数据延迟 300 秒 150 秒 100 秒
    响应内容 每次最多返回 1 小时通话数据 每次最多返回 3 小时通话数据 每次最多返回 6 小时通话数据
    可查询时间范围 最近 1 天 最近 7 天 最近 15 天
  • 请求次数的计算以服务器的 UTC 时间为准。
  • 数据延迟是指从一个通话开始到能获取该通话的数据需要的时间。

    • 获取频道通话列表

    获取符合指定条件的通话及其基本信息。

    • 方法：GET
    • 接入点：/beta/analytics/call/lists

    请求参数

    该 API 需要在 URL 中传入以下参数指定搜索通话的条件。

    参数 类型 描述
    start_ts Number 搜索的时间范围起点。Unix 时间戳 （秒）。
    end_ts Number 搜索的时间范围终点。Unix 时间戳（秒）。
    cname String （可选）频道名称。
    appid String 你的项目使用的 App ID。

    HTTP 请求示例

    GET /beta/analytics/call/lists?start_ts=1550024508&end_ts=1550025508&appid=xxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    响应示例

    {
"code": 200,
"message": "",
"has_more": false,
"call_lists": 
[
  {
  "call_id": "cxxxxxxxxxxxxxxxxxxxx",
  "cname":   "cname1",
  "created_ts": 1547448383,
  "destroyed_ts": 1547448483,
  "finished": true
  }
]
}
    • code: Number 类型，响应状态码。200 表示请求成功，详见状态码。
    • message: String 类型，错误消息。
    • has_more: Boolean 类型，是否还有通话未列出。如果为 true，表示符合查询条件的通话没有在 call_lists 中全部列出。如果你要查找的通话未列出，请修改查询条件重新发送请求。
    • call_lists: JSONArray 类型，返回的通话。默认返回最近的 100 个通话，按通话开始时间降序排列。每个通话中包含以下信息：
      • call_id: String 类型，通话 ID，即通话的唯一标识。
      • cname: String 类型，频道名称。
      • created_ts: Number 类型，通话开始的时间。Unix 时间戳（秒）。
      • destroyed_ts: Number类型，通话结束的时间。Unix 时间戳（秒）。
      • finished: Boolean 类型，通话是否结束。

    获取用户通话详情

    通过指定通话 ID 来获取用户的通话详情。

    • 方法：GET
    • 接入点：/beta/analytics/call/sessions

    请求参数

    该 API 需要在 URL 中传入以下参数指定通话 ID 和获取的数据。

    参数 类型 描述
    start_ts Number 搜索的时间范围起点。Unix 时间戳 （秒）。
    end_ts Number 搜索的时间范围终点。Unix 时间戳（秒）。搜索的起止时间范围暂不支持跨天，如果有跨天的通话请分多次请求。
    call_id String 通话 ID，即通话的唯一标识。
    page_no Number (可选) 翻页序号，默认为 1。
    page_size Number (可选) 每页的用户通话数，默认每页最多 20 个。
    uids String (可选) 请求的用户 uid 列表，多个 uid 用逗号隔开（如 uids=10001,10002,10003），最多可以指定 10 个 uid。用户 ID 根据实际的场景会存在复用的情况，如果请求指定 10 个 uid，那么返回的用户通话数会大于等于 10。
    appid String 你的项目使用的 App ID。
    exclude_server_user Boolean （可选）是否排除 Linux 用户。默认为 true，表示排除 Linux 用户。

    HTTP 请求示例

    GET /beta/analytics/call/sessions?start_ts=1548665345&end_ts=1548670821&appid=axxxxxxxxxxxxxxxxxxxx&call_id=cxxxxxxxxxxxxxxxxxxxx&page_no=1&page_size=20&uids=uxx1,uxx2 HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    响应示例

    {
    "code": 200,
    "message": "",
      "total_size": 101,
    "page_no": 1,
    "page_size": 20,
    "call_info": [
        {
            "sid": "EDB224CCF4FB4F99815C24302BDF3301",
            "cname": "15056678066620",
            "uid": 630985881,
            "network": "Wi-Fi",
            "platform": "Android",
            "speaker": true,
            "sdk_version": "2.2.0.07_14",
            "device_type": "Android (6.0)",
            "join_ts": 1548670251,
            "leave_ts": 1548670815,
            "finished": true
        },
        ......
        ]
}
    • code: Number 类型，响应状态码。200 表示请求成功，详见状态码。
    • message: String 类型，错误消息。
    • total_size: Number 类型，返回的用户通话总数。
    • page_no: Number 类型，翻页序号。
    • page_size: Number 类型，每页的用户通话数。
    • call_info: JSONArray 类型，包含通话中各个用户的信息。最多返回 20 个用户通话，按照用户加入频道的时间降序排列。每个用户包含以下信息 ：
      • sid: String 类型，用户通话的唯一标识。
      • cname: String 类型，频道名称。
      • uid: Number 类型，用户 ID。
      • network: String 类型，网络类型。
      • platform: String 类型，平台信息。
      • speaker: Boolean 类型，用户在通话中是否发送音视频。
      • sdk_version: String 类型，SDK 版本信息。
      • device_type: String 类型，设备信息。
      • join_ts: Number 类型，用户加入频道的时间。Unix 时间戳（秒）。
      • leave_ts: Number 类型，用户离开频道的时间。Unix 时间戳（秒）。
      • finished: Boolean 类型，用户是否已离开频道。

    获取通话质量指标

    获取指定通话的质量指标数据。

    • 方法：GET
    • 接入点：/beta/analytics/call/metrics

    请求参数

    该 API 需要在 URL 中传入以下参数指定通话。

    参数 类型 描述
    start_ts Number 通话开始的时间。Unix 时间戳（秒）。
    end_ts Number 通话结束的时间。Unix 时间戳（秒）。
    appid String 你的项目使用的 App ID。
    call_id String 通话 ID，即通话的唯一标识。
    sids String 请求的用户通话 sid 列表。最多可以指定 20 个 sid，多个 sid 用逗号隔开，如 sids=SXXXXXXXXXXXXXXXX1,SXXXXXXXXXXXXXXXX2。

    HTTP 请求示例

    GET /beta/analytics/call/metrics?start_ts=1548665345&end_ts=1548670821&appid=axxxxxxxxxxxxxxxxxxxx&call_id=cxxxxxxxxxxxxxxxxxxxx&sids=sxxxxxxxxxxxxxxxx1,sxxxxxxxxxxxxxxxx2,sxxxxxxxxxxxxxxxx3 HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    响应示例

    {
    "code": 200,
    "message": "",
    "metrics": [
        {
            "sid": "EDB224CCF4FB4F99815C24302BDF3301",
            "data": [
                {
                    "mid": 20003,
                    "kvs": [
                        [
                            1548670255,
                            215
                        ],
                        [
                            1548670257,
                            129
                        ],
                        [
                            1548670259,
                            121
                        ],
                        ......
                    ],
                    "peer_uid": 0,
                },
                ......
            ]
        },
......
]
}
    • code: Number 类型，响应状态码。200 表示请求成功，详见状态码。
    • message: String 类型，错误消息。
    • metrics: JSONArray 类型，各个用户通话（sid）的具体指标数据。每个用户通话包含以下信息：
      • sid: String 类型，用户在该通话中的唯一标识。
      • data: Array 类型，用户通话的质量指标数据。
      • mid: Number 类型，指标 ID，详见 指标 ID 表。
      • kvs: Array 类型，时间戳及相应时间的指标数值。
      • peer_uid: Number 类型，远端用户的 ID。如果为 0， 表示收到的是本地用户的指标数据。

    报告问题

    向 Agora 报告通话质量问题。

    • 方法：POST
    • 接入点：/beta/analytics/feedback/reportV2

    该方法每秒最多可调用 10 次。

    参数

    该 API 需要在 URL 中传入 appid 参数，你的项目使用的 App ID。

    该 API 需要在请求包体中传入以下参数。

    参数 类型 描述
    cname String 频道名称。
    teacher_uid Number 老师的用户 ID。
    student_uid Number 学生的用户 ID。
    abnormal_uid Number 体验异常端（老师或学生）的用户 ID。
    ts Number 问题发生时间，UNIX 时间戳，单位为秒。
    comments String （可选）备注。可以简单描述问题。
    type Number 问题类型：
  • 1: 切课
  • 2: 求助
  • 3: 投诉
  • 4: 问题反馈
    		•

    HTTP 请求示例

    POST /beta/analytics/feedback/reportV2?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: api.agora.io
Content-type: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
Cache-Control: no-cache

{ 
    "cname":"android_video_engine_1561704454355",
    "teacher_uid":111,
    "comments":"bad network",
    "ts":1581387571,
    "type":1,
    "student_uid":222,
    "abnormal_uid":222
}

    响应示例

    {
"code": 200,
"message": "",
}
    • code: Number 类型，响应状态码。200 表示请求成功，详见状态码。
    • message: String 类型，错误消息。

    参考

    状态码

    下表中的状态码适用于所有水晶球 RESTful API：

    状态码 描述
    200 请求处理成功
    400 参数错误
    401 未经授权
    403 授权信息错误，禁止访问
    404 API 调用错误
    500 未知错误

    以下状态码仅适用于通话调查 RESTful API：

    • 300: 超出 API 调用限制。返回该状态码时，可能会返回以下错误信息：
      • qps limit error：每秒的请求次数超出限制。
      • qpd limit error：每天的请求次数超出限制。
      • query latency limit error：数据延迟超出限制。
      • query time range limit error：可查询时间范围超出限制。
      • query time length limit error：响应内容中每次最多返回的数据超出限制。
      • no auth：当前套餐包不支持调用该 API。

    指标 ID 表

    mid 描述
    20001 App 的 CPU 使用率
    20002 系统 CPU 使用率
    20003 音频发送码率，单位 Kbps
    20004 音频接收码率，单位 Kbps
    20005 音频渲染卡顿时间，单位 ms
    20006 视频小流发送码率，单位 Kbps
    20007 视频采集帧率，单位 fps
    20008 视频大流发送帧率，单位 fps
    20009 视频接收码率，单位 Kbps
    20010 视频接收帧率，单位 fps
    20011 视频渲染卡顿时间，单位 ms
    20013 视频的画面质量，该数值越低表示画面越清晰
    20015 音频上行丢包率
    20016 音频端到端丢包率
    20017 视频上行丢包率
    20018 视频端到端丢包率
    20019 视频接收分辨率的宽
    20020 视频接收分辨率的高
    20021 SDK 任务调度延迟，单位 ms
    20022 客户端到本地路由器的往返时延，单位 ms
    20023 视频小流发送帧率，单位 fps
    20024 视频大流发送码率，单位 Kbps
    20025 采集音量
    20026 播放音量
    20027 视频发送分辨率的宽
    20028 视频发送分辨率的高

    体验 ID 映射表

    exp_id 描述
    4 视频卡顿
    5 音频卡顿
    6 进频道慢

    根因 ID 映射表

    factor_id 描述
    1 相同 UID 互踢
    2 管理员踢出
    3 连接异常
    8 视频下行网络延时
    9 音频下行网络延时
    10 CPU 占用高
    11 设备繁忙
    12 用户停止发送本地音频流
    13 用户停止发送本地视频流
    14 用户关闭音频模块
    15 用户关闭视频模块
    16 远端用户停止接收本地用户的音频流
    17 远端用户停止接受本地用户的视频流
    21 视频上行网络丢包
    22 音频上行网络丢包
    23 视频下行网络丢包
    24 音频下行网络丢包
    25 Electron 集成
    29 Wi-Fi（包含热点）信号差
    30 用户被踢出频道
    31 APP ID 无效，导致加频道失败
    32 频道名称无效，导致加频道失败
    33 Token 无效，导致加频道失败
    34 Token 过期，导致加频道失败
    35 用户被拦截，导致加频道失败
    36 加入频道超时
    37 网络中断，触发网络重连
    38 设置代理，触发网络重连
    39 Token 更新，触发网络重连
    40 用户 IP 变更，触发网络重连
    41 连接网络超时，触发网络重连
    42 视频上行网络延时
    43 音频上行网络延时
    44 视频上行网络抖动
    45 音频上行网络抖动
    46 视频下行网络抖动
    47 音频下行网络抖动