查询观看行为分析

接口描述

1、通过时间区间分页查询观看行为分析数据
2、接口URL中的{userid}为点播账号userid，具体参考菜单【使用须知】->【获取密钥】
3、观看完成度=用户观看有效时长/视频时长，例如：视频A时长为50分钟，用户观看了第0~20分钟，拖拽进度条后观看了第10~30分钟，此时用户有效观看时长为30分钟，则完成度为 30/50=60%
4、接口支持https协议

接口URL

http://api.polyv.net/v2/advance/play/{userid}

在线API调用

请求方式

GET

接口约束

1、接口同时支持HTTP 、HTTPS ，建议使用HTTPS 确保接口安全，接口调用有频率限制，详细请查看 2、高级分析功能介绍详见： 视频高级分析 3、由于数据量和计算量大，数据分析结果次日才可查询 4、查询的时间跨度不超过31天；当start有值而end为空时，返回开始日期后31天后的数据；当start为空而end不为空时，返回结束日期前31天内的数据；当start、end参数均为空时，返回最近31天的数据。

请求参数描述

参数名必选类型说明

userId

true

String

保利威点播账户id，可以参考【获取密钥】获取，获取路径：官网->登录->点播（API接口）

ptime

true

Long

当前时间的毫秒级时间戳，3分钟内有效

sign

true

String

签名，为40位大写的SHA1值,生成签名的secretkey密钥作为通信数据安全的关键信息，严禁保存在客户端直接使用，所有API都必须通过客户自己服务器中转调用POLYV服务器获取响应数据【详见签名生成规则】

start

false

String

开始时间，格式：yyyy-MM-dd或者yyyy-MM-dd HH:mm:ss，查询范围不超过31天

end

false

String

结束时间，格式：yyyy-MM-dd或者yyyy-MM-dd HH:mm:ss，查询范围不超过31天

pageSize

false

Integer

每页取多少条数据（最大为20，超过则默认取20条数据）

viewerId

false

String

自定义观看者id

viewerName

false

String

观看者昵称

vid

false

String

视频id，不传查当前账号下所有视频的观看行为分析数据

token

false

String

下一页的凭证，从当前页的返回数据里获取，第一页不需要传

示例

http://api.polyv.net/v2/advance/play/1b448be323?vid=1b448be323ae991b1dfc5136597618d1_1&start=2021-03-10+15%3A21%3A01&sign=12BD21B68CE506562F6C79B7615254EB668B2DFB&pageSize=5&end=2021-04-07+15%3A21%3A01&userid=1b448be323&ptime=1617786046170

响应参数描述

参数名类型说明

code

Integer

响应状态码，200为成功返回，非200为失败【详见全局错误说明】

status

String

响应状态文本信息

message

String

响应描述信息，当code为400或者500的时候，辅助描述错误原因

data

Object

响应成功时返回观看行为分析详细数据 【详见data字段说明】

data字段说明

参数名类型说明

pageSize

Integer

每页显示的数据条数

contents

Array

观看的详细数据【详见contents字段说明】

token

String

查询下一页时传的凭证

hasNextPage

Boolean

是否有下一页

contents字段说明

参数名类型说明

startTime

String

首次观看日期，格式：yyyy-MM-dd HH:mm:ss

videoId

String

视频id

videoName

String

视频名称

videoImage

String

视频首图链接地址（没有添加协议头）

videoDuration

Integer

视频时长，单位：秒

deviceClass

String

设备名称

osName

String

操作系统

osVersion

String

操作系统版本

agentName

String

终端名称

agentVersion

String

终端版本

referer

String

来源

ip

String

ip地址

country

String

国家

province

String

省份

city

String

地区

isp

String

运营商

viewerid

String

观看者id

viewerNickName

String

观看者昵称

viewerAvatar

String

观看者头像

totalVideoCount

Long

观看者观看的视频总量

heatmap

String

热力图（["0-1:1","3-4:2"]表示视频的0到1秒有1次观看，3到4秒有2次观看）

completionRate

Double

观看完成度

status

String

视频状态 60/61：已发布 10：等待编码 20：正在编码 50：等待审核 51：审核不通过 -1：已删除

playId

String

