## 文件搜索

### 基本信息

| 属性         | 内容                               |
|:-----------|:---------------------------------|
| 接口名称       | 文件搜索                             |
| 接口版本       | v1.0                             |
| 接口路径       | /search                          |
| 请求方法       | GET                              |
| 接口状态       | 生产环境                             |

### 接口说明

根据文件名搜索文件或文件夹，支持按目录、文件标签、时间范围和文件类型筛选。

### 接口地址

```
https://proapi.115.com/open/ufile/search
```

### 请求方式

```
GET
```

### 认证方式

```
Authorization: Bearer access_token
```

### 请求参数

| 参数名         | 类型     | 必填 | 默认值 | 说明                                                        | 约束/示例    |
|:------------|:-------|:---|:----|:----------------------------------------------------------|:---------|
| search_value | string | 否  | ""  | 搜索关键词；与 `file_label` 至少传一个，最多取前40个字符                  | "文件"     |
| limit       | int    | 否  | 20  | 单页记录数；`offset + limit` 最大不超过10000                         | 20       |
| offset      | int    | 否  | 0   | 数据显示偏移量                                                   | 0        |
| file_label  | string | 否  | ""  | 文件标签；与 `search_value` 至少传一个                              | "1"      |
| cid         | int    | 否  | 0   | 目标目录ID；`-1` 表示不返回任何列表内容                                | 0        |
| gte_day     | string | 否  | ""  | 搜索结果匹配的开始日期                                                | 2020-11-19 |
| lte_day     | string | 否  | ""  | 搜索结果匹配的结束日期                                                | 2020-11-20 |
| fc          | int    | 否  | 0   | 显示类型：1-只显示文件夹，2-只显示文件，0-全部                              | 0        |
| type        | int    | 否  | 0   | 一级筛选大分类，见下方枚举表格                                          | 1        |
| suffix      | string | 否  | ""  | 一级筛选选择“其他”时填写的后缀名                                        | "pdf"    |

#### 请求参数中的 type 字段枚举

| 值 | 说明  | 备注 |
|:--|:----|:---|
| 1 | 文档  | -  |
| 2 | 图片  | -  |
| 3 | 音频  | -  |
| 4 | 视频  | -  |
| 5 | 压缩包 | -  |
| 6 | 应用  | -  |

### 请求示例

```shell
curl -G 'https://proapi.115.com/open/ufile/search' \
  -H 'Authorization: Bearer access_token' \
  --data-urlencode 'search_value=文件' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'offset=0'
```

### 响应字段说明

| 字段                 | 类型       | 描述                                      |
|:-------------------|:---------|:----------------------------------------|
| count              | int      | 符合条件的文件或文件夹总数                          |
| data               | object[] | 文件或文件夹列表                                |
| data[].file_id     | string   | 文件或文件夹ID                                |
| data[].user_id     | string   | 115账号                                   |
| data[].sha1        | string   | 文件SHA-1值                                |
| data[].file_name   | string   | 文件或文件夹名称                               |
| data[].file_size   | string   | 文件大小                                    |
| data[].user_ptime  | string   | 上传时间                                    |
| data[].user_utime  | string   | 更新时间                                    |
| data[].pick_code   | string   | 文件提取码                                   |
| data[].parent_id   | string   | 父目录ID                                   |
| data[].area_id     | string   | 文件状态：1-正常，7-已删除(回收站)，120-彻底删除          |
| data[].is_private  | int      | 文件是否隐藏：0-未隐藏，1-已隐藏                      |
| data[].file_category | string | 文件属性：1-文件，0-文件夹                          |
| data[].ico         | string   | 文件后缀                                    |
| limit              | int      | 分页数量                                    |
| offset             | int      | 偏移量                                     |
| state              | boolean  | 接口状态，true表示成功                          |
| message            | string   | 异常信息                                    |
| code               | int      | 异常码                                     |

### 响应示例

```json
{
  "count": 0,
  "data": [],
  "limit": 20,
  "offset": 0,
  "state": true,
  "message": "",
  "code": 0
}
```

### 注意事项

- `search_value` 与 `file_label` 至少传一个；搜索关键词最多取前40个字符。
- 当 `offset + limit` 超过10000时，服务端按 `offset=0`、`limit=115` 查询。
- 搜索结果会过滤不属于正常区域的文件；当前账号未开启隐藏文件展示时，也会过滤隐藏文件。
- `user_id` 由服务端根据 access token 获取，无需传入。

### 修改历史

| 修改时间                         | 修改说明 |
|:-----------------------------|:-----|
| 2025年04月01日(周二) 00:00:00 | 创建文档 |