获取主账号下的用户画像数据--企业直播-火山引擎

文档中心

立即注册

导航

获取主账号下的用户画像数据

最近更新时间：2024.11.15 11:15:19首次发布时间：2023.11.23 14:40:38

您可通过此接口获取主账号下观众的基础数据、互动数据及直播报名数据等用户画像数据。

注意事项

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

请求说明

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

请求参数

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

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`ListAccountUserData`	接口名称。当前 API 的名称为 `ListAccountUserData`。
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`。
SortField	String	否	`CommentCount`	排序维度。默认按照用户 ID 进行排序。 `CommentCount`：观众发送的评论数量 `WatchTime`：累计观看时长/累计页面访问时长 `LiveCount`：观众累计观看的直播间数量
SortMode	String	否	`desc`	排序模式。默认值为 `desc`。 `asc`：升序 `desc`：降序
KeyWord	String	否	`A`	根据观众昵称或手机号进行筛选。观众昵称支持模糊搜索。最多支持输入 1,000 个字符。
ActivityId	Long	否	`177***4894`	直播间 ID。您可通过调用 ListActivityAPI 接口获取 ID。
PlayStatus	String	否	`All`	根据以下维度进行筛选。默认值为 `All`。 `All`：观看直播、预告、回放的数据。 `Live`：观看直播的数据。 `Preview`：观看预告的数据。 `Replay`：观看回放的数据。 `PageView`：访问观看页的数据。
SelectTags	Array of SelectTags	否	`-`	根据分类标签信息进行筛选。您可通过调用 ListSiteTagAPIV2 接口获取标签信息。
PageNumber	Float	否	`1`	分页查询页码，默认值为 `1`。使用滚动查询时，不需要传入该参数。未使用滚动查询时，接口最多支持返回 10,000 条查询结果，即 `PageNumber`×`PageSize`≤10,000。
BanStatus	Integer	否	`0`	根据观众的封禁状态进行筛选。已封禁的观众无法进入当前主账号及其子账号的任一直播间。默认值为 `0`。取值如下： `0`：查询所有观众 `1`：查询已封禁的观众 `2`：查询未封禁的观众
UserIds	Array of Long	否	`[12345,67890]`	观众的用户 ID。您可调用当前接口获取用户 ID。数组元素数量上限为 1000。说明该参数仅在 `BanStatus` 取值为 `1` 或 `2` 时生效。

SelectTags

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

返回参数

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

Users

参数	类型	示例值	描述
BasicData	Object of BasicData	`-`	基础数据。
InteractData	Object of InteractData	`-`	互动数据。
PayData	Object of PayData	`-`	付费数据。
UserEnterForm	Object of UserEnterForm	`-`	直播报名数据。
WatchData	Object of WatchData	`-`	观看和页面访问数据。

BasicData

参数	类型	示例值	描述
UserId	Long	`176****653`	用户 ID，观众在企业直播的唯一标识。
NickName	String	`观众 A`	观众昵称。
Telephone	String	`154***4892`	观众登录直播间的手机号。
IP	String	`36.11***67.68`	观众的 IP 地址。
Country	String	`中国`	观众所在国家。
Province	String	`北京`	观众所在省份。
WatchType	String	`手机号`	该参数与观众登录直播间的方式有关。例如，观众通过手机号登录直播间则返回手机号，通过登录您的自有账号系统进入直播间则此处返回登录账号的 App 名称。
WatchDevice	String	`Android 6.0`	观众进入直播间使用的终端机型。
ExternalId	String	`127***1145`	观众在第三方平台的唯一标识。您可以根据该关联用户 ID 识别企业自身的用户身份，以便于按需实现用户洞察和进行数据分析。观众通过不同方式登录直播间时，关联用户 ID 取值不同，具体取值情况详见数据统计。
BanStatus	Integer	`1`	观众的封禁状态。取值如下： `1`：已封禁 `2`：未封禁

InteractData

参数	类型	示例值	描述
ReservationCount	Integer	`1`	观众预约直播的次数。
VoteCount	Integer	`1`	观众参与投票的次数。
CommentCount	Integer	`2`	观众发送的评论数量（包括已删除评论和未通过聊天审核的评论等，但不包括图片评论）以及参与抽奖、红包等互动活动时发送的弹幕口令数。
QuestionnaireCount	Integer	`2`	观众填写问卷的次数。
LotteryCount	Integer	`5`	观众参与实时抽奖的次数。
LotteryHitCount	Integer	`3`	观众中奖的次数。
InviteCount	Integer	`5`	观众分享直播的次数，即有多少用户通过观众分享的专属链接、二维码或海报进入并登录直播间。
ShiftScreenNumber	Integer	`2`	观众触发切屏检测提醒弹窗的次数。
MuteNumber	Integer	`1`	观众触发静音停播提醒弹窗的次数。
NoInteractNumber	Integer	`1`	观众触发无互动检测提醒弹窗的次数。
CouponPickupCount	Long	`1`	观众领取的卡券数量。

PayData

参数	类型	示例值	描述
TotalAmount	String	`5`	付费金额。
PayCount	Integer	`1`	付费观看次数。

UserEnterForm

参数	类型	示例值	描述
EnterReviewName	String	`报名姓名`	直播报名填写的姓名。
EnterReviewSex	String	`报名性别`	直播报名填写的性别。
EnterReviewAge	String	`报名年龄`	直播报名填写的年龄。
EnterReviewBirthday	String	`报名生日`	直播报名填写的生日。
EnterReviewTel	String	`185***4856`	直播报名填写的手机号。
EnterReviewEmail	String	`zhibo@xxx.com`	直播报名填写的邮箱。
EnterReviewCompany	String	`报名公司`	直播报名填写的公司名称。
EnterReviewIndustry	String	`报名行业`	直播报名填写的行业名称。
EnterReviewPosition	String	`报名职位`	直播报名填写的职位。
EnterReviewEducation	String	`报名学历`	直播报名填写的学历。

WatchData

参数	类型	示例值	描述
LiveCount	Long	`3`	观众累计观看的直播间数量。
WatchTime	Long	`500`	观众观看超低延时直播、普通延时直播、预告、回放的累计观看时长。单位为秒。
RtmLiveData	Long	`200`	观众观看超低延时直播的累计时长。单位为秒。
WatchLiveDuration	Long	`300`	观众观看超低延时直播、普通延时直播的累计观看时长。单位为秒。
WatchPreviewDuration	Long	`100`	观众观看预告的累计观看时长。单位为秒。
WatchReplayDuration	Long	`100`	观众观看回放的累计观看时长。单位为秒。
WatchPageDuration	Long	`200`	观众访问观看页的累计页面访问时长。单位为秒。

请求示例

POST https://livesaas.volcengineapi.com/?Action=ListAccountUserData&Version=2023-08-01
{
    "PageToken": "init",
    "PageNumber": 1,
    "PageSize": 20,
    "SortField": "CommentCount",
    "SortMode": "desc",
    "KeyWord": "A",
    "ActivityId": 177***4894,
    "SelectTags": [
        {
            "Index": 0,
            "Value": [
                "标签值"
            ],
            "Name": "标签名称"
        }
    ],
    "PlayStatus": "All",
    "BanStatus": 0,
    "UserIds": [
        12345,
        67890
    ]
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "ListAccountUserData",
        "Version": "2023-08-01",
        "Service": "livesaas",
        "Region": "cn-north-1",
        "SystemTime": 1721111109
    },
    "Result": {
        "PageToken": "finish",
        "PageNumber": 1,
        "Users": [
            {
                "BasicData": {
                    "UserId": 176****653,
                    "WatchDevice": "Android 6.0",
                    "ExternalId": "127***1145",
                    "WatchType": "手机号",
                    "Province": "北京",
                    "Country": "中国",
                    "IP": "36.11***67.68",
                    "Telephone": "154***4892",
                    "NickName": "观众 A",
                    "BanStatus": 1
                },
                "InteractData": {
                    "ReservationCount": 1,
                    "LotteryCount": 5,
                    "NoInteractNumber": 1,
                    "MuteNumber": 1,
                    "ShiftScreenNumber": 2,
                    "InviteCount": 5,
                    "LotteryHitCount": 3,
                    "QuestionnaireCount": 2,
                    "CommentCount": 2,
                    "VoteCount": 1,
                    "CouponPickupCount": 1
                },
                "WatchData": {
                    "LiveCount": 3,
                    "WatchReplayDuration": 100,
                    "WatchPageDuration": 200,
                    "WatchPreviewDuration": 100,
                    "WatchLiveDuration": 300,
                    "RtmLiveData": 200,
                    "WatchTime": 500
                },
                "PayData": {
                    "TotalAmount": "5",
                    "PayCount": 1
                },
                "UserEnterForm": {
                    "EnterReviewName": "报名姓名",
                    "EnterReviewSex": "报名性别",
                    "EnterReviewAge": "报名年龄",
                    "EnterReviewEducation": "报名学历",
                    "EnterReviewPosition": "报名职位",
                    "EnterReviewIndustry": "报名行业",
                    "EnterReviewCompany": "报名公司",
                    "EnterReviewEmail": "zhibo@xxx.com",
                    "EnterReviewTel": "185***4856",
                    "EnterReviewBirthday": "报名生日"
                }
            }
        ],
        "TotalCount": 1,
        "PageSize": 20
    }
}

错误码

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

状态码	错误码	错误信息	说明
400	InvalidParameter.InvalidAccountId	The specified parameter AccountId is invalid.	当前账号的鉴权信息错误。
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.	数据搜索服务出现内部错误。请重试。