mirror of
https://github.com/truewhile/MeBox.git
synced 2026-09-28 03:06:38 +08:00
truewhile
205 lines
12 KiB
Markdown
205 lines
12 KiB
Markdown
## 获取文件列表
|
||
|
||
### 基本信息
|
||
|
||
| 属性 | 内容 |
|
||
|:-----------|:---------------------------------|
|
||
| 接口名称 | 获取文件列表 |
|
||
| 接口版本 | 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 | 创建文档 |
|