MeBox/115doc/115开放平台/API列表/文件管理/文件搜索.md

文件搜索

基本信息

属性	内容
接口名称	文件搜索
接口版本	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	应用	-

请求示例

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	异常码

响应示例

{
  "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	创建文档