You need to enable JavaScript to run this app.
导航
企业直播
  • 文档首页
    • /
  • 企业直播

获取主账号下的直播间实时统计数据

最近更新时间：2024.04.23 14:26:57

首次发布时间：2023.11.23 14:40:38

我的收藏

通过本接口，您可以获取主账号下直播间的累计直播时长、最高同时在线人数和累计观看人次等实时数据。

说明

  • 例如直播间A，实时数据只能提供从直播间创建之后的总观看人次，无法提供某个时间范围内的统计数量。

注意事项

请求频率：单用户请求频率限制为 1 次/秒。

请求说明

  • 请求方式：POST
  • 请求地址：https://livesaas.volcengineapi.com/?Action=ListAccountActivityData&Version=2023-08-01

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息详见公共参数。

Query

参数类型是否必选示例值描述
ActionString是ListAccountActivityData接口名称。当前 API 的名称为 ListAccountActivityData。
VersionString是2023-08-01接口版本。当前 API 的版本为 2023-08-01。

Body

参数类型是否必选示例值描述

PageToken

String

否

init

滚动查询 ID。滚动查询方式适用于查询 10,000 条以上数据的场景。
使用滚动查询方式时，首次调用接口查询数据时将该参数值设置为 init，第二次调用接口查询时将该参数值设置为首次查询返回参数中 PageToken 的值，第三次调用接口查询时将该参数值设置为第二次查询返回参数中 PageToken 的值，依次类推。当查询到最后分页，没有更多数据时，返回 finish。

说明

  • 返回参数中 PageToken 值的失效时间为 3 分钟，即超过 3 分钟该 PageToken 值会失效，无法使用该值进行下一次查询。
  • 滚动查询过程中，请勿变更除 PageSize 参数外的查询条件，否则会导致接口查询失败。如需变更滚动查询条件，则需重新进行滚动查询。
PageSizeInteger否20分页查询数量，取值范围为 [1,1000]，默认取值为 20。

PageNumber

Integer

否

1

分页查询页码，默认取值为 1。

  • 使用滚动查询时，不需要传入该参数。
  • 未使用滚动查询时，接口最多支持返回 10,000 条查询结果，即 PageNumber×PageSize≤10,000。

SortField

String

否

LiveTime

排序维度。默认取值为 LiveTime。

  • LiveTime：直播间设置的直播时间
  • LiveDuration：直播间的累计直播时长
  • PCU：最高同时在线观看人数/最高同时在线访问人数
  • UV：累计观看人数/累计访问人数
  • PV：累计观看人次/累计访问人次
  • CommentCount：直播间的总聊天数以及弹幕口令数
  • WatchDurationPerPeople：人均观看时长/人均访问时长

SortMode

String

否

desc

排序模式。默认取值为 desc。

  • asc：升序
  • desc：降序

StartLiveTime

Long

是

1692339016

查询起始时间。Unix 时间戳，单位为秒。
StartLiveTime 取值需小于等于 EndLiveTime，且与 EndLiveTime 的差值最大为 15,552,000，即 180 天。

EndLiveTime

Long

是

1700115016

查询结束时间。Unix 时间戳，单位为秒。
EndLiveTime 取值需大于等于 StartLiveTime，且与 StartLiveTime 的差值最大为 15,552,000，即 180 天。

PlayStatus

String

否

ALL

根据以下维度进行筛选。默认取值为 All。

  • All：观看直播、预告、回放的数据。
  • Live：观看直播的数据。
  • Preview：观看预告的数据。
  • Replay：观看回放的数据。
  • PageView：访问观看页的数据。

ActivityName

String

否

直播间

根据直播间名称进行筛选。支持模糊搜索。最多支持输入 1,000 个字符。
例如，Name 取值为 直播间 A 时，则返回直播间名称为 直播间 ABC、直播间 a、企业直播间 ab 等包含 直播间 A 关键词的直播间列表。

SelectTagsArray of SelectTags否-根据分类标签信息进行筛选。您可以通过 ListSiteTagAPIV2 接口查询标签信息。

SelectTags

