# 批量获取点播视频完成度

### 接口URL

```
https://api.polyv.net/v2/video/engagement/{userId}/getList
```

### 接口说明

```
支持批量分页获取视频观看完成度
支持https
```

### 支持格式

```
JSON
```

### 请求方式

```
POST,GET
```

### 请求数限制

```
TRUE
```

### 请求参数

| 参数名         | 必选    | 类型及范围  | 说明                                                                                                                       |
| ----------- | ----- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| userid      | true  | string | 路径参数，用户userId                                                                                                            |
| ptime       | true  | float  | 13位的当前时间毫秒级时间戳                                                                                                           |
| sign        | true  | String | 签名，为40位大写的SHA1值【详见[签名生成规则](https://git.polyv.net/help-center/document-center/-/blob/master/vod/api/buildSign/README.md)】 |
| field       | true  | string | 查询条件字段，取值范围：video 根据视频搜索；viewer 根据观众搜索                                                                                   |
| fieldValue  | true  | string | 查询条件的值，如果filed = video 填写vid；如果field = viewer 填写 viewerId                                                                |
| filterValue | false | string | 过滤条件，如果field = video，可填写多个以,分隔的viewerId进行过滤；如果field = viewer，可填写多个以,分隔的vid进行过滤                                           |
| page        | false | int    | 第几页，默认1                                                                                                                  |
| size        | false | int    | 每一页大小                                                                                                                    |

### 返回结果

```json
{
    "code": 200,
    "status": "success",
    "message": "success",
    "data": {
        "pageSize": 20,
        "pageNumber": 1,
        "totalItems": 1,
        "contents": [
            {
                "vid": "ee7fe7fbdadafe381e8e100669144e51_e",
                "viewerId": "1111",
                "watchPercentage": 0.05
            }
        ]
    }
}
```

### 请求失败返回json示例

```json
// 签名错误
{
    "code": 400,
    "status": "error",
    "message": "the sign is not right.",
    "data": ""
}
// 类型错误
{
    "code": 400,
    "status": "error",
    "message": "field type error",
    "data": ""
}
// ...
```

### 字段说明

| 字段                               | 类型     | 说明         |
| -------------------------------- | ------ | ---------- |
| code                             | int    | 请求返回状态码    |
| status                           | string | 请求返回状态     |
| message                          | string | 请求返回信息     |
| data.pageSize                    | int    | 每页大小       |
| data.pageNumber                  | int    | 第几页        |
| data.totalItems                  | int    | 总数量        |
| data.content\[0].vid             | string | 视频vid      |
| data.content\[0].viewerId        | string | 观众viewerId |
| data.content\[0].watchPercentage | float  | 观看完成度      |

#### Java示例代码

```java
public class Test {

    public static void main(String[] args) throws Exception {
        String userId = "ee7fe7fbda";
        String secretkey = "2owGBAZsAY";
        String url = "https://api.polyv.net/v2/video/engagement/%s/getList";

        Map<String, String> maps = new HashMap<>();
        maps.put("field", "viewer");
        maps.put("fieldValue", "1111");
        maps.put("filterValue", "");
        maps.put("sign", getSign(maps, secretkey));

        url += "?" + buildUrl(maps);
        url = String.format(url, userId);
        HttpClient client = new HttpClient();
        GetMethod getMethod = new GetMethod(url);
        client.executeMethod(getMethod);
        System.out.println(url);
        System.out.println(getMethod.getResponseBodyAsString());
    }

    public static String buildUrl(Map<String, String> maps) {
        List<String> tmp = new ArrayList<>();
        for (Map.Entry<String, String> key : maps.entrySet()) {
            tmp.add(key.getKey() + "=" + key.getValue());
        }
        return String.join("&", tmp);
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://polyv.gitbook.io/document/docs/unclassified/2020/f1e48ef9b8e10e43a1b08278bbcbc5f5.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.