# 上传文件 将指定文件上传至云空间指定目录中。 ## 使用限制 - 文件大小不得超过 20 MB，且不可上传空文件。要上传大于 20 MB 的文件，你需使用分片上传文件相关接口。详情参考[上传文件概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/file/multipart-upload-file-/introduction)。 - 该接口调用频率上限为 5 QPS，10000 次/天。否则会返回 1061045 错误码，可通过稍后重试解决。 ## 请求 基本 |   ---|--- HTTP URL | https://open.feishu.cn/open-apis/drive/v1/files/upload_all HTTP Method | POST 接口频率限制 | [特殊频控](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN) 支持的应用类型 | Custom App、Store App 权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 查看、评论、编辑和管理云空间中所有文件(drive:drive)
上传、下载文件到云空间(drive:file)
上传文件(drive:file:upload) ### 请求头 名称 | 类型 | 必填 | 描述 ---|---|---|--- 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) Content-Type | string | 是 | **示例值**："multipart/form-data; boundary=---7MA4YWxkTrZu0gW" 更多云文档接口权限问题，参考[常见问题](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN)。 ### 请求体 名称 | 类型 | 必填 | 描述 ---|---|---|--- file_name | string | 是 | 要上传的文件的名称。
**示例值**："demo.pdf"
**数据校验规则**：
- 最大长度：`250` 字符 parent_type | string | 是 | 上传点的类型。取固定值 `explorer`，表示将文件上传至云空间中。
**示例值**："explorer"
**可选值有**：
- explorer：云空间 parent_node | string | 是 | 云空间中文件夹的 token。获取方式见[文件夹概述](https://open.feishu.cn/document/ukTMukTMukTM/ugTNzUjL4UzM14CO1MTN/folder-overview)。
**示例值**："fldbcO1UuPz8VwnpPx5a92abcef" size | int | 是 | 文件的大小，单位为字节。
**示例值**：1024
**数据校验规则**：
- 最大值：`20971520` checksum | string | 否 | 文件的 Adler-32 校验和
**示例值**："3248270248" file | file | 是 | 文件的二进制内容
**示例值**：file binary ### cURL示例 ```shell curl --location --request POST 'https://open.feishu.cn/open-apis/drive/v1/files/upload_all' \ --header 'Authorization: Bearer t-e13d5ec1954e82e458f3ce04491c54ea8c9abcef' \ --header 'Content-Type: multipart/form-data' \ --form 'file_name="demo.pdf"' \ --form 'parent_type="explorer"' \ --form 'parent_node="fldbcO1UuPz8VwnpPx5a92abcef"' \ --form 'size="1024"' \ --form 'file=@"/path/demo.pdf"' ``` ### Python示例 ```python import os import requests from requests_toolbelt import MultipartEncoder def upload_file(): file_path = "/path/demo.pdf" file_size = os.path.getsize(file_path) url = "https://open.feishu.cn/open-apis/drive/v1/files/upload_all" form = {'file_name': 'demo.pdf', 'parent_type': 'explorer', 'parent_node': 'fldbcO1UuPz8VwnpPx5a92abcef', 'size': str(file_size), 'file': (open(file_path, 'rb'))} multi_form = MultipartEncoder(form) headers = { 'Authorization': 'Bearer t-e13d5ec1954e82e458f3ce04491c54ea8c9abcef', ## 获取tenant_access_token, 需要替换为实际的token } headers['Content-Type'] = multi_form.content_type response = requests.request("POST", url, headers=headers, data=multi_form) if __name__ == '__main__': upload_file() ``` ### 请求体示例 ```HTTP ---7MA4YWxkTrZu0gW Content-Disposition: form-data; name="file_name"; demo.pdf ---7MA4YWxkTrZu0gW Content-Disposition: form-data; name="parent_type"; explorer ---7MA4YWxkTrZu0gW Content-Disposition: form-data; name="parent_node"; fldbcO1UuPz8VwnpPx5a92abcef ---7MA4YWxkTrZu0gW Content-Disposition: form-data; name="size"; 1024 ---7MA4YWxkTrZu0gW Content-Disposition: form-data; name="checksum"; 3248270248 ---7MA4YWxkTrZu0gW Content-Disposition: form-data; name="file"; Content-Type: application/octet-stream file binary ---7MA4YWxkTrZu0gW ``` ## 响应 ### 响应体 名称 | 类型 | 描述 ---|---|--- code | int | 错误码，非 0 表示失败 msg | string | 错误描述 data | \- | \- file_token | string | 已上传的文件的 token ### 响应体示例 ```json { "code": 0, "msg": "success", "data": { "file_token": "boxcnrHpsg1QDqXAAAyachabcef" } } ``` ### 错误码 HTTP状态码 | 错误码 | 描述 | 排查建议 ---|---|---|--- 200 | 1061001 | internal error. | 服务内部错误，包括超时、错误码没处理等。
**注意**：
上传文件接口不支持直接将文件上传至知识库，请先将文件上传至文件夹后再移动至知识库。 400 | 1061002 | params error. | 请检查请求参数是否正确。
常见错误问题：
1. size入参错误：
- 末尾存在空格
- 大小不能为 0
2. Content-Type 入参错误
- 需要是"multipart/form-data"，非"application/json" 404 | 1061003 | not found. | 请确认对应资源是否存在。 403 | 1061004 | forbidden. | 当前调用身份没有文件或文件夹的阅读或编辑等权限。请参考以下方式解决：
- 若上传素材，请确保当前调用身份具有目标云文档的编辑权限
- 若上传文件，请确保当前调用身份具有文件夹的编辑权限
- 若对文件或文件夹进行增删改等操作，请确保调用身份具有足够文档权限：
- 对于新建文件接口，调用身份需要有目标文件夹的编辑权限
- 对于复制文件接口，调用身份需要有文件的阅读或编辑权限、并且具有目标文件夹的编辑权限
- 对于移动文件接口，调用身份需要有被移动文件的可管理权限、被移动文件所在位置的编辑权限、目标位置的编辑权限
- 对于删除文件接口，调用身份需要具有以下两种权限之一：
- 该应用或用户是文件所有者并且具有该文件所在父文件夹的编辑权限
- 该应用或用户并非文件所有者，但是该文件所在父文件夹的所有者或者拥有该父文件夹的所有权限（full access）
了解开通权限步骤，参考[如何为应用开通云文档相关资源的权限](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-add-permissions-to-app)。 400 | 1061021 | upload id expire. | 上传事务过期，请重头开始上传。 500 | 1061022 | file version conflict. | 文件版本号冲突。 400 | 1061041 | parent node has been deleted. | 请确认上传点未被删除。 400 | 1061042 | parent node out of limit. | 在当前上传点上传过多素材，请更换上传点。 400 | 1061043 | file size beyond limit. | 请检查文件大小以避免超出限制。详情参考飞书帮助中心[云盘文件上传大小限制](https://www.feishu.cn/hc/zh-CN/articles/360049067549)。 400 | 1061044 | parent node not exist. | `parent_node` 不存在。请确认上传点 token 是否有误：
- 对于上传文件接口，请参考[文件夹 token 获取方式](https://open.feishu.cn/document/ukTMukTMukTM/ugTNzUjL4UzM14CO1MTN/folder-overview#-717d325)确认是否填写了正确的文件夹 token
- 对于上传素材接口，请参考[上传点类型和上传点 token](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/introduction#cc82be3c) 确认 `parent_node` 是否填写正确 200 | 1061045 | can retry. | 内部可重试错误，请稍后重试。 400 | 1061109 | file name cqc not passed. | 请确保上传的文件和文件名合规。 400 | 1061101 | file quota exceeded. | 租户容量超限，请确保租户有足够容量进行上传。 403 | 1061500 | mount node point kill. | 挂载点不存在。 400 | 1062007 | upload user not match. | 请确保当前请求身份和上传任务的身份为同一个。 400 | 1062008 | checksum param Invalid. | 请确保文件/文件块的checksum正确。 400 | 1062009 | the actual size is inconsistent with the parameter declaration size. | 实际传输的文件大小和参数说明的大小不符合一致。 400 | 1062010 | block missing, please upload all blocks. | 部分文件分片缺失，请确保所有文件分片上传完成。 400 | 1062011 | block num out of bounds. | 上传过多文件分片，请确保上传的为对应文件。 400 | 1061061 | user quota exceeded. | 个人容量超限，请确保个人有足够容量进行上传。 403 | 1061073 | no scope auth. | 没有申请接口权限。 200 | 1064230 | locked for data migration | 数据迁移中，暂时无法上传。 400 | 1062505 | parent node out of size. | 云空间中所有层级的节点总和超限。上限为 40 万个，请检查节点数量。了解更多，参考[云空间概述](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/files/guide/introduction)。 400 | 1062506 | parent node out of depth. | 云空间目录深度超限制（15限制）。 400 | 1062507 | parent node out of sibling num. | 云空间中根目录或文件夹的单层节点超限。上限为 1500 个，你可通过将文件新建到不同文件夹中解决。