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

水晶球 RESTful API

更新时间 2023/03/29 09:56:46

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

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

使用水晶球 RESTful API 需要订阅套餐包，详见计费说明。

认证

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

数据格式

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

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

通话调查

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

API 限制

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

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

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

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

    获取频道通话列表

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

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

    查询参数

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

    参数 类型 描述
    start_ts Number 搜索的时间范围起点。Unix 时间戳 （秒）。
    end_ts Number 搜索的时间范围终点。Unix 时间戳（秒）。
    cname String (可选) 频道名称。
    appid String 你的项目使用的 App ID。
    page_no Number (可选) 翻页序号，默认为 1。
    page_size Number (可选) 每页的用户通话数，默认为每页 20 个，最大不能超过 100。如果指定的值超过 100，每页的用户通话数最多仍为 100 个。

    HTTP 请求示例

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

    响应示例

    {
    "code": 200,
    "message": "",
    "requestId": "bxxxxxxxxxxxxxxxxxx4",
    "total_size": 101,
    "page_no": 1,
    "page_size": 20,
    "has_more": false,
    "call_lists": [
        {
            "call_id": "cxxxxxxxxxxxxxxxxxxxx",
            "cname": "cname1",
            "created_ts": 1547448383,
            "destroyed_ts": 1547448483,
            "finished": true
        }
    ]
}
    • code: Number 类型，响应状态码。200 表示请求成功，详见状态码。
    • message: String 类型，错误消息。
    • requestId: String 类型，对应请求的 ID。
    • total_size: Number 类型，返回的用户通话总数。
    • page_no: Number 类型，翻页序号。
    • page_size: Number 类型，每页的用户通话数。
    • has_more: Boolean 类型，是否还有通话未列出。如果为 true，表示符合查询条件的通话没有在 call_lists 中全部列出。如果你要查找的通话未列出，请修改查询条件重新发送请求。
    • call_lists: JSONArray 类型，返回的通话，按通话开始时间降序排列。每个通话中包含以下信息：
      • 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 个，最大不能超过 100。如果指定的值超过 100，每页的用户通话数最多仍为 100 个。
    如果需要实现翻页，必须同时指定 page_no 和 page_size 的值。
    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": "",
    "requestId": "bxxxxxxxxxxxxxxxxxx4",
    "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 类型，错误消息。
    • requestId: String 类型，对应请求的 ID。
    • total_size: Number 类型，返回的用户通话总数。
    • page_no: Number 类型，翻页序号。
    • page_size: Number 类型，每页的用户通话数。
    • call_info: JSONArray 类型，包含通话中各个用户的信息，按照用户加入频道的时间降序排列。每个用户包含以下信息 ：
      • 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": "",
  "requestId": "bxxxxxxxxxxxxxxxxxx4",
  "metrics": [
      {
          "sid": "EDB224CCF4FB4F99815C24302BDF3301",
          "data": [
              {
                  "mid": 20003,
                  "kvs": [
                      [
                          1548670255,
                          215
                      ],
                      [
                          1548670257,
                          129
                      ],
                      [
                          1548670259,
                          121
                      ]
                  ],
                  "peer_uid": 0
              }
          ]
      }
  ]
}
    • code: Number 类型，响应状态码。200 表示请求成功，详见状态码。
    • message: String 类型，错误消息。
    • requestId: String 类型，对应请求的 ID。
    • metrics: JSONArray 类型，各个用户通话（sid）的具体指标数据。每个用户通话包含以下信息：
      • sid: String 类型，用户在该通话中的唯一标识。
      • data: Array 类型，用户通话的质量指标数据。
      • mid: Number 类型，指标 ID，详见 指标 ID 表。
      • kvs: Array 类型，时间戳及相应时间的指标数值。
      • peer_uid: Number 类型，远端用户的 ID。如果为 0， 表示收到的是本地用户的指标数据。

    数据洞察

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

    API 限制

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

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

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

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

    查询时序用量指标

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

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

    查询参数

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

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

    HTTP 请求示例

    以按天查询通话人数为例，startTs 为 2021 年 7 月 1 日早上 8 点，endTs 为 2021 年 7 月 3 日早上 8 点（UTC 时间），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

    响应参数

    参数 类型 描述
    code Number 响应状态码。200 表示请求成功，详见状态码。
    message String 错误消息。
    data JSONArray 由指标数据值和 Unix 时间戳组成的数组。
  • userCount: 请求的指标名称，此处示例为通话人数。
  • ts: Unix 时间戳 （秒）。
    		•

    响应示例

    包含 2 组数据，分别为按 UTC 时间结算的 7 月 2 日的通话人数与 7 月 3 日的通话人数，时间戳为 7 月 2 日零点与 7 月 3 日零点。

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

    查询时序质量指标

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

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

    查询参数

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

    参数 类型 描述
    startTs Number 查询的时间范围起点，Unix 时间戳 （秒）。
    endTs 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 平台的声网 RTC SDK。
  • WebRTC：指 Web 平台的声网 RTC SDK。
    		•

    HTTP 请求示例

    以按小时查询络延迟率为例，startTs 为 2021 年 7 月 1 日早上 8 点，endTs 为 2021 年 7 月 2 日早上 8 点（UTC 时间），HTTP 请求如下：

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

    响应参数

    参数 类型 描述
    code Number 响应状态码。200 表示请求成功，详见状态码。
    message String 错误消息。
    data JSONArray 由指标数据值和 Unix 时间戳组成的数组。
  • networkDelay: 请求的指标名称，此处示例为网络延迟率。
  • ts: Unix 时间戳 （秒）。
    		•

    响应示例

    包含 25 组数据，均按 UTC 时间结算，其中第一组数据对应 7 月 1 日早上 8 点的网络延迟率，第二组数据对应 7 月 1 日早上 9 点的网络延迟率，依此类推。最后一组数据对应 7 月 2 日早上 8 点的网络延迟率。

    {
    "code": 200,
    "message": "success",
    "data": [
        {
            "networkDelay": 0.064762,
            "ts": 1625097600
        },
        {
            "networkDelay": 0.028156,
            "ts": 1625101200
        },
        ...
        {
            "networkDelay": 0.03765,
            "ts": 1625184000
        }
   ]
}

    查询聚合用量指标

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

    • 方法：POST
    • 接入点：/beta/insight/usage/aggregation

    查询参数

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

    参数 类型 描述
    appid String 你的项目使用的 App ID。

    请求包体

    你需要在请求包体传入以下参数：

    参数 类型 描述
    startTs Number 查询的时间范围起点，Unix 时间戳 （秒）。
    endTs Number 查询的时间范围终点，Unix 时间戳 （秒）。
    metric String 要查询的指标，支持设为以下值：
  • userCount：通话人数，一个用户 ID 在一个频道中计为一人，在多个频道中计为多人。
  • sessionCount：通话进出人次，用户每加入一次频道计为一个通话人次。
  • channelCount：频道数，从有用户加入频道到所有用户离开频道计为一个通话频道。
  • peakConcurrentChannels：最大同时在线频道数。
  • peakConcurrentUsers：最大同时在线人数。
  • totalDuration：音视频通话时长（分钟）。
  • totalVideoDuration：视频通话时长（分钟）。
  • totalAudioDuration：音频通话时长（分钟）。
    		•
    dimension String （可选）统计维度，仅支持单维度指定。支持设为以下值：
  • country：国家。
  • region：地区。
  • network：网络类型。
  • sdkVersion：SDK 版本。
  • os：操作系统。
  • device：设备型号。
    • 设置该参数后，将默认返回对应维度中 TOP 20 的值（仅 device 维度返回 TOP 50 的值）。
    当 metric 为 peakConcurrentUsers 或 peakConcurrentChannels 时，不支持传 dimension 和 dimensionValues，仅返回 App ID 维度的聚合结果。
    dimensionValues String （可选）统计维度的值 ，即对 dimension 中设定的维度指定取值，仅在传入 dimension 时有效。所有值必须用双引号包括，并以逗号分隔。设置该参数后，将返回 dimensionValues 中传入的值对应的聚合指标数据。
    你可以在首次请求时，通过不传 dimensionValues 来获取当前 dimension 下的 TOP 值，再根据业务需要从中选取几个值，来作为下次请求时传入 dimensionValues 的值。
    filters JSONArray （可选）地区筛选器，仅在 dimension 为 region 时生效，用于从地区维度的返回结果中筛选出属于指定国家的结果。包含以下属性：
  • name：String。仅支持传入 country。
  • value：String。需要筛选的国家，仅支持传入一个国家值。
    		•

    HTTP 请求示例

    以查询 startTs 为 2021 年 7 月 1 日早上 8 点，endTs 为 2021 年 7 月 2 日早上 8 点（UTC 时间）区间内的通话为例，HTTP 请求如下：

    示例 1：请求查询通话人数 TOP 20 的国家和各国通话人数

    POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