参数类型是否必选示例值描述
IndexInteger否0标签的索引值。用于标识标签在控制台展示的位置。取值范围为 [0,19]。
ValueArray of String是["标签值"]分类标签值。每个标签值最多为 20 个字符。
NameString否标签名称分类标签名称。最多支持输入 8 个字符。

返回参数

参数类型示例值描述
PageTokenStringfinish滚动查询 ID。
PageSizeInteger20分页查询数量。
TotalCountInteger1直播间总数量。
ActivitiesArray of Activities-直播间统计信息。
PageNumberInteger1分页查询页码。

Activities

参数类型示例值描述
ActivityIdLong142489521562直播间 ID。
ActivityNameString直播间 A直播间名称。
LiveTimeLong1692559016默认为直播间设置的直播时间。若通过直播时间进行筛选，则该直播时间表示筛选时间范围内距离当前时间最近直播场次的实际开播时间。Unix 时间戳，单位为秒。
LiveDurationLong899直播间的累计直播时长。单位为秒。

PV

Long

412

累计观看次数/累计访问次数。

说明

如果观众刷新观看页 1 次，则人次新增 1 次。

UV

Long

286

累计观看人数/累计访问人数。

说明

使用相同设备（即设备 ID 相同）观看或访问观看页的观众被判定为同一人，人数算作 1。例如 1 位观众使用设备 A 观看了 2 次、使用设备 B 观看了 1 次，1 位观众使用设备 C 观看了 3 次，则观看人数增加 3 人。

PCU

Long

47

最高同时在线观看或访问人数。

说明

使用相同设备（即设备 ID 相同）观看或访问观看页的观众被判定为同一人，人数算作 1。

CommentCountLong403直播间的总聊天数以及弹幕口令数，包括主持人、观众、嘉宾、机器人发送的聊天数量（包括已删除评论和未通过聊天审核的评论等，但不包括图片评论），以及观众参与抽奖、红包等互动活动时发送的弹幕口令数。

WatchDurationPerPeople

Long

476

人均观看时长/人均访问时长。单位为秒。PlayStatus 的取值不同，该参数的计算方式不同，具体如下：

  • All：累计观看直播、预告和回放的总时长 / 累计观看人数（UV）。
  • Live：累计观看直播时长 / 累计观看人数（UV）。
  • Preview：累计观看预告时长 / 累计观看人数（UV）。
  • Replay：累计观看回放时长 / 累计观看人数（UV）。
  • PageView：累计访问时长 / 累计访问人数（UV）。

说明

  • 累计观看时长指直播间内观众使用播放器观看的累计观看时长。例如 1 位观众观看了 1800 秒，1 位观众观看了 3600 秒，则累计观看时长增加 5400 秒。
  • 累计访问时长指直播间内观众访问观看页的累计页面访问时长。例如 1 位观众访问观看页 1800 秒，1 位观众访问观看页 3600 秒，则累计访问时长增加 5400 秒。
LiveCountLong1直播场次，即直播间直播的次数。直播间的 1 次开关播，算作 1 个直播场次。单位为次。
LivePromotionLiveCountLong1转推场次，即直播间开启直播转推开关的直播场次数。一场直播中，无论转推到多少个第三方平台或账号、转推是否成功，转推场次均算作 1。单位为次。有关如何开启直播转推开关，详见直播转推。
LivePromotionLiveDurationLong120转推时长，即直播间开启直播转推开关的直播场次的直播时长之和。单位为秒。有关如何开启直播转推开关，详见直播转推。1 个直播场次只要转推过，就以该场次完整直播时长计算。例如直播间 A 开启过 2 场直播且均开启了直播转推开关。其中第一场直播的时长为 3600 秒，转推 B 平台 1200 秒，转推 C 平台 3000 秒，则第一场直播的转推时长为 3600 秒。第二场直播的时长为 1800 秒，转推 D 平台 300 秒，则第二场直播的转推时长为 1800 秒。因此，直播间 A 的转推时长为 5400（36000+1800） 秒。

LivePromotionPlatformCount

Long

2

