You need to enable JavaScript to run this app.
导航
获取主账号下的直播间离线统计数据
最近更新时间:2024.07.04 10:54:09首次发布时间:2024.04.23 14:26:57

您可通过此接口获取主账号下指定时间范围内,开播并且已关播直播间的累计直播时长、最高同时在线人数和累计观看人次等离线数据。

说明

离线数据是指直播间创建后,某个时间范围内的数据,而不是直播间创建以来的所有历史数据。

注意事项

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

请求说明

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

请求参数

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

Query

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

Body

参数类型是否必选示例值描述
PageSizeInteger20分页查询数量,取值范围为 [1,1000],默认取值为 20
PageNumberInteger1分页查询页码,默认取值为 1

SortField

String

LiveTime

排序维度。默认取值为 LiveTime

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

SortMode

String

desc

排序模式。默认取值为 desc

  • asc:升序
  • desc:降序

StartLiveTime

Long

1711555260

查询起始时间。Unix 时间戳,单位为秒。StartLiveTime 需同时满足以下条件:
1、取值大于等于 1711555200,即 2024 年 3 月 28 日 0 时。
2、取值小于等于 EndLiveTime,且与 EndLiveTime 的差值最大为 15,552,000,即 180 天。

EndLiveTime

Long

1715115016

查询结束时间。Unix 时间戳,单位为秒。EndLiveTime 需同时满足以下条件:
1、取值小于等于 T-1 日,其中 T 表示当前日期。例如当前日期为 2024 年 04 月 10 日,则 LiveEndTime 取值需为 2024 年 04 月 09 日或之前的某个时间点。
2、取值大于等于 StartLiveTime,且与 StartLiveTime 的差值最大为 15,552,000,即 180 天。

PlayStatus

String

All

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

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

ActivityName

String

直播间 A

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

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

SelectTags

参数类型是否必选示例值描述
IndexInteger0标签的索引值。用于标识标签在控制台展示的位置。索引值越小,位置越靠前。
ValueArray of String["标签值"]分类标签值。
NameString标签名称分类标签名称。

返回参数

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

Activities

参数类型示例值描述
ActivityIdLong17951838079243直播间 ID。
ActivityNameString直播间 A直播间名称。
LiveTimeLong1712111173直播间最近一次的开播时间。Unix 时间戳,单位为秒。
LiveDurationLong1215直播间的累计直播时长。单位为秒。

PV

Long

7

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

说明

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

UV

Long

5

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

说明

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

PCU

Long

10

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

说明

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

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

WatchDurationPerPeople

Long

4

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

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

说明

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

LivePromotionPlatformCount

Long

11

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

说明

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

请求示例

POST https://livesaas.volcengineapi.com/?Action=ListAccountActivityHistoryData&Version=2023-08-01
{
    "PageSize": 20,
    "SortField": "LiveTime",
    "SortMode": "desc",
    "StartLiveTime": 1711555260,
    "EndLiveTime": 1715115016,
    "PlayStatus": "All",
    "SelectTags": [
        {
            "Index": 0,
            "Name": "标签名称",
            "Value": [
                "标签值"
            ]
        }
    ],
    "ActivityName": "直播间 A",
    "PageNumber": 1
}

返回示例

{
    "ResponseMetadata": {
        "Action": "ListAccountActivityHistoryData",
        "Region": "cn-north-1",
        "RequestId": "2024041615203872B383A0A1B2B628CCA2",
        "Service": "livesaas",
        "SystemTime": 1713252039,
        "Version": "2023-08-01"
    },
    "Result": {
        "Activities": [
            {
                "ActivityId": 17951838079243,
                "ActivityName": "直播间 A",
                "AppTemplateLiveCount": 2,
                "AppTemplateLiveDuration": 687,
                "CommentCount": 8,
                "LiveCount": 4,
                "LiveDuration": 1215,
                "LivePromotionLiveCount": 4,
                "LivePromotionLiveDuration": 3514,
                "LivePromotionPlatformCount": 11,
                "LiveTime": 1712111173,
                "PCU": 10,
                "PV": 7,
                "UV": 5,
                "WatchDurationPerPeople": 4
            }
        ],
        "PageNumber": 1,
        "PageSize": 20,
        "TotalCount": 1
    }
}

错误码

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

状态码错误码错误信息说明
400InvalidParameter.HistoryDataNotReadyThe search end time needs to be less than today, otherwise the historical data has not been produced.离线数据尚未生成。请配置小于当前日期的结束时间。
400InvalidParameter.InvalidAccountIdThe specified parameter AccountId is invalid.当前账号的鉴权信息错误。
400MissingParameter.StartLiveTimeNotFoundThe required parameter StartLiveTime is missing.缺少必选参数 StartLiveTime。请修改后重试。
400MissingParameter.EndLiveTimeNotFoundThe required parameter EndLiveTime is missing.缺少必选参数 EndLiveTime。请修改后重试。
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.分类标签值不存在。请确认后重试。