获取主账号下的直播间实时统计数据--企业直播-火山引擎

文档中心

立即注册

导航

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

最近更新时间：2024.09.04 00:01:27首次发布时间：2023.11.23 14:40:38

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

说明

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

注意事项

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

请求说明

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

请求参数

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

Query

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

Body

参数	类型	是否必选	示例值	描述
PageToken	String	否	`init`	滚动查询 ID。滚动查询方式适用于查询 10,000 条以上数据的场景。使用滚动查询方式时，首次调用接口查询数据时将该参数值设置为 `init`，第二次调用接口查询时将该参数值设置为首次查询返回参数中 `PageToken` 的值，第三次调用接口查询时将该参数值设置为第二次查询返回参数中 `PageToken` 的值，依次类推。当查询到最后分页，没有更多数据时，返回 `finish`。说明返回参数中 `PageToken` 值的失效时间为 3 分钟，即超过 3 分钟该 `PageToken` 值会失效，无法使用该值进行下一次查询。滚动查询过程中，请勿变更除 `PageSize` 参数外的查询条件，否则会导致接口查询失败。如需变更滚动查询条件，则需重新进行滚动查询。
PageSize	Integer	否	`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 个字符。例如，`ActivityName` 取值为 `直播间 A` 时，则返回直播间名称为 `直播间 ABC`、`直播间 a`、`企业直播间 ab` 等包含 `直播间 A` 关键词的直播间列表。
SelectTags	Array of SelectTags	否	`-`	根据分类标签信息进行筛选。您可以通过 ListSiteTagAPIV2 接口查询标签信息。

SelectTags

参数	类型	是否必选	示例值	描述
Index	Integer	否	`0`	标签的索引值。用于标识标签在控制台展示的位置。索引值越小，位置越靠前。
Value	Array of String	是	`["标签值"]`	分类标签值。
Name	String	否	`标签名称`	分类标签名称。

返回参数

参数	类型	示例值	描述
PageToken	String	`finish`	滚动查询 ID。使用滚动查询时，返回下次查询需要传入的 `PageToken` 参数的值。当查询到最后分页，没有更多数据时，返回 `finish`。未使用滚动查询时，返回空。
PageSize	Integer	`20`	分页查询数量。
TotalCount	Integer	`1`	直播间总数量。
Activities	Array of Activities	`-`	直播间统计信息。
PageNumber	Integer	`1`	分页查询页码。未使用滚动查询时，返回实际分页查询页码。使用滚动查询时，返回 `0`。

Activities

参数	类型	示例值	描述
ActivityId	Long	`142489521562`	直播间 ID。
ActivityName	String	`直播间 A`	直播间名称。
LiveTime	Long	`1692559016`	默认为直播间设置的直播时间。若通过直播时间进行筛选，则该直播时间表示筛选时间范围内距离当前时间最近直播场次的实际开播时间。Unix 时间戳，单位为秒。
LiveDuration	Long	`899`	直播间的累计直播时长。单位为秒。
PV	Long	`412`	累计观看次数/累计访问次数。说明如果观众刷新观看页 1 次，则人次新增 1 次。
UV	Long	`286`	累计观看人数/累计访问人数。说明使用相同设备（即设备 ID 相同）观看或访问观看页的观众被判定为同一人，人数算作 1。例如 1 位观众使用设备 A 观看了 2 次、使用设备 B 观看了 1 次，1 位观众使用设备 C 观看了 3 次，则观看人数增加 3 人。
PCU	Long	`47`	最高同时在线观看或访问人数。说明使用相同设备（即设备 ID 相同）观看或访问观看页的观众被判定为同一人，人数算作 1。
CommentCount	Long	`403`	直播间的总聊天数以及弹幕口令数，包括主持人、观众、嘉宾、机器人发送的聊天数量（包括已删除评论和未通过聊天审核的评论等，但不包括图片评论），以及观众参与抽奖、红包等互动活动时发送的弹幕口令数。
WatchDurationPerPeople	Long	`476`	人均观看时长/人均访问时长。单位为秒。`PlayStatus` 的取值不同，该参数的计算方式不同，具体如下： `All`：累计观看直播、预告和回放的总时长 / 累计观看人数（UV）。 `Live`：累计观看直播时长 / 累计观看人数（UV）。 `Preview`：累计观看预告时长 / 累计观看人数（UV）。 `Replay`：累计观看回放时长 / 累计观看人数（UV）。 `PageView`：累计访问时长 / 累计访问人数（UV）。说明累计观看时长指直播间内观众使用播放器观看的累计观看时长。例如 1 位观众观看了 1800 秒，1 位观众观看了 3600 秒，则累计观看时长增加 5400 秒。累计访问时长指直播间内观众访问观看页的累计页面访问时长。例如 1 位观众访问观看页 1800 秒，1 位观众访问观看页 3600 秒，则累计访问时长增加 5400 秒。
LiveCount	Long	`1`	直播场次，即直播间直播的次数。直播间的 1 次开关播，算作 1 个直播场次。单位为次。
LivePromotionLiveCount	Long	`1`	转推场次，即直播间开启直播转推开关的直播场次数。一场直播中，无论转推到多少个第三方平台或账号、转推是否成功，转推场次均算作 1。单位为次。有关如何开启直播转推开关，详见直播转推。
LivePromotionLiveDuration	Long	`120`	转推时长，即直播间开启直播转推开关的直播场次的直播时长之和。单位为秒。有关如何开启直播转推开关，详见直播转推。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）。
AppTemplateLiveCount	Long	`1`	手机开播装修次数，即直播间使用 VolcLive 应用或 Android/iOS 开播 SDK 的挂件或图层（包括直播模板中的挂件和图层）功能进行装修的直播场次数。单位为次。有关如何使用挂件和图层功能，详见手机开播和 SDK 概览。
AppTemplateLiveDuration	Long	`120`	手机开播装修时长，即直播间使用 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        
    }
}

错误码

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

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