下载素材

下载各类云文档中的素材，例如电子表格中的图片。该接口支持通过在请求头添加Range 参数分片下载素材。

前提条件

调用此接口之前，你需确保应用已拥有素材的下载权限。否则接口将返回 403 的 HTTP 状态码。参考云空间常见问题第 3 点了解如何分享素材的下载权限给应用。更多云文档接口权限问题，参考云文档常见问题。

注意事项

本接口仅支持下载云文档而非云空间中的资源文件。如要下载云空间中的资源文件，需调用下载文件接口。

使用限制

该接口调用频率上限为 5 QPS，10000 次/天。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/drive/v1/medias/:file_token/download
HTTP Method	GET
接口频率限制	特殊频控
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	bitable:app 查看、评论、编辑和管理多维表格 bitable:app:readonly 查看、评论和导出多维表格 docs:doc 查看、评论、编辑和管理文档 docs:doc:readonly 查看、评论和导出文档 docs:document.media:download 下载云文档中的图片和附件 drive:drive 查看、评论、编辑和管理云空间中所有文件 drive:drive:readonly 查看、评论和下载云空间中所有文件 sheets:spreadsheet 查看、评论、编辑和管理电子表格 sheets:spreadsheet:readonly 查看、评论和导出电子表格

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

部分下载

名称	类型	必填	描述
Range	string	否	在 HTTP 请求头中，通过指定 Range 来下载素材的部分内容，单位是字节（byte）。该参数的格式为 Range: bytes=start-end，示例值为 Range: bytes=0-1024，表示下载第 0 个字节到第 1024 个字节之间的数据。

路径参数

名称	类型	描述
file_token	string	素材文件的 token。获取方式如下所示： * 新版文档：通过获取文档所有块接口获取指定文件块（File Block）或图片块（Image Block）的 token，即为素材的 token。 * 电子表格：通过读取多个范围接口获取指定附件的 fileToken 参数，即为素材的 token。 * 多维表格：通过查询记录接口获取指定附件的 file_token，即为素材的 token。 示例值："boxcnrHpsg1QDqXAAAyachabcef"

查询参数

名称	类型	必填	描述
extra	string	否	拥有高级权限的多维表格在下载素材时，需要添加额外的扩展信息作为 URL 查询参数鉴权。详情参考素材概述-extra 参数说明。 示例值：无

请求示例

以下代码展示如何使用 cURL 命令下载素材。并将素材命名为 local_file。

# 将 Token 为 file_token 的素材下载到本地，并命名为 local_file，注意 file_token、local_file 和 authorization 要替换为真实值
curl -i -X GET 'https://open.feishu.cn/open-apis/drive/v1/medias/{file_token}/download' -o "{local_file}" \
-H 'Authorization: {authorization}'

响应

响应头

名称	类型	描述
content-type	string	素材文件的MIME
content-disposition	string	文件名

HTTP状态码为 200 时，表示成功

返回文件二进制流

状态码

| HTTP 状态码 | 描述 |
|---|---|---| | 200 | 素材成功下载。返回文件二进制流。 |
| 206 | 下载部分内容成功。接口将返回指定 Range 的部分文件的二进制流。 |
|400 | 对于开启了高级权限的多维表格，你需确保已正确添加额外的扩展信息作为 URL 查询参数鉴权。详情参考素材概述-extra 参数说明。| | 403 | 没有下载素材的权限。要下载云文档中的素材，你需确保调用身份拥有文档资源权限。详情参考云文档常见问题 3开通权限。如果多维表格开启了高级权限，你需确保调用身份拥有可管理权限。 |
| 404 | 素材 token 不存在或素材被删除。请检查 token 是否有误以及素材是否存在。 || | 500 | 服务端内部异常。请重试或联系技术支持。 |

后续操作

接口调用成功后，你可以通过访问你在下载时指定的本地下载目录，对已下载的素材进行下一步操作。