转推平台数量，即直播间所有直播场次成功转推的平台数之和。单位为个。有关如何开启直播转推开关，详见直播转推。

说明

  • 不统计转推中和转推失败的平台。
  • 同一个直播间不同场次转推至相同平台或相同账号时，平台数量不进行合并去重。例如直播间 A 开启过 2 场直播，分别为场次 1 和场次 2。场次 1 成功转推到 6 个平台，其中 1 个平台为快手；场次 2 成功转推到 2 个平台，其中 1 个平台为快手，则直播间 A 的转推平台数量为 8（6+2）。
AppTemplateLiveCountLong1手机开播装修次数，即直播间使用 VolcLive 应用或 Android/iOS 开播 SDK 的挂件或图层（包括直播模板中的挂件和图层）功能进行装修的直播场次数。单位为次。有关如何使用挂件和图层功能，详见手机开播和 SDK 概览。
AppTemplateLiveDurationLong120手机开播装修时长，即直播间使用 VolcLive 应用或 Android/iOS 开播 SDK 的挂件或图层（包括直播模板中的挂件和图层）功能进行装修的直播场次的直播时长之和。单位为秒。有关如何使用挂件和图层功能，详见手机开播和 SDK 概览。

请求示例

POST https://livesaas.volcengineapi.com/?Action=ListAccountActivityData&Version=2023-08-01

{
  "StartLiveTime": 1692339016,
  "EndLiveTime": 1700115016
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "202306041104200100100232280022D31",
        "Action": "ListAccountActivityData",
        "Version": "2023-08-01",
        "Service": "livesaas",
        "Region": "cn-north-1",        
        "SystemTime": 1700126287
    },
    "Result": {
      "PageToken": "",
      "Activities": [
        {
          "ActivityId": 142489521562,
          "ActivityName": "直播间 A",
          "LiveTime": 1692559016,
          "LiveDuration": 899,
          "PV": 412,
          "UV": 286,
          "PCU": 47,
          "WatchDurationPerPeople": 476,
          "CommentCount": 403,
          "LiveCount": 1,
          "LivePromotionLiveCount": 1,
          "LivePromotionLiveDuration": 120,
          "LivePromotionPlatformCount": 2,
          "AppTemplateLiveCount": 1,
          "AppTemplateLiveDuration": 120
        }
      ],
      "TotalCount": 1,
      "PageSize": 20,
      "PageNumber": 1        
    }
}

错误码

下表提供了该接口特有的错误码，公共错误码请参见公共错误码和错误码文档。

状态码错误码错误信息说明
400InvalidParameter.InvalidAccountIdThe specified parameter AccountId is invalid.当前账号的鉴权信息错误。
400MissingParameter.StartLiveTimeNotFoundThe required parameter StartLiveTime is missing.缺少必选参数 StartLiveTime。请修改后重试。
400MissingParameter.EndLiveTimeNotFoundThe required parameter EndLiveTime is missing.缺少必选参数 EndLiveTime。请修改后重试。
400InvalidParameter.InvalidActivityNameThe specified parameter ActivityName is invalid.ActivityName 参数超过最大字符限制。请修改后重试。
400InvalidParameter.SearchSizeInvalidSearch scope is too large,please use PageToken search data more than 10,000.搜索数据超过 10,000 条，请使用 PageToken 进行滚动查询。
400InvalidParameter.PageTokenInvalidPageToken does not exist or expires. Please initialize the query againPageToken 参数值不存在或已过期。请使用 PageToken 重新进行滚动查询。
400InvalidParameter.PageTokenConditionModifyThe search condition change, PageToken cannot be used. Please initialize the query again.搜索条件变更，继续使用之前的 PageToken 返回值搜索会错误。请使用 PageToken 重新进行滚动查询。
500InternalErrorData search inner error, please try again.数据搜索服务出现内部错误。请重试。
400InvalidParameter.InvalidSelectTagsThe select tag does not exist. Please confirm the parameter.分类标签不存在。请确认后重试。
400InvalidParameter.InvalidSelectTagValueThe value of select tag does not exist. Please confirm the parameter.分类标签值不存在。请确认后重试。