表示此次播放动作的id

返回错误代码列表

错误代码message说明

400

sign can not be empty.

加密串为空

400

ptime is too old.

时间戳过期

400

ptime is illegal.

ptime超出当前时间3分钟

400

Could not find user by userid.

userid不存在

400

the sign is not right.

加密串错误

401

start date or end date is illegal.

start或者end参数格式有问题

402

date range exceeds 31 days.

start和end参数相差超过31天

403

get play list error.

后台获取数据失败

500

get play list failed. please check the backend log.

后台抛异常

Java请求示例

快速接入基础代码请下载相关依赖源码， 点击下载源代码 ,下载后加入到自己的源码工程中即可。测试用例中的HttpUtil.java 和 VodSignUtil.java 都包含在下载文件中。

强烈建议您使用点播Java SDK完成API的功能对接，点播Java SDK 对API调用逻辑、异常处理、数据签名、HTTP请求线程池进行了统一封装和优化。

private static final Logger log = LoggerFactory.getLogger(VodBigdataTest.class);

/**
 * 查询观看行为分析
 */
@Test
public void testGetPlayAnalysis() throws Exception, NoSuchAlgorithmException {
    //公共参数,填写自己的实际参数
    String secretKey = super.secretKey;
    String userId = super.userId;
    String ptime = String.valueOf(System.currentTimeMillis());
    //业务参数
    String url = String.format("http://api.polyv.net/v2/advance/play/%s", userId);
    String start = "2021-03-10 15:21:01";
    String end = "2021-04-07 15:21:01";
    String pageSize = "5";
    String vid = "1b448be323ae991b1dfc5136597618d1_1";

    Map<String, String> requestMap = new HashMap<>();
    requestMap.put("userid", userId);
    requestMap.put("ptime", ptime);
    requestMap.put("start", start);
    requestMap.put("end", end);
    requestMap.put("pageSize", pageSize);
    requestMap.put("vid", vid);

    requestMap.put("sign", VodSignUtil.getSign(requestMap, secretKey));
    
    String response = HttpUtil.get(url, requestMap);
    log.debug("测试查询观看行为分析，{}", response);
    //do somethings
}

响应示例

系统全局错误说明详见全局错误说明

成功示例