{
    "startTs": 1625097600,        
    "endTs": 1625184000,        
    "metric": "userCount",    
    "dimension": "country"
}

    示例 2：请求查询 SDK 版本为 "3.6.1.1" 和 "4.1.1" 的通话人数

    POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

{
    "startTs": 1625097600,        
    "endTs": 1625184000,         
    "metric": "userCount",    
    "dimension": "sdkVersion",
    "dimensionValues":["3.6.1.1","4.1.1"]
}

    示例 3：请求查询中国通话人数 TOP 20 的地区和这些地区的通话人数

    POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

{
    "startTs": 1625097600,        
    "endTs": 1625184000,           
    "metric": "userCount",    
    "dimension": "region",
    "filters": [{"name": "country", "value": "China"}]
}

    响应参数

    HTTP 响应中会返回以下参数：

    参数 类型 描述
    code Number 响应状态码。200 表示请求成功，详见状态码。
    message String 错误消息。
    data JSONArray
  • 请求中没有填入 dimension 字段：返回 App ID 维度的指标数据。
  • 请求中填入了 dimension 字段：由维度和指标数据组成的数组。
    		•

    响应示例

    示例 1：请求查询通话人数 TOP 20 的国家和各国通话人数

    包含 20 组数据，分别为 2021 年 7 月 1 日早上 8 点到 2021 年 7 月 2 日早上 8 点各国家的总通话人数 TOP 20。

    {
    "code": 200,
    "message": "null",
    "data": [
        {
            "country": "China",
            "userCount": 42,
        },
        {
            "country": "United States",
            "userCount": 37
        }
        ......
   ]
}

    示例 2：请求查询 SDK 版本为"3.6.1.1" 和 "4.1.1" 的通话人数

    包含 2 组数据，分别为 2021 年 7 月 1 日早上 8 点到 2021 年 7 月 2 日早上 8 点 SDK 版本为 "3.6.1.1" 和 "4.1.1" 的总通话人数。

    {
    "code": 200,
    "message": "null",
    "data": [
        {
            "sdkVersion": "3.6.1.1",
            "userCount": 42,
        },
        {
            "sdkVersion": "4.1.1",
            "userCount": 37
        }
   ]
}

    示例 3：请求查询中国通话人数 TOP 20 的地区和这些地区的通话人数

    包含 20 组数据，分别为 2021 年 7 月 1 日早上 8 点到 2021 年 7 月 2 日早上 8 点中国各地区的总通话人数 TOP 20。

    {
    "code": 200,
    "message": "null",
    "data": [
        {
            "region": "Shanghai",
            "userCount": 42,
        },
        {
            "region": "Beijing",
            "userCount": 37
        }
        ......
   ]
}

    查询聚合质量指标

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

    • 方法：POST
    • 接入点：/beta/insight/quality/aggregation

    查询参数

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

    参数 类型 描述
    appid String 你的项目使用的 App ID。

    请求包体

    你需要在请求包体传入以下参数：

    参数 类型 描述
    startTs Number 查询的时间范围起点，Unix 时间戳 （秒）。
    endTs Number 查询的时间范围终点，Unix 时间戳 （秒）。
    metric String 要查询的指标，支持设为以下值：
  • joinSuccessRate：加入频道成功率。
  • joinSuccessIn5sRate：5s 内加入频道成功率。
  • audioFreezeRate：音频卡顿率。
  • videoFreezeRate：视频卡顿率。
  • networkDelay ：网络延迟率。
    		•
    productType String 要查询的产品类型，支持设为以下值：
  • Native：指 Android、iOS、macOS、Windows 平台的声网 RTC SDK。
  • WebRTC：指 Web 平台的声网 RTC SDK。
    		•
    dimension String （可选）统计维度，仅支持单维度指定。支持设为以下值：
  • country：国家。
  • region：地区。
  • network：网络类型。
  • sdkVersion：SDK 版本。
  • os：操作系统。
  • device：设备型号。
  • channelSize：频道规模。
    • 设置该参数后，将默认返回对应维度中 TOP 20 的值（仅 device 维度返回 TOP 50 的值）。
    dimensionValues JSONArray （可选）统计维度的值 ，即对 dimension 中设定的维度指定取值，仅在传入 dimension 时有效。所有值必须用双引号包括，并以逗号分隔。设置该参数后，将返回 dimensionValues 中传入的值对应的聚合指标数据。
    你可以在首次请求时，通过不传 dimensionValues 来获取当前 dimension 下的 TOP 值，再根据业务需要从中选取几个值，来作为下次请求时传入 dimensionValues 的值。
    仅 dimension 为 channelSize 时不支持传 dimensionValues，将返回以预设的梯度规模分组的结果。
    filters JSONArray （可选）地区筛选器，仅在 dimension 为 region 时生效，用于从地区维度的返回结果中筛选出属于指定国家的结果。包含以下属性：
  • name：String。仅支持传入 country。
  • value：String。需要筛选的国家，仅支持传入一个国家值。
    		•

    HTTP 请求示例

    以查询 startTs 为 2021 年 7 月 1 日早上 8 点，endTs 为 2021 年 7 月 2 日早上 8 点（UTC 时间）的通话为例，HTTP 请求如下：

    示例 1：请求查询音频卡顿率 TOP 20 的国家和各国音频卡顿率

    POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

