## 获取文件列表

### 基本信息

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

### 接口说明

获取指定目录中的文件和文件夹列表，支持分页、排序以及按文件类型、后缀名和星标状态筛选。

### 接口地址

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

### 请求方式

```
GET
```

### 认证方式

```
Authorization: Bearer access_token
```

### 请求参数

| 参数名        | 类型     | 必填 | 默认值       | 说明                                                     | 约束/示例     |
|:-----------|:-------|:---|:----------|:-------------------------------------------------------|:----------|
| cid        | string | 否  | "0"       | 目录ID，对应 `parent_id`；根目录ID为 `0`                         | "0"       |
| type       | int    | 否  | 0         | 文件类型，见下方枚举表格                                          | 1         |
| limit      | int    | 否  | 20        | 查询数量，最大1150                                            | 20        |
| offset     | int    | 否  | 0         | 查询起始位置                                                 | 0         |
| suffix     | string | 否  | ""        | 文件后缀名                                                  | "pdf"     |
| asc        | int    | 否  | 0         | 排序方向：1-升序，0-降序                                        | 0         |
| o          | string | 否  | user_ptime | 排序字段，见下方枚举表格                                          | file_name |
| custom_order | int    | 否  | 0         | 排序模式，见下方枚举表格                                          | 0         |
| stdir      | int    | 否  | 0         | 筛选文件时是否显示文件夹：1-显示，0-不显示                              | 1         |
| star       | int    | 否  | 0         | 星标筛选：1-仅显示星标文件，0-全部                                  | 0         |
| cur        | int    | 否  | 0         | 是否只显示当前文件夹内的文件：1-是，0-否                              | 1         |
| show_dir   | int    | 否  | 0         | 是否显示目录：1-是，0-否                                        | 0         |

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

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

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

| 值          | 说明     | 备注 |
|:-----------|:-------|:---|
| file_name  | 文件名    | -  |
| file_size  | 文件大小   | -  |
| user_ptime | 上传时间   | 默认值 |
| user_utime | 更新时间   | -  |
| file_type  | 文件类型   | -  |

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

| 值 | 说明                    | 备注 |
|:--|:----------------------|:---|
| 0 | 使用记忆排序，自定义排序失效       | 默认值 |
| 1 | 使用自定义排序，不使用记忆排序      | -  |
| 2 | 使用自定义排序，非文件夹置顶       | -  |

### 请求示例

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

### 响应字段说明