{
	"code": 200,
	"status": "success",
	"message": "success",
	"data": {
		"pageSize": 5,
		"contents": [{
			"startTime": "2021-04-06 16:29:06",
			"videoId": "1b448be323ae991b1dfc5136597618d1_1",
			"videoName": "小猫2",
			"videoImage": "//img.videocc.net/uimage/1/1b448be323/first_image/cd09cde7-acb0-4662-b24d-fee4b4e3f885_s.jpg",
			"videoDuration": 15,
			"deviceClass": "Desktop",
			"osName": "Windows NT",
			"osVersion": "10.0",
			"agentName": "Edge",
			"agentVersion": "89.0.774.68",
			"referer": "https://share.plvideo.cn/front/video/preview?vid=1b448be323ae991b1dfc5136597618d1_1",
			"ip": "xxxxxxx",
			"country": "中国",
			"province": "湖南",
			"city": "长沙",
			"isp": "中国电信",
			"viewerId": "N/A",
			"viewerNickName": "N/A",
			"viewerAvatar": "N/A",
			"totalVideoCount": 0,
			"heatmap": "[\"0-15:1\"]",
			"completionRate": 1.0,
			"status": 61,
			"playId": "1617697736110X1071695"
		}, {
			"startTime": "2021-04-02 17:11:48",
			"videoId": "1b448be323ae991b1dfc5136597618d1_1",
			"videoName": "小猫2",
			"videoImage": "//img.videocc.net/uimage/1/1b448be323/first_image/cd09cde7-acb0-4662-b24d-fee4b4e3f885_s.jpg",
			"videoDuration": 15,
			"deviceClass": "Desktop",
			"osName": "Windows NT",
			"osVersion": "10.0",
			"agentName": "Edge",
			"agentVersion": "89.0.774.63",
			"referer": "https://share.plvideo.cn/front/video/preview?vid=1b448be323ae991b1dfc5136597618d1_1",
			"ip": "xxxxxxx",
			"country": "中国",
			"province": "湖南",
			"city": "长沙",
			"isp": "中国电信",
			"viewerId": "N/A",
			"viewerNickName": "N/A",
			"viewerAvatar": "N/A",
			"totalVideoCount": 0,
			"heatmap": "[\"0-15:1\"]",
			"completionRate": 1.0,
			"status": 61,
			"playId": "1617354698104X1597608"
		}, {
			"startTime": "2021-03-31 16:28:14",
			"videoId": "1b448be323ae991b1dfc5136597618d1_1",
			"videoName": "小猫2",
			"videoImage": "//img.videocc.net/uimage/1/1b448be323/first_image/cd09cde7-acb0-4662-b24d-fee4b4e3f885_s.jpg",
			"videoDuration": 15,
			"deviceClass": "Desktop",
			"osName": "Windows NT",
			"osVersion": "10.0",
			"agentName": "Edge",
			"agentVersion": "89.0.774.63",
			"referer": "https://share.plvideo.cn/front/video/preview?vid=1b448be323ae991b1dfc5136597618d1_1",
			"ip": "xxxxxxx",
			"country": "中国",
			"province": "湖南",
			"city": "长沙",
			"isp": "中国电信",
			"viewerId": "N/A",
			"viewerNickName": "N/A",
			"viewerAvatar": "N/A",
			"totalVideoCount": 0,
			"heatmap": "[\"0-15:1\"]",
			"completionRate": 1.0,
			"status": 61,
			"playId": "1617179283819X1803923"
		}, {
			"startTime": "2021-03-31 16:26:10",
			"videoId": "1b448be323ae991b1dfc5136597618d1_1",
			"videoName": "小猫2",
			"videoImage": "//img.videocc.net/uimage/1/1b448be323/first_image/cd09cde7-acb0-4662-b24d-fee4b4e3f885_s.jpg",
			"videoDuration": 15,
			"deviceClass": "Phone",
			"osName": "Android",
			"osVersion": "6.0",
			"agentName": "WeChat",
			"agentVersion": "8.0.2.1860",
			"referer": "https://share.plvideo.cn/front/video/view?vid=1b448be323ae991b1dfc5136597618d1_1",
			"ip": "xxxxxxx",
			"country": "中国",
			"province": "湖南",
			"city": "长沙",
			"isp": "中国电信",
			"viewerId": "N/A",
			"viewerNickName": "N/A",
			"viewerAvatar": "N/A",
			"totalVideoCount": 0,
			"heatmap": "[\"0-15:1\"]",
			"completionRate": 1.0,
			"status": 61,
			"playId": "1617179158342X1197943"
		}, {
			"startTime": "2021-03-31 16:25:20",
			"videoId": "1b448be323ae991b1dfc5136597618d1_1",
			"videoName": "小猫2",
			"videoImage": "//img.videocc.net/uimage/1/1b448be323/first_image/cd09cde7-acb0-4662-b24d-fee4b4e3f885_s.jpg",
			"videoDuration": 15,
			"deviceClass": "Desktop",
			"osName": "Windows NT",
			"osVersion": "10.0",
			"agentName": "Edge",
			"agentVersion": "89.0.774.63",
			"referer": "https://share.plvideo.cn/front/video/preview?vid=1b448be323ae991b1dfc5136597618d1_1",
			"ip": "xxxxxxx",
			"country": "中国",
			"province": "湖南",
			"city": "长沙",
			"isp": "中国电信",
			"viewerId": "N/A",
			"viewerNickName": "N/A",
			"viewerAvatar": "N/A",
			"totalVideoCount": 0,
			"heatmap": "[\"0-15:1\"]",
			"completionRate": 1.0,
			"status": 61,
			"playId": "1617179110026X1812455"
		}],
		"token": "2daa82aabd892f661e967ed365536c05ad832deccda9d0a66f380c6987d838b8e248525ef721439b95a56f9d2027734e5b0d72bbb3022c88a2ef50e2604de902",
		"hasNextPage": true
	}
}

异常示例

{
  "code": 400,
  "status": "error",
  "message": "ptime is too old.",
  "data": ""
}
Previous批量查询视频分析Next查询视频分析

Last updated