{
    "startTs": 1625097600,        
    "endTs": 1625184000,        
    "metric": "audioFreezeRate",    
    "dimension": "country"
}

    示例 2：请求查询 SDK 版本为"3.6.1.1" 和 "4.1.1" 的音频卡顿率

    POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

{
    "startTs": 1625097600,        
    "endTs": 1625184000,         
    "metric": "audioFreezeRate",    
    "dimension": "sdkVersion",
    "dimensionValues":["3.6.1.1","4.1.1"]
}

    示例 3：请求查询音频卡顿率 TOP 20 的中国地区和各地区音频卡顿率

    POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

{
    "startTs": 1625097600,        
    "endTs": 1625184000,           
    "metric": "audioFreezeRate",    
    "dimension": "region",
    "filters": [{"name": "country", "value": "China"}]
}

    响应参数

    HTTP 响应中会返回以下参数：

    参数 类型 描述
    code Number 响应状态码。200 表示请求成功，详见状态码。
    message String 错误消息。
    data JSONArray
    • 请求中没有填入 dimension 字段：返回 App ID 维度的指标数据。
    • 请求中填入了 dimension 字段：由维度、refUsage 和指标数据组成的数组。
      • refUsage：辅助用量数据。每组返回数据中，每个 metric 将对应返回一个辅助用量数据，用于辅助判断数据的有效性。以下为 metric 和 refUsage 对应关系：
        • metric 为 joinSuccessRate 时，refUsage 表示尝试加入频道次数。
        • metric 为 joinSuccessIn5sRate 时，refUsage 表示尝试加入频道次数。
        • metric 为 audioFreezeRate 时，refUsage 表示音频通话时长（分钟）。
        • metric 为 videoFreezeRate 时，refUsage 表示视频通话时长（分钟）。
        • metric 为 networkDelay 时，refUsage 表示音视频总通话时长（分钟）。

      响应示例

      示例 1：请求查询音频卡顿率 TOP 20 的国家和各国音频卡顿率

      包含 20 组数据，分别为 2021 年 7 月 1 日早上 8 点到 2021 年 7 月 2 日早上 8 点各国家通话的音频卡顿率 TOP 20。

      {
    "code": 200,
    "message": "null",
    "data": [
        {
            "country": "China",
            "refUsage": 231234,
            "audioFreezeRate": 0.0017,
        },
        {
            "country": "United States",
            "refUsage": 213212,
            "audioFreezeRate": 0.0014
        }
        ......
   ]
}

      示例 2：请求查询 SDK 版本为"3.6.1.1" 和 "4.1.1" 的音频卡顿率

      包含 2 组数据，分别为 2021 年 7 月 1 日早上 8 点到 2021 年 7 月 2 日早上 8 点 SDK 版本为 "3.6.1.1" 和 "4.1.1" 的音频卡顿率。

      {
    "code": 200,
    "message": "null",
    "data": [
        {
            "sdkVersion": "3.6.1.1",
            "refUsage": 231234,
            "audioFreezeRate": 0.0017,
        },
        {
            "sdkVersion": "4.1.1",
            "refUsage": 213212,
            "audioFreezeRate": 0.0014
        }
   ]
}

      示例 3：请求查询音频卡顿率 TOP 20 的中国地区和各地区音频卡顿率

      包含 20 组数据，分别为 2021 年 7 月 1 日早上 8 点到 2021 年 7 月 3 日早上 8 点中国各地区通话的音频卡顿率 TOP 20。

      {
    "code": 200,
    "message": "null",
    "data": [
        {
            "region": "Shanghai",
            "refUsage": 231234,
            "audioFreezeRate": 0.0017,
        },
        {
            "region": "Beijing",
            "refUsage": 213212,
            "audioFreezeRate": 0.0014
        }
        ......
   ]
}

      实时监控

      实时监控 RESTful API 用于查询指定时间范围内 App ID 级别的规模和质量数据。返回数据的粒度达到秒级别，几乎可以实时地反映项目情况。

      在返回结果中，指定的时间范围会被划分为多个时间窗口。时间窗口从 00:00:00 开始计算，每 20 秒为一个时间窗口。

      API 限制

      实时监控 RESTful API 的调用限制取决于你订阅的水晶球套餐包。

      专业版、旗舰版套餐包在实时监控 RESTful API 的调用限制方面有以下区别：

      专业版 旗舰版
      请求次数 每分钟 3 次，每天 480 次 每分钟 10 次，每天 1440 次
      可查询时间范围 最近 40 分钟 最近 60 分钟
      单次查询时间范围 40 分钟 60 分钟
      数据延迟 40 秒 20 秒
      请求次数的计算以服务器的 UTC 时间为准。

      查询实时规模

      获取实时的通话人数和频道数。

      • 方法：GET
      • 接入点：/beta/realtime/usage/by_time_20sec

      查询参数

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

      参数 类型 描述
      startTs Number 查询的时间范围起点，Unix 时间戳 （秒）。响应中会包含起点所在的时间窗口。
      endTs Number 查询的时间范围终点，Unix 时间戳 （秒）。响应中不会包含终点所在的时间窗口。
      appid String 你的项目使用的 App ID。
      productType String 要查询的产品类型，支持设为以下值：
    • Native：指 Android、iOS、macOS、Windows 平台的声网 RTC SDK。
    • WebRTC：指 Web 平台的声网 RTC SDK。
      		•
      metric String 要查询的指标，支持设为以下值：
    • userCount：通话人数，一个用户 ID 在一个频道中计为一人，在多个频道中计为多人。
    • channelCount：频道数，从有用户加入频道到所有用户离开频道计为一个通话频道。
      		•
      dimension String （可选）统计维度，仅支持单维度指定。仅在 metric 为 userCount 时生效。支持设为以下值：
    • country：国家。
    • region：地区。
    • net：网络类型。
    • sdk：SDK 版本。
    • os：操作系统。
    • device：设备型号。
      • 你可以通过获取实时规模 TOP 20 分组获取当前 dimension 下的 TOP 值，再根据业务需要从中选取几个值，来作为下次请求时传入 dimensionValues 的值。
      dimensionValues String （可选）统计维度的值 ，即对 dimension 中设定的维度指定取值，仅在传入 dimension 时有效。所有值必须用双引号包括，并以逗号分隔。
      cname String （可选）频道名称。如果不填，代表查询该项目的整体指标。

      请求示例

      以查询 SDK 版本为 "3.6.1.1" 和 "4.1.1" 的实时通话人数为例，其中 startTs 为 2021 年 9 月 17 日 08:10:10，endTs 为 2021 年 9 月 17 日 08:11:10 ，HTTP 请求如下：

      GET /beta/realtime/usage/by_time_20sec?startTs=1631837410&endTs=1631837470&appid=your_app_id&productType=Native&metric=userCount&dimension=sdk&dimensionValues="3.6.1.1","4.1.1" HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

      响应参数

      HTTP 响应中会返回以下参数：

      参数 类型 描述
      code Number 响应状态码。200 表示请求成功，详见状态码。
      message String 错误消息。
      data JSONArray 由指标数据、维度和 Unix 时间戳（秒）组成的数组。

      响应示例

      由于请求查询 2021 年 9 月 17 日 08:10:10 到 2021 年 9 月 17 日 08:11:10 区间内的通话人数，响应中返回的 data 数组包含 3 组数据：

      • 2021 年 9 月 17 日 00:10:00 – 00:10:20 的通话人数、对应 SDK 版本和 Unix 时间戳。
      • 2021 年 9 月 17 日 00:10:20 – 00:10:40 的通话人数、对应 SDK 版本和 Unix 时间戳。
      • 2021 年 9 月 17 日 00:10:40 – 00:11:00 的通话人数、对应 SDK 版本和 Unix 时间戳。

      其中的 Unix 时间戳为对应时间窗口的起始时间。

      {
    "code": 200,
    "message": null,
    "data": [
        {
            "userCount": 236,
            "sdk": "3.6.1.1",
            "ts": 1631837400
        },
        {
            "userCount": 82,
            "sdk": "4.1.1",
            "ts": 1631837400
        },
        {
            "userCount": 235,
            "sdk": "3.6.1.1",
            "ts": 1631837420
        },
        {
            "userCount": 85,
            "sdk": "4.1.1",
            "ts": 1631837420
        },
        {
            "userCount": 252,
            "sdk": "3.6.1.1",
            "ts": 1631837440
        },
        {
            "userCount": 90,
            "sdk": "4.1.1",
            "ts": 1631837440
        }
    ]
}

      查询实时质量

      获取实时的加入频道成功率、5s 加入频道成功率、音频卡顿率、视频卡顿率、网络延迟率。

      • 方法：GET
      • 接入点：/beta/realtime/quality/by_time_20sec

      查询参数

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

      参数 类型 描述
      startTs Number 查询的时间范围起点，Unix 时间戳 （秒）。响应中会包含起点所在的时间窗口。
      endTs Number 查询的时间范围终点，Unix 时间戳 （秒）。响应中不会包含终点所在的时间窗口。
      appid String 你的项目使用的 App ID。
      productType String 要查询的产品类型，支持设为以下值：
    • Native：指 Android、iOS、macOS、Windows 平台的声网 RTC SDK。
    • WebRTC：指 Web 平台的声网 RTC SDK。
      		•
      metric String 要查询的指标，支持设为以下值：
    • joinSuccessRate：加入频道成功率。
    • joinSuccessIn5sRate：5s 内加入频道成功率。
    • audioFreezeRate：音频卡顿率。
    • videoFreezeRate：视频卡顿率。
    • networkDelay ：网络延迟率。
      		•
      dimension String （可选）统计维度，仅支持单维度指定。仅在 metric 为 userCount 时生效。支持设为以下值：
    • country：国家。
    • region：地区。
    • net：网络类型。
    • sdk：SDK 版本。
    • os：操作系统。
    • device：设备型号。
      • 你可以通过获取实时质量 TOP 20 分组获取当前 dimension 下的 TOP 值，再根据业务需要从中选取几个值，来作为下次请求时传入 dimensionValues 的值。
      dimensionValues String （可选）统计维度的值 ，即对 dimension 中设定的维度指定取值，仅在传入 dimension 时有效。所有值必须用双引号包括，并以逗号分隔。
      cname String （可选）频道名称。如果不填，代表查询该项目的整体指标。
      uids String （可选）请求的用户 uid 列表，多个 uid 用逗号隔开（如 uids=10001,10002,10003），最多可以指定 10 个 uid。
      如果填写了 uids 字段，请确保 cname 字段不为空，否则 uids 字段不生效。

      请求示例

      以查询网络延迟率为例，其中 startTs 为 2021 年 9 月 17 日 08:10:10，endTs 为 2021 年 9 月 17 日 08:11:10 ，HTTP 请求如下：

      示例 1：请求中不填 uids 字段

      GET /beta/realtime/quality/by_time_20sec?startTs=1631837410&endTs=1631837470&appid=axxxxxxxxxxxxxxxxxxxx&productType=Native&metric=networkDelay HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

      示例 2：请求中指定 uid 为 2303692334 和 2963430861

      GET /beta/realtime/quality/by_time_20sec?startTs=1631837410&endTs=1631837470&appid=axxxxxxxxxxxxxxxxxxxx&productType=Native&metric=networkDelay&cname=demoChannel&uids=2303692334,2963430861 HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

      示例 3：请求中指定 dimension 为 sdkVersion，dimensionValues 为 "3.6.1.1" 和 "4.1.1"

      GET /beta/realtime/quality/by_time_20sec?startTs=1631837410&endTs=1631837470&appid=your_app_id&productType=Native&metric=networkDelay&dimension=sdk&dimensionValues="3.6.1.1","4.1.1" HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

      响应参数

      HTTP 响应中会返回以下参数：

      参数 类型 描述
      code Number 响应状态码。200 表示请求成功，详见状态码。
      message String 错误消息。
      data JSONArray
    • 请求中没有填入 uids 字段：由指标数据和 Unix 时间戳（秒）组成的数组。
    • 请求中填入了 uids 字段：由 uid、指标数据、Unix 时间戳（秒）组成的数组。
    • 请求中填入了 dimension 和 dimensionValues 字段：由指标数据、维度和 Unix 时间戳（秒）组成的数组。
      		•

      响应示例

      由于请求查询 2021 年 9 月 17 日 08:10:10 到 2021 年 9 月 17 日 08:11:10 区间内的通话人数，返回的 data 数组包含 3 组数据：

      • 2021 年 9 月 17 日 00:10:00 – 00:10:20 的网络延迟率和 Unix 时间戳。
      • 2021 年 9 月 17 日 00:10:20 – 00:10:40 的网络延迟率和 Unix 时间戳。
      • 2021 年 9 月 17 日 00:10:40 – 00:11:00 的网络延迟率和 Unix 时间戳。

      其中的 Unix 时间戳为对应时间窗口的起始时间。

      示例 1：请求中不填 uids 字段

      {
    "code": 200,
    "message": "success",
    "data": [
        {
            "networkDelay": 0.0120,
            "ts": 1631837400
        },
        {
            "networkDelay": 0.0057,
            "ts": 1631837420
        },
        {
            "networkDelay": 0.0039,
            "ts": 1631837440
        }
    ]
}

      示例 2：请求中指定 uid 为 2303692334 和 2963430861

      {
    "code": 200,
    "message": "success",
    "data": [
        {
            "uid": 2303692334,
            "values": [
                {
                    "ts": 1631837400,
                    "networkDelay": 0.389
                },
                {
                    "ts": 1631837420,
                    "networkDelay": 0.389
                },
                {
                    "ts": 1631837440,
                    "networkDelay": 0.389
                }
            ]
        },
        {
            "uid": 2963430861,
            "values": [
                {
                    "ts": 1631837400,
                    "networkDelay": 0.389
                },
                {
                    "ts": 1631837420,
                    "networkDelay": 0.389
                },
                {
                    "ts": 1631837440,
                    "networkDelay": 0.389
                }
            ]
        }
    ]
}

      示例 3：请求中指定 dimension 为 sdkVersion，dimensionValues 为 "3.6.1.1" 和 "4.1.1"

      {
    "code": 200,
    "message": null,
    "data": [
        {
            "networkDelay": 0.389,
            "sdk": "3.6.1.1",
            "ts": 1631837400
        },
        {
            "networkDelay": 0.411,
            "sdk": "4.1.1",
            "ts": 1631837400
        },
        {
            "networkDelay": 0.343,
            "sdk": "3.6.1.1",
            "ts": 1631837420
        },
        {
            "networkDelay": 0.363,
            "sdk": "4.1.1",
            "ts": 1631837420
        },
        {
            "networkDelay": 0.511,
            "sdk": "3.6.1.1",
            "ts": 1631837440
        },
        {
            "networkDelay": 0.436,
            "sdk": "4.1.1",
            "ts": 1631837440
        }
    ]
}

      查询实时规模 TOP 20 分组

      获取指定维度下实时的通话人数的 TOP 20 分组数据；为查询实时规模接口的 dimensionValues 参数提供内容输入。

      • 方法：GET

        接入点：/beta/realtime/usage/dimension/top20

      查询参数

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

      参数 类型 描述
      ts Number 查询的时间范围起点，Unix 时间戳 （秒）。实际查询范围为 [ts, ts + 20s ]。
      appid String 你的项目使用的 App ID。
      productType String 要查询的产品类型，支持设为以下值：
    • Native：指 Android、iOS、macOS、Windows 平台的声网 RTC SDK。
    • WebRTC：指 Web 平台的声网 RTC SDK。
      		•
      metric String 要查询的指标，仅支持设为 userCount，即通话人数，一个用户 ID 在一个频道中计为一人，在多个频道中计为多人。
      dimension String 统计维度，仅支持单维度指定。支持设为以下值：
    • country：国家。
    • region：地区。
    • net：网络类型。
    • sdk：SDK 版本。
    • os：操作系统。
    • device：设备型号。
      • 将默认返回维度对应 TOP 20 的值（仅当 dimension 为 device 时，将默认返回 TOP 50 的值）。
      cname String （可选）频道名称。如果不填，代表查询该项目的整体指标。

      请求示例

      以查询 2021 年 9 月 17 日 08:10:10 起各 SDK 版本通话人数 TOP 20 数据，HTTP 请求如下：

      GET /beta/realtime/usage/dimension/top20?ts=1631837410&appid=your_app_id&productType=Native&metric=userCount&dimension=sdk HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

      响应参数

      HTTP 响应中会返回以下参数：

      参数 类型 描述
      code Number 响应状态码。200 表示请求成功，详见状态码。
      message String 错误消息。
      data JSONArray 由维度、指标数据和时间窗口的起止 Unix 时间戳（秒）组成的数组。

      响应示例

      包含 20 组数据，分别为 2021 年 9 月 17 日 08:10:10 至 08:10:30 范围内各 SDK 版本下通话人数的 TOP 20 数据。

      
{
    "code": 200,
    "message": null,
    "data": {
        "list": [
            {
                "sdk": "3.6.1.1",
                "userCount": 236,
                "windowStartTs": 1631837410,
                "windowEndTs": 1631837430
            },
            {
                "sdk": "4.1.1",
                "userCount": 82,
                "windowStartTs": 1631837410,
                "windowEndTs": 1631837430
            },
            {
                "sdk": "2.9.1",
                "userCount": 68,
                "windowStartTs": 1631837410,
                "windowEndTs": 1631837430
            },
            ...
        ]
    }
}

      查询实时质量 TOP 20 分组

      获取指定维度下的实时加入频道成功率、5s 加入频道成功率、音频卡顿率、视频卡顿率、网络延迟率 TOP 20 分组数据；为查询实时质量接口的 dimensionValues 参数提供内容输入。

      • 方法：GET

        接入点：/beta/realtime/quality/dimension/top20

      查询参数

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

      参数 类型 描述
      ts Number 查询的时间范围起点，Unix 时间戳 （秒）。实际查询范围为 [ts, ts + 20s ]。
      appid String 你的项目使用的 App ID。
      productType String 要查询的产品类型，支持设为以下值：
    • Native：指 Android、iOS、macOS、Windows 平台的声网 RTC SDK。
    • WebRTC：指 Web 平台的声网 RTC SDK。
      		•
      metric String 要查询的指标，支持设为以下值：
    • joinSuccessRate：加入频道成功率。
    • joinSuccessIn5sRate：5s 内加入频道成功率。
    • audioFreezeRate：音频卡顿率。
    • videoFreezeRate：视频卡顿率。
    • networkDelay ：网络延迟率。
      		•
      dimension String 统计维度，仅支持单维度指定。支持设为以下值：
    • country：国家。
    • region：地区。
    • net：网络类型。
    • sdk：SDK 版本。
    • os：操作系统。
    • device：设备型号。
      • 将默认返回维度对应 TOP 20 的值（仅当 dimension 为 device 时，将默认返回 TOP 50 的值）。
      extraMetrics String （可选）额外指标，用于辅助判断数据的有效性。仅支持设为 userCount，即当前维度下的用户数。

      请求示例

      以查询 2022 年 12 月 21 日 20:00:00 起各设备下音频卡顿率 TOP 50 数据，且传入 extraMetrics，HTTP 请求如下：

      GET /beta/realtime/quality/dimension/top20?ts=1671624000&appid=your_app_id&productType=Native&metric=audioFreezeRate&dimension=device&extraMetrics=userCount HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

      响应参数

      HTTP 响应中会返回以下参数：

      参数 类型 描述
      code Number 响应状态码。200 表示请求成功，详见状态码。
      message String 错误消息。
      data JSONArray 由维度、指标数据、当前维度下的用户数和时间窗口的起止 Unix 时间戳（秒）组成的数组。

      响应示例

      包含 50 组数据，分别为 2022 年 12 月 21 日 20:00:00 至 20:00:20 范围内各设备型号下的音频卡顿率 TOP 50 数据。

      {
    "code": 200,
    "message": null,
    "data": {
        "list": [
            {
                "audioFreezeRate": 0.050833333333333335,
                "windowStartTs": 1671624000,
                "userCount": 2,
                "device": "ldn-al00",
                "windowEndTs": 1671624020
            },
            {
                "audioFreezeRate": 0,
                "windowStartTs": 1671624000,
                "userCount": 2,
                "device": "80HH",
                "windowEndTs": 1671624020
            },
            {
                "audioFreezeRate": 0,
                "windowStartTs": 1671624000,
                "userCount": 1,
                "device": "20KNA004CD",
                "windowEndTs": 1671624020
            }
        ]
    }
}

      保障 REST 服务高可用

      为保障 REST 服务的高可用，避免因区域网络故障造成的服务不可用，声网提供切换域名的方案。

      切换域名操作

      1. 根据你的业务服务器所在地设置主域名：
        • 业务服务器 DNS 地址位于中国大陆时，设置主域名为 api.sd-rtn.com。
        • 业务服务器 DNS 地址位于中国大陆以外的国家或地区时，设置主域名为 api.agora.io。
      2. 当使用主域名发起 RESTful API 请求失败时，使用该域名重试一次。
      3. 如果步骤 2 的重试依然失败，使用备用的主域名重试：
        • 如果当前设置的主域名为 api.sd-rtn.com，备用的主域名指 api.agora.io。
        • 如果当前设置的主域名为 api.agora.io，备用的主域名指 api.sd-rtn.com。
      4. 如果步骤 3 的重试依然失败，使用与当前解析区域相邻的区域域名重试。
        举例说明：假设你的业务服务器位于欧洲，你设置主域名为 api.agora.io，而且业务服务器解析主域名解析到德国。德国位于欧洲中部 api-eu-central-1.agora.io，查域名信息表可知，相邻区域为欧洲西部 api-eu-west-1.agora.io 或 api-eu-west-1.sd-rtn.com。因此，出现网络故障且步骤 2、3 的重试失败时，请使用 api-eu-west-1.agora.io 或 api-eu-west-1.sd-rtn.com 域名重试。

      注意事项

      • 为避免重试请求过于频繁，超过声网服务所规定的 QPS（每秒请求数），声网建议你使用退避策略。例如，第一次等待 1 秒后重试、第二次等待 3 秒后重试、第三次等待 6 秒后重试。
      • 如果是网络问题而非 DNS 解析域名问题导致的请求失败，声网建议你跳过步骤 3，直接进行步骤 4。
      • 切换至区域域名前，请确保你使用的业务（例如，云端录制、云信令、频道管理等 REST 服务）在该区域有部署服务。

      域名信息

      主域名 区域域名 地理区域
      api.sd-rtn.com api-us-west-1.sd-rtn.com 美国西部
      api-us-east-1.sd-rtn.com 美国东部
      api-ap-southeast-1.sd-rtn.com 亚太东南
      api-ap-northeast-1.sd-rtn.com 亚太东北
      api-eu-west-1.sd-rtn.com 欧洲西部
      api-eu-central-1.sd-rtn.com 欧洲中部
      api-cn-east-1.sd-rtn.com 中国华东
      api-cn-north-1.sd-rtn.com 中国华北
      api.agora.io api-us-west-1.agora.io 美国西部
      api-us-east-1.agora.io 美国东部
      api-ap-southeast-1.agora.io 亚太东南
      api-ap-northeast-1.agora.io 亚太东北
      api-eu-west-1.agora.io 欧洲西部
      api-eu-central-1.agora.io 欧洲中部
      api-cn-east-1.agora.io 中国华东
      api-cn-north-1.agora.io 中国华北

      参考

      状态码

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

      返回状态码 300 时，可能会返回以下错误信息：

      错误信息 描述 正确示例
      qps limit error 每秒的请求次数超出限制 如果 qps limit = 10，则 current qps < 10
      qpm limit error 每分钟的请求次数超出限制 如果 qpm limit = 100，则 current qpm < 100
      qpd limit error 每天的请求次数超出限制 如果 qpd limit = 10000，则 current qpd < 10000
      query latency limit error 数据延迟超出限制 如果 query latency limit = 10s， current time = 1623316864，则 end_ts < 1623316864 - 10
      query time range limit error 可查询时间范围超出限制 如果 query time range limit = 3d，current time = 1623316864，则 start_ts > 1623316864 - 3 * 86400(s)
      query duration limit error 单次查询时间范围超出限制 如果 query duration = 8h，则 end_ts -start_ts < 8 * 3600(s)
      query time length limit error 响应内容中每次最多返回的数据超出限制 如果 query time length limit = 3h，则 end_ts -start_ts < 3 * 3600(s)
      you have no auth to access this service, please buy or upgrade your service package 当前套餐包不支持调用该 API 无

      指标 ID 表

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