# 获取文件夹中的文件清单
该接口用于获取用户云空间指定文件夹中文件信息清单。文件的信息包括名称、类型、token、创建时间、所有者 ID 等。
**注意事项**：了解如何让应用（tenant_access_token）访问个人云空间中的文件夹，参考[云空间常见问题](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/faq)。
## 使用限制
本接口仅支持获取当前层级的文件信息，不支持递归获取子文件夹中的文件信息清单。
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/drive/v1/files
HTTP Method | GET
接口频率限制 | [20 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 查看、评论、编辑和管理云空间中所有文件(drive:drive)
查看、评论和下载云空间中所有文件(drive:drive:readonly)
获取云空间文件夹下的云文档清单(space:document:retrieve)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
获取用户 user ID(contact:user.employee_id:readonly)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
或
`user_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
### 查询参数
名称 | 类型 | 必填 | 描述
---|---|---|---
page_size | int | 否 | 指定每页显示的数据项的数量，默认值为100。若获取根目录下的清单，将返回全部数据
**示例值**：50
**数据校验规则**：
- 最大值：`200`
page_token | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
**示例值**：MTY1NTA3MTA1OXw3MTA4NDc2MDc1NzkyOTI0Nabcef
folder_token | string | 否 | 文件夹的 token。不填写或填空字符串，将获取用户云空间根目录下的清单，且不支持分页和返回快捷方式。了解如何获取文件夹 token，参考[文件夹概述](https://open.feishu.cn/document/ukTMukTMukTM/ugTNzUjL4UzM14CO1MTN/folder-overview)。
**示例值**：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](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)
- user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。[了解更多：如何获取 User ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)
**默认值**：`open_id`
**当值为 `user_id`，字段权限要求**：
获取用户 user ID(contact:user.employee_id:readonly)
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
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. | 服务内部错误，如超时等，请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)。
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）