# 搜索视频

### 接口描述

```
1、搜索视频详细内容
2、接口支持https协议
```

### 接口URL

```
http://api.polyv.net/v2/video/search-videos
```

[在线API调用](https://git.polyv.net/help-center/document-center/-/blob/master/req.html?api=http:/api.polyv.net/v2/video/search-videos/README.md)

### 请求方式

```
GET
```

### 接口约束

1、接口同时支持HTTP 、HTTPS ，建议使用HTTPS 确保接口安全，接口调用有频率限制，[详细请查看](https://git.polyv.net/help-center/document-center/-/blob/master/vod/api/limit/README.md)

### 请求参数描述

| 参数名             | 必选    | 类型      | 说明                                                                                                                                                                                                                                                  |
| --------------- | ----- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| userid          | true  | String  | 保利威点播账户id，可以参考【[获取密钥](https://git.polyv.net/help-center/document-center/-/blob/master/vod/api/getSecretKey/README.md)】获取，获取路径：官网->登录->点播（API接口）                                                                                                     |
| ptime           | true  | Long    | 当前时间的毫秒级时间戳，3分钟内有效                                                                                                                                                                                                                                  |
| sign            | true  | String  | 签名，为40位大写的SHA1值,`生成签名的secretkey密钥作为通信数据安全的关键信息，严禁保存在客户端直接使用，所有API都必须通过客户自己服务器中转调用POLYV服务器获取响应数据`【详见[签名生成规则](https://git.polyv.net/help-center/document-center/-/blob/master/vod/api/buildSign/README.md)】                                           |
| filters         | false | String  | <p>需要返回的视频信息，多个以英文逗号分隔，默认仅返回基础信息<br>basicInfo：基础信息<br>metaData：元数据<br>transcodeInfo：转码信息<br>snapshotInfo：截图信息</p>                                                                                                                                   |
| cateId          | false | Long    | 视频分类id，该参数获取自【[获取分类及子分类](https://git.polyv.net/help-center/document-center/-/blob/master/vod/api/video_management/category/get_categories.md)】                                                                                                      |
| title           | false | String  | 按标题/视频vid模糊搜索                                                                                                                                                                                                                                       |
| tag             | false | String  | 按视频标签模糊搜索                                                                                                                                                                                                                                           |
| uploader        | false | String  | 上传者，例如：主账号                                                                                                                                                                                                                                          |
| status          | false | String  | 视频状态，默认搜索全部状态的视频，多个状态以英文逗号分隔，查询已发布状态的视频只需传61/60其中一个即可，如"61,50"，可以参考【[status字段说明](https://git.polyv.net/help-center/document-center/-/blob/master/vod/api/video_management/search/search_video.md.md?id=status%E5%AD%97%E6%AE%B5%E8%AF%B4%E6%98%8E)】 |
| containSubCate  | false | Boolean | <p>是否包含子分类<br>true：包含<br>false：不包含，默认为true</p>                                                                                                                                                                                                      |
| startTime       | false | Long    | 按创建时间范围查询，起始时间戳，13位时间戳                                                                                                                                                                                                                              |
| endTime         | false | Long    | 结束时间戳，13位时间戳                                                                                                                                                                                                                                        |
| startModifyTime | false | Long    | 按修改时间范围查询，起始时间戳，13位时间戳                                                                                                                                                                                                                              |
| endModifyTime   | false | Long    | 修改时间的结束时间戳，13位时间戳                                                                                                                                                                                                                                   |
| encrypted       | false | Boolean | 是否加密                                                                                                                                                                                                                                                |
| playAuthEnable  | false | Boolean | 是否开启了播放授权                                                                                                                                                                                                                                           |
| sort            | false | String  | <p>结果排序，可以按创建时间或播放次数降序/升序排序<br>creationTimeAsc：创建时间升序<br>creationTimeDesc：创建时间降序<br>playTimesAsc：播放次数升序<br>playTimesDesc：播放次数降序</p>                                                                                                                 |
| page            | false | Integer | 页码，默认为1                                                                                                                                                                                                                                             |
| pageSize        | false | Integer | 页面大小，默认为10，最大1000                                                                                                                                                                                                                                   |

#### status字段说明

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

### 示例

```requestUrl
http://api.polyv.net/v2/video/search-videos?cateId=1615795867474&uploader=%E4%B8%BB%E8%B4%A6%E5%8F%B7&sign=1BE730A20058481E794D3B5BE27ED9FBF7B491C0&containSubCate=true&pageSize=10&filters=basicInfo%2CmetaData&page=1&sort=creationTimeDesc&userid=1b448be323&ptime=1620289391124&status=60
```

### 响应参数描述

| 参数名     | 类型      | 说明                                                                                                                                                                                              |
| ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code    | Integer | 响应状态码，200为成功返回，非200为失败【详见[全局错误说明](https://git.polyv.net/help-center/document-center/-/blob/master/vod/api/errorInfo/README.md)】                                                                 |
| status  | String  | 响应状态文本信息                                                                                                                                                                                        |
| message | String  | 响应描述信息，当code为400或者500的时候，辅助描述错误原因                                                                                                                                                               |
| data    | Object  | 响应成功时返回搜索结果【详见[data字段说明](https://git.polyv.net/help-center/document-center/-/blob/master/vod/api/video_management/search/search_video.md?id=data%E5%AD%97%E6%AE%B5%E8%AF%B4%E6%98%8E)】，响应失败时返回空 |

#### data字段说明

| 字段         | 类型      | 说明                                                                                                                                                                                           |
| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pageNumber | Integer | 当前的页数                                                                                                                                                                                        |
| totalPages | Integer | 总的页数                                                                                                                                                                                         |
| pageSize   | Integer | 每页条数                                                                                                                                                                                         |
| contents   | Array   | 搜索视频的结果列表【详见[contents字段说明](https://git.polyv.net/help-center/document-center/-/blob/master/vod/api/video_management/search/search_video.md?id=contents%E5%AD%97%E6%AE%B5%E8%AF%B4%E6%98%8E)】 |
| totalItems | Integer | 总的条数                                                                                                                                                                                         |

#### contents字段说明

| 字段             | 类型     | 说明                                                                                                                                                                                                        |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| vid            | String | 视频id                                                                                                                                                                                                      |
| basicInfo      | Object | 视频的详细信息 【详见[basicInfo字段说明](https://git.polyv.net/help-center/document-center/-/blob/master/vod/api/video_management/search/search_video.md?id=basicInfo%E5%AD%97%E6%AE%B5%E8%AF%B4%E6%98%8E)】             |
| metaData       | Object | 视频的元数据 【详见[metaData字段说明](https://git.polyv.net/help-center/document-center/-/blob/master/vod/api/video_management/search/search_video.md?id=metaData%E5%AD%97%E6%AE%B5%E8%AF%B4%E6%98%8E)】                |
| transcodeInfos | Array  | 视频的转码信息列表 【详见[transcodeInfos字段说明](https://git.polyv.net/help-center/document-center/-/blob/master/vod/api/video_management/search/search_video.md?id=transcodeInfos%E5%AD%97%E6%AE%B5%E8%AF%B4%E6%98%8E)】 |
| snapshotInfo   | Object | 视频的截图信息 【详见[snapshotInfo字段说明](https://git.polyv.net/help-center/document-center/-/blob/master/vod/api/video_management/search/search_video.md?id=snapshotInfo%E5%AD%97%E6%AE%B5%E8%AF%B4%E6%98%8E)】       |

#### basicInfo字段说明

| 字段           | 类型      | 说明                           |
| ------------ | ------- | ---------------------------- |
| title        | String  | 视频标题                         |
| description  | String  | 视频描述                         |
| duration     | Long    | 源视频时长，单位：秒                   |
| thumbnailURL | String  | 首图地址，小图                      |
| coverURL     | String  | 首图地址，大图                      |
| creationTime | String  | 创建时间，格式为：yyyy-MM-dd HH:mm:ss |
| updateTime   | String  | 更新时间，格式为：yyyy-MM-dd HH:mm:ss |
| size         | Long    | 源文件大小，单位：Bytes               |
| status       | Integer | 视频状态码                        |
| cateId       | Long    | 分类id；其中1为根目录，即"默认分类"         |
| cateName     | String  | 分类名称                         |
| tags         | String  | 标签                           |
| uploader     | String  | 上传者                          |
| playTimes    | Integer | 播放次数                         |
| md5Checksum  | String  | 视频源文件校验md5校验和                |

#### metaData字段说明

| 字段       | 类型      | 说明                 |
| -------- | ------- | ------------------ |
| size     | Long    | 源文件大小，单位：Bytes     |
| format   | String  | 视频容器类型，如mp4、flv等   |
| duration | Long    | 源视频时长，单位：秒         |
| bitrate  | Integer | 视频码率，单位：kbps       |
| fps      | Integer | 视频帧率               |
| height   | Integer | 分辨率高，单位：px         |
| width    | Integer | 分辨率宽，单位：px         |
| codec    | String  | 编码格式，例如：h264、h265等 |

#### transcodeInfos字段说明

| 字段         | 类型      | 说明                                                   |
| ---------- | ------- | ---------------------------------------------------- |
| playUrl    | String  | 播放地址                                                 |
| definition | String  | <p>清晰度<br>SOURCE：原清晰度<br>LD：普清<br>SD：标清<br>HD：高清</p> |
| bitrate    | Integer | 码率kbps                                               |
| duration   | Long    | 时长，秒                                                 |
| encrypt    | Boolean | <p>是否加密<br>true：加密视频<br>false：非加密</p>                |
| format     | String  | 转码格式，如mp4、flv、pdx、hls                                |
| fps        | Integer | 视频帧率                                                 |
| height     | Integer | 分辨率高，单位：px                                           |
| width      | Integer | 分辨率宽，单位：px                                           |
| status     | String  | <p>视频状态<br>normal：可以正常播放<br>unavailable：不能正常播放</p>   |

#### snapshotInfo字段说明

| 字段          | 类型        | 说明         |
| ----------- | --------- | ---------- |
| imageUrl    | String\[] | 截图url数组，小图 |
| bigImageUrl | String\[] | 截图url数组，大图 |

### Java请求示例

快速接入基础代码请下载相关依赖源码， [点击下载源代码](https://git.polyv.net/help-center/document-center/-/blob/master/third_res/util.zip) ,下载后加入到自己的源码工程中即可。测试用例中的**HttpUtil.java 和 VodSignUtil.java** 都包含在下载文件中。

> 强烈建议您使用[点播Java SDK](https://git.polyv.net/help-center/document-center/-/blob/master/vod/java/README.md)完成API的功能对接，点播Java SDK 对API调用逻辑、异常处理、数据签名、HTTP请求线程池进行了统一封装和优化。

```java
private static final Logger log = LoggerFactory.getLogger(VodSearchTest.class);
/**
 * 搜索视频
 * @throws Exception
 * @throws NoSuchAlgorithmException
 */
@Test
public void testSearchVideo() throws Exception, NoSuchAlgorithmException {
    //公共参数,填写自己的实际参数
    String secretKey = super.secretKey;
    String userId = super.userId;
    String ptime = String.valueOf(System.currentTimeMillis());
    //业务参数
    String url = "http://api.polyv.net/v2/video/search-videos";
    String filters = "basicInfo,metaData";
    String cateId = "1615795867474";
    String uploader = "主账号";
    String status = "60";
    String containSubCate = "true";
    String page = "1";
    String pageSize = "10";
    String sort = "creationTimeDesc";

    Map<String, String> requestMap = new HashMap<>();
    requestMap.put("userid", userId);
    requestMap.put("ptime", ptime);
    requestMap.put("cateId", cateId);
    requestMap.put("filters", filters);
    requestMap.put("uploader", uploader);
    requestMap.put("status", status);
    requestMap.put("containSubCate", containSubCate);
    requestMap.put("page", page);
    requestMap.put("pageSize", pageSize);
    requestMap.put("sort", sort);
    requestMap.put("sign", VodSignUtil.getSign(requestMap, secretKey));
    String response = HttpUtil.get(url, requestMap);
    log.debug("测试搜索视频,{}", response);
    //do somethings

}
```

### 响应示例

系统全局错误说明详见[全局错误说明](https://git.polyv.net/help-center/document-center/-/blob/master/vod/api/errorInfo/README.md)

成功示例

```json
{
  "code": 200,
  "status": "success",
  "message": "success",
  "data": {
    "pageNumber": 1,
    "totalPages": 1,
    "pageSize": 10,
    "contents": [
      {
        "vid": "1b448be32389acdf41f567e3a0bf0c19_1",
        "basicInfo": {
          "title": "3-25测试裁剪",
          "description": "",
          "duration": 81,
          "coverURL": "https://img.videocc.net/uimage/1/1b448be323/9/1b448be32389acdf41f567e3a0bf0c19_0_b.jpg",
          "creationTime": "2021-03-25 14:33:29",
          "updateTime": "2021-03-25 14:35:22",
          "size": 3101307,
          "status": 61,
          "cateId": 1616654004170,
          "cateName": "fx20lh79cf",
          "tags": "2191541_fx20lh79cf-2e77d0a29c11adbf9fea7a1a206fa666|ppt|playback",
          "uploader": "API",
          "playTimes": 1
        },
        "metaData": {
          "size": 3101307,
          "format": "m3u8",
          "duration": 81,
          "bitrate": 0,
          "fps": 25,
          "height": 720,
          "width": 1280,
          "codec": "h264"
        }
      },
      {
        "vid": "1b448be3230e2235bc8f43c3aafa23b5_1",
        "basicInfo": {
          "title": "合并后文件名1234",
          "description": "",
          "duration": 321,
          "coverURL": "https://img.videocc.net/uimage/1/1b448be323/5/1b448be3230e2235bc8f43c3aafa23b5_0_b.jpg",
          "creationTime": "2021-03-15 16:11:08",
          "updateTime": "2021-03-15 16:16:21",
          "size": 19117170,
          "status": 61,
          "cateId": 1615795867478,
          "cateName": "fwr2dfsptr",
          "tags": "2191541_fwr2dfsptr-b90e4e77230c24f895b1ffeabe3059cb|ppt|playback",
          "uploader": "API",
          "playTimes": 0
        },
        "metaData": {
          "size": 19117170,
          "format": "m3u8",
          "duration": 321,
          "bitrate": 0,
          "fps": 25,
          "height": 720,
          "width": 1280,
          "codec": "h264"
        }
      }
    ],
    "totalItems": 2
  }
}
```

异常示例

签名不正确

```json
{
  "code":400,
  "status":"error",
  "message":"the sign is not right",
  "data":""
}
```

时间戳过期

```json
{
    "code": 400,
    "status": "error",
    "message": "ptime is too old.",
    "data": ""
}
```

内部错误，或传了非法参数，程序转换异常

```json
{
    "code": 500,
    "status": "fail",
    "message": "undefined error",
    "data": null
}
```