| 字段                    | 类型       | 描述                                                        |
|:----------------------|:---------|:----------------------------------------------------------|
| data                  | object[] | 文件和文件夹列表                                                   |
| data[].fid            | string   | 文件或文件夹ID                                                   |
| data[].aid            | string   | 文件状态：1-正常，7-已删除(回收站)，120-彻底删除                            |
| data[].pid            | string   | 父目录ID                                                      |
| data[].fc             | string   | 文件分类：0-文件夹，1-文件                                         |
| data[].fn             | string   | 文件或文件夹名称                                                  |
| data[].fco            | string   | 文件夹封面                                                      |
| data[].ism            | string   | 是否星标，1表示星标                                                |
| data[].isp            | int      | 是否加密，1表示加密                                                |
| data[].pc             | string   | 文件提取码                                                      |
| data[].upt            | int      | 修改时间                                                       |
| data[].uet            | int      | 修改时间                                                       |
| data[].uppt           | int      | 上传时间                                                       |
| data[].cm             | int      | 特殊目录标识                                                     |
| data[].fdesc          | string   | 文件备注                                                       |
| data[].ispl           | int      | 是否统计文件夹下视频时长                                               |
| data[].fl             | object[] | 文件标签                                                       |
| data[].fl[].id        | string   | 文件标签ID                                                     |
| data[].fl[].name      | string   | 文件标签名称                                                     |
| data[].fl[].sort      | string   | 文件标签排序                                                     |
| data[].fl[].color     | string   | 文件标签颜色                                                     |
| data[].fl[].is_default | int      | 文件标签类型：0-最近使用，1-非最近使用，2-默认标签                            |
| data[].fl[].update_time | int      | 文件标签更新时间                                                  |
| data[].fl[].create_time | int      | 文件标签创建时间                                                  |
| data[].sha1           | string   | 文件SHA-1值                                                   |
| data[].fs             | int      | 文件大小，单位为字节                                                |
| data[].fta            | string   | 文件状态：0或2-未上传完成，1-已上传完成                                  |
| data[].ico            | string   | 文件后缀名                                                      |
| data[].fatr           | string   | 音频长度                                                       |
| data[].isv            | int      | 是否为视频                                                      |
| data[].def            | int      | 视频清晰度：1-标清，2-高清，3-超清，4-1080P，5-4K，100-原画                  |
| data[].def2           | int      | 视频清晰度：1-标清，2-高清，3-超清，4-1080P，5-4K，100-原画                  |
| data[].play_long      | int      | 音视频时长，单位为秒                                                |
| data[].v_img          | string   | 视频缩略图地址                                                    |
| data[].thumb          | string   | 图片缩略图地址                                                    |
| data[].uo             | string   | 原图地址                                                       |
| count                 | int      | 当前目录文件数量                                                   |
| sys_count             | int      | 系统文件夹数量                                                    |
| offset                | int      | 偏移量                                                        |
| limit                 | int      | 分页数量                                                       |
| aid                   | string   | 文件状态：1-正常，7-已删除(回收站)，120-彻底删除                            |
| cid                   | int      | 父目录ID                                                      |
| is_asc                | int      | 排序方向：1-升序，0-降序                                            |
| min_size              | int      | 最小文件大小筛选值                                                  |
| max_size              | int      | 最大文件大小筛选值                                                  |
| sys_dir               | string   | 系统目录                                                       |
| hide_data             | string   | 是否返回文件数据                                                  |
| record_open_time      | string   | 是否记录文件夹打开时间                                                |
| star                  | int      | 是否星标：1-星标，0-未星标                                           |
| type                  | int      | 一级筛选大分类，见请求参数中的 `type` 字段枚举                               |
| suffix                | string   | 一级筛选选择“其他”时填写的后缀名                                        |
| path                  | object[] | 父目录树                                                       |
| path[].name           | string   | 父目录名称                                                      |
| path[].aid            | int      | 父目录文件状态                                                    |
| path[].cid            | int      | 父目录ID                                                      |
| path[].pid            | int      | 上级父目录ID                                                    |
| path[].isp            | int      | 父目录是否加密                                                   |
| path[].p_cid          | string   | 父目录路径标识                                                    |
| path[].fv             | string   | 父目录属性                                                      |
| cur                   | int      | 是否只显示当前文件夹内的文件                                            |
| stdir                 | int      | 筛选文件时是否显示文件夹                                               |
| fields                | string   | 指定返回字段                                                     |
| order                 | string   | 实际使用的排序字段                                                  |
| state                 | boolean  | 接口状态，true表示成功                                              |
| code                  | int      | 异常码                                                        |
| message               | string   | 异常信息                                                       |

### 响应示例

```json
{
  "data": [],
  "count": 0,
  "sys_count": 0,
  "offset": 0,
  "limit": 20,
  "aid": "1",
  "cid": 0,
  "is_asc": 0,
  "min_size": 0,
  "max_size": 0,
  "sys_dir": "",
  "hide_data": "",
  "record_open_time": "",
  "star": 0,
  "type": 0,
  "suffix": "",
  "path": [],
  "cur": 0,
  "stdir": 0,
  "fields": "",
  "order": "user_ptime",
  "state": true,
  "code": 0,
  "message": ""
}
```

### 注意事项

- `limit` 最大为1150。
- 当 `cid` 指向不存在或已删除的目录时，接口返回异常；当目录为加密目录时，不返回目录内容。
- `user_id` 由服务端根据 access token 获取，无需传入。

### 修改历史

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