获取文件夹中的文件清单
该接口用于获取用户云空间指定文件夹中文件信息清单。文件的信息包括名称、类型、token、创建时间、所有者 ID 等。
Tip: 了解如何让应用（tenant_access_token）访问个人云空间中的文件夹，参考云空间常见问题。
使用限制
本接口仅支持获取当前层级的文件信息，不支持递归获取子文件夹中的文件信息清单。
请求
| 项目 | 值 |
|---|---|
| HTTP URL | https://open.feishu.cn/open-apis/drive/v1/files |
| HTTP Method | GET |
| 接口频率限制 | 20 次/秒 |
| 支持的应用类型 | custom,isv |
| 权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可 | drive:drive 查看、评论、编辑和管理云空间中所有文件 drive:drive:readonly 查看、评论和下载云空间中所有文件 space:document:retrieve 获取云空间文件夹下的云文档清单 |
| 字段权限要求 | > Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID |
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Authorization | string | 是 | tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token |
查询参数
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
page_size | int | 否 | 指定每页显示的数据项的数量，默认值为100。若获取根目录下的清单，将返回全部数据 示例值：50 数据校验规则： - 最大值： 200 |
page_token | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果 示例值：MTY1NTA3MTA1OXw3MTA4NDc2MDc1NzkyOTI0Nabcef |
folder_token | string | 否 | 文件夹的 token。不填写或填空字符串，将获取用户云空间根目录下的清单，且不支持分页和返回快捷方式。了解如何获取文件夹 token，参考文件夹概述。 示例值：fldbcO1UuPz8VwnpPx5a9abcef |
order_by | string | 否 | 定义清单中文件的排序方式 示例值：EditedTime 可选值有： - EditedTime: 按编辑时间排序 - CreatedTime: 按创建时间排序默认值： EditedTime |
direction | string | 否 | 定义清单中文件的排序规则，与 order_by 配合使用 示例值：DESC 可选值有： - ASC: 按升序排序 - DESC: 按降序排序默认值： DESC |
user_id_type | string | 否 | 用户 ID 类型 示例值：open_id 可选值有： - open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？默认值： open_id当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID |
响应
响应体
| 名称 | 类型 | 描述 |
|---|---|---|
code | int | 错误码，非 0 表示失败 |
msg | string | 错误描述 |
data | \- | - |
└ files | file\[\] | 文件夹中的文件清单列表 |
└ token | string | 文件标识 |
└ name | string | 文件名 |
└ type | string | 文件类型。可选值有： - doc：旧版文档- sheet：表格- mindnote：思维导图- bitable：多维表格- file：文件- docx：新版文档- folder：文件夹- shortcut: 快捷方式 |
└ parent_token | string | 父文件夹标识 |
└ url | string | 文件在浏览器中的 URL 链接 |
└ shortcut_info | shortcut_info | 快捷方式类型文件的信息 |
└ target_type | string | 快捷方式指向的原文件类型，包括： - doc：旧版文档- sheet：表格- mindnote：思维导图- bitable：多维表格- file：文件- docx：新版文档 |
└ target_token | string | 快捷方式指向的原文件 token |
└ created_time | string | 文件创建时间，秒级时间戳 |
└ modified_time | string | 文件最近修改时间，秒级时间戳 |
└ owner_id | string | 文件所有者的 ID。ID 类型由查询参数中的 user_id_type 决定 |
└ next_page_token | string | 分页标记，当 has_more 为 true 时，会同时返回下一次遍历的 page_token，否则不返回。 |
└ has_more | boolean | 是否还有更多项 |
响应体示例
json
{
"code":0,
"data":{
"files":[
{
"name":"test pdf.pdf",
"parent_token":"fldbcO1UuPz8VwnpPx5a9abcef",
"token":"boxbc0dGSMu23m7QkC1bvabcef",
"type":"file",
"created_time":"1679277808",
"modified_time":"1679277808",
"owner_id":"ou_20b31734443364ec8a1df89fdf325b44",
"url":"https://feishu.cn/file/boxbc0dGSMu23m7QkC1bvabcef"
},
{
"name":"test file.docx",
"parent_token":"fldcnCEG903UUB4fUqfysdabcef",
"shortcut_info":{
"target_token":"boxcnRPaXpD4I6Je9t8k8babcef",
"target_type":"file"
},
"token":"nodcnVkiLQ6LD4CsUEaANrabcef",
"type":"shortcut",
"created_time":"1679295364",
"modified_time":"1679295364",
"owner_id":"ou_20b31734443364ec8a1df89fdf325b44",
"url":"https://feishu.cn/file/boxcnRPaXpD4I6Je9t8k8babcef"
},
{
"name":"test docx",
"parent_token":"fldcnCEG903UUB4fUqfysdabcef",
"token":"doxcntan34DX4QoKJu7jJyabcef",
"type":"docx",
"created_time":"1679295364",
"modified_time":"1679295364",
"owner_id":"ou_20b31734443364ec8a1df89fdf325b44",
"url":"https://feishu.cn/docx/doxcntan34DX4QoKJu7jJyabcef"
},
{
"name":"test sheet",
"parent_token":"fldcnCEG903UUB4fUqfysdabcef",
"token":"shtcnOko1Ad0HU48HH8KHuabcef",
"type":"sheet",
"created_time":"1679295364",
"modified_time":"1679295364",
"owner_id":"ou_20b31734443364ec8a1df89fdf325b44",
"url":"https://feishu.cn/sheets/shtcnOko1Ad0HU48HH8KHuabcef"
}
],
"has_more":false
},
"msg":"success"
}错误码
| HTTP状态码 | 错误码 | 描述 | 排查建议 |
|---|---|---|---|
| 500 | 1061001 | internal error. | 服务内部错误，如超时等，请联系技术支持。 |
| 400 | 1061002 | params error. | 请检查请求参数是否正确。 |
| 404 | 1061003 | not found. | 请确认对应资源是否存在。 |
| 403 | 1061004 | forbidden. | 请确认当前身份是否有对应上传节点的权限，如用户是否有上传到指定doc的编辑权限。 |
| 401 | 1061005 | auth failed. | 请使用有效的 access token 访问该接口。 |
| 404 | 1061007 | file has been delete. | 请确认对应节点未被删除。 |
| 400 | 1064001 | page size out of limit. | 请检查分页大小是否超过限制。（最大值为200） |