飞书开放平台 Server API 文档

主题

素材概述 ​

本文档介绍云空间中素材相关能力的基础概念、相关接口和 extra 参数说明等。

基础概念 ​

素材指在文档、电子表格、多维表格等中用到的资源素材，如文档中的图片、视频或文件等。每个素材都有唯一的 token 作为标识。

素材 token 获取方式 ​

飞书开放平台支持在在线文档、电子表格、多维表格中上传和下载素材。在不同的云文档中，素材 token 的获取方式不同。具体方式如下所示：

素材所在文档类型素材 token 获取方式
在线文档通过获取文档所有块接口获取指定文件块（File Block）或图片块（Image Block）等，其中的 token 参数即为素材 token。
电子表格通过读取多个范围接口获取指定附件的 fileToken 参数，即为素材的 token。
多维表格通过查询记录接口获取指定附件的 file_token参数，即为素材的 token。

上传素材说明 ​

上传素材指将本地环境的各类文件上传至云文档中。飞书开放平台支持在在线文档、电子表格、多维表格中上传素材。

Warning: 上传素材相关接口不支持并发调用，且调用频率上限为 5 QPS，10000 次/天。否则会返回 1061045 错误码，可通过稍后重试解决。

上传点类型和上传点 token ​

要将指定素材上传到指定云文档中，你需先确定上传点的类型（parent_type）和上传点的 token（parent_node），再调用上传接口。下表列出不同上传场景对应的上传点类型和上传点 token 说明。

Note 要在知识库文档中上传图片或文件，你需先调用获取知识空间节点信息获取当前知识库文档的实际 token，再根据下列上传场景，确定上传点 token 的值。

上传场景上传点类型（parent_type）上传点 token （parent_node）token 示例值
在新版文档中上传图片docx_image传入新版文档块的唯一标识 block_id，表示将图片素材上传到新版文档的指定图片块中。了解在文档中插入图片的完整步骤，参考文档常见问题-如何插入图片。doxcnXgNGAtaAraIRVeCfmabcef
在新版文档中上传文件docx_file传入新版文档块的唯一标识 block_id，表示将文件素材上传到新版文档的指定文件块中。了解在文档中插入文件的完整步骤，参考文档常见问题-如何插入文件/附件。doxcnXgNGAtaAraIRVeCfmabcef
在电子表格中上传图片sheet_image传入电子表格的唯一标识 spreadsheet_token，表示将图片素材上传到指定电子表格中，点击了解如何获取云文档 token。图片完成上传后，你可继续使用写入图片等接口将图片写入电子表格具体位置。MRLOWBf6J47ZUjmwYRsN8uabcef
在电子表格中上传文件sheet_file传入电子表格的唯一标识 spreadsheet_token，表示将文件素材上传到指定电子表格中，点击了解如何获取云文档 token。MRLOWBf6J47ZUjmwYRsN8uabcef
在多维表格中上传图片bitable_image传入多维表格的唯一标识 app_token，表示将图片素材上传到指定多维表格中，点击了解如何获取云文档 token。 了解在多维表格中插入图片的完整步骤，参考多维表格常见问题-如何在多维表格中上传附件。Pc9OpwAV4nLdU7lTy71t6Kabcef
在多维表格中上传文件bitable_file传入多维表格的唯一标识 app_token，表示将文件素材上传到指定多维表格中，点击了解如何获取云文档 token。了解在多维表格中插入附件的完整步骤，参考多维表格常见问题-如何在多维表格中上传附件。Pc9OpwAV4nLdU7lTy71t6Kabcef
上传素材至云空间ccm_import_open无需填写，该场景用于导入文件，详情参考导入文件概述。/
在旧版文档中上传图片（旧版文档已下线，已不推荐使用）doc_image传入旧版文档的唯一标识 doc_token，表示将图片素材上传到指定旧版文档中，点击了解如何获取云文档 token。2olt0Ts4Mds7j7iqzdwrqEabcef
在旧版文档中上传文件（旧版文档已下线，已不推荐使用）doc_file传入旧版文档的唯一标识 doc_token，表示将文件素材上传到指定旧版文档中，点击了解如何获取云文档 token。2olt0Ts4Mds7j7iqzdwrqEabcef

接口说明 ​

飞书开放平台提供了多个上传素材接口。你需根据上传素材的大小，选择合适的方式：

  • 若当前网络连接稳定且素材大小不超过 20 MB，直接调用上传素材；
  • 若当前网络连接不稳定，或素材大小超过 20 MB，你需依次调用以下分片上传素材接口，对素材定长分片上传，减少单次带宽使用，提高上传成功率。该上传方式支持开发者依据分片上传进度展示整体素材的上传进度，且支持一天内恢复上传。

    1. 分片上传素材-预上传

      发送初始化请求，以获取上传事务 ID 和分片策略，为上传素材分片做准备。平台固定以 4MB 的大小对素材进行分片。

    2. 分片上传素材-上传分片

      根据预上传接口返回的上传事务 ID 和分片策略上传对应的素材分片。

    3. 分片上传素材-完成上传

      调用上传分片接口将分片全部上传完毕后，你可调用本接口触发完成上传。

extra 参数说明 ​

对于以下上传与下载素材场景，你需要填写 extra 参数。

Warning: - extra 参数类型为字符串，对象类型需要转成字符串作为入参。 如果是直接通过 URL 进行访问，需要对字符串进行 URL 编码，将其放置在 URL 查询中。

  • API 调试台页面填写的 extra 参数无需编码转义。

上传素材至云文档 ​

在以下上传场景中，需通过 extra 参数传入素材所在云文档的 token。extra 参数的格式为 "{\"drive_route_token\":\"素材所在云文档的 token\"}"。以下示例值未转义，实际使用中请注意转义。

上传场景extra 参数值示例（未转义）云文档 token 获取方式
在文档中上传图片{"drive_route_token":"doxcnXgNGAtaAraIRVeCfmabcef"}参考文档概述获取 token，即文档的 document_id。
在文档中上传文件{"drive_route_token":"doxcnXgNGAtaAraIRVeCfmabcef"}参考文档概述获取 token，即文档的 document_id。
在电子表格中上传图片{"drive_route_token":"MRLOWBf6J47ZUjmwYRsN8uabcef"}参考电子表格概述获取 token，即电子表格的 spreadsheetToken。
在电子表格中上传文件{"drive_route_token":"MRLOWBf6J47ZUjmwYRsN8uabcef"}参考电子表格概述获取 token，即电子表格的 spreadsheetToken。
在多维表格中上传图片{"drive_route_token":"Pc9OpwAV4nLdU7lTy71t6Kabcef"}参考多维表格概述获取多维表格的 token。
在多维表格中上传文件{"drive_route_token":"Pc9OpwAV4nLdU7lTy71t6Kabcef"}参考多维表格概述获取多维表格的 token。

上传素材至云空间 ​

上传素材至云空间的场景通常与导入文件场景关联，详情参考导入文件概述。在该场景下，上传点类型（parent_type）为 ccm_import_open，上传点 token（parent_node）无需填写。extra 参数需要填入 json 序列化后的字符串。填写示例如下所示。

  • 将本地文件扩展名为 txt 的文件导入为新版文档：

    json
    "{ "obj_type": "docx","file_extension": "txt"}"

  • 将本地文件扩展名为 xlsx 的文件导入为电子表格：

    "{ "obj_type": "sheet","file_extension": "xlsx"}"

  • 将本地文件扩展名为 md 的文件导入为新版文档：

    "{ "obj_type": "docx","file_extension": "md"}"

  • 将本地文件扩展名为 markdown 的文件导入为新版文档：

    "{ "obj_type": "docx","file_extension": "markdown"}"

下载多维表格中的素材 ​

对于设置了高级权限的多维表格，在调用下载素材或者获取素材临时下载链接接口时，需要添加 extra 参数作为 URL 查询参数鉴权。若不添加 extra 参数将返回 HTTP 400 状态码。你可通过以下方式获取 extra 参数：

  1. 调用查询记录接口，响应中将包含附件的下载链接，示例如下所示：
json
{
  "code": 0,
  "data": {
    "has_more": false,
    "items": [
      {
        "fields": {
          "附件": [
            {
              "file_token": "RSkabsaphoy6yVxK0mGcggabcef",
              "name": "74d2c703524489dbabcef.png",
              "size": 87123,
              "tmp_url": "https://open.feishu.cn/open-apis/drive/v1/medias/batch_get_tmp_download_url?file_tokens=RSkabsaphoy6yVxK0mGcggabcef&extra={"bitablePerm":{"tableId":"tblz8ExGaVhuiSD1","rev":32}}",  // 素材临时下载链接对应的 URL 值，需要对此字符串进行 URL 编码
              "type": "image/png",
              "url": "https://open.feishu.cn/open-apis/drive/v1/medias/RSkabsaphoy6yVxK0mGcggabcef/download?extra={"bitablePerm":{"tableId":"tblz8ExGaVhuiSD1","rev":32}}"   // 下载素材对应的 URL 值，需要对此字符串进行 URL 编码
            }
          ]
        },
        "record_id": "recbMzD0zT"
      }
    ],
    "total": 1
  },
  "msg": "success"
}

构建 extra 参数的步骤和示例如下所示：

  1. 获取素材所在 table 的 tableId，构建 Extra 对象；
  2. 根据附件所在的字段、记录 ID 和文件 token，填写 attachments 参数。其中 attachments 的第一个 key 为字段 ID，第二个 key 为记录 ID，value 为文件 token 数组；

Warning: attachments 为必填参数。不填可能导致时延过长，接口调用失败。

  1. 序列化 Extra 对象成字符串；
  2. 对此字符串进行 URL 编码，将其放置在 URL 查询中。
JSON
{"bitablePerm":{"tableId":"tblO6OeNZxfabcef","attachments":{"fld32zZi5I":{"rec0BuOHq":["boxbcsQNT0JsmrztOnX530abcef"]}}}}
// 转义后
https://open.feishu.cn/open-apis/drive/v1/medias/boxbcsQNT0JsmrztOnX530abcef/download?extra=%7B%22bitablePerm%22%3A%7B%22tableId%22%3A%22tblO6OeNZxfabcef%22%2C%22attachments%22%3A%7B%22fld32zZi5I%22%3A%7B%22rec0BuOHq%22%3A%5B%22boxbcsQNT0JsmrztOnX530abcef%22%5D%7D%7D%7D%7D

方法列表 ​

以下为素材的方法列表。其中，“商店”代表应用商店应用；“自建”代表企业自建应用，了解更多应用相关信息，参考应用类型简介。了解调用服务端 API 的流程，参考流程概述。

方法 (API)权限要求（满足任一）访问凭证（选择其一）商店自建
[上传素材](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/upload_all)POST /open-apis/drive/v1/medias/upload_allbitable:app 查看、评论、编辑和管理多维表格 docs:doc 查看、评论、编辑和管理文档 docs:document.media:upload 上传图片和附件到云文档中 drive:drive 查看、评论、编辑和管理云空间中所有文件sheets:spreadsheet 查看、评论、编辑和管理电子表格tenant_access_token``user_access_token✓✓
[下载素材](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/download)GET /open-apis/drive/v1/medias/:file_token/downloadbitable:app 查看、评论、编辑和管理多维表格sheets:spreadsheet:readonly 查看、评论和导出电子表格docs:doc 查看、评论、编辑和管理文档docs:doc:readonly 查看、评论和导出文档docs:document.media:download 下载云文档中的图片和附件drive:drive 查看、评论、编辑和管理云空间中所有文件drive:drive:readonly 查看、评论和下载云空间中所有文件sheets:spreadsheet 查看、评论、编辑和管理电子表格sheets:spreadsheet:readonly 查看、评论和导出电子表格tenant_access_token``user_access_token✓✓
[获取素材临时下载链接](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/batch_get_tmp_download_url)GET /open-apis/drive/v1/medias/batch_get_tmp_download_urlbitable:app 查看、评论、编辑和管理多维表格sheets:spreadsheet:readonly 查看、评论和导出电子表格docs:doc 查看、评论、编辑和管理文档docs:doc:readonly 查看、评论和导出文档docs:document.media:download 下载云文档中的图片和附件drive:drive 查看、评论、编辑和管理云空间中所有文件drive:drive:readonly 查看、评论和下载云空间中所有文件sheets:spreadsheet 查看、评论、编辑和管理电子表格sheets:spreadsheet:readonly 查看、评论和导出电子表格tenant_access_token``user_access_token✓✓
[分片上传素材-预上传](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/upload_prepare)POST /open-apis/drive/v1/medias/upload_preparebitable:app 查看、评论、编辑和管理多维表格docs:doc 查看、评论、编辑和管理文档docs:document.media:upload 上传图片和附件到云文档中drive:drive 查看、评论、编辑和管理云空间中所有文件sheets:spreadsheet 查看、评论、编辑和管理电子表格tenant_access_token``user_access_token✓✓
[分片上传素材-上传分片](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/upload_part)POST /open-apis/drive/v1/medias/upload_partbitable:app 查看、评论、编辑和管理多维表格docs:doc 查看、评论、编辑和管理文档docs:document.media:upload 上传图片和附件到云文档中drive:drive 查看、评论、编辑和管理云空间中所有文件sheets:spreadsheet 查看、评论、编辑和管理电子表格tenant_access_token``user_access_token✓✓
[分片上传素材-完成上传](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/upload_finish)POST /open-apis/drive/v1/medias/upload_finishbitable:app 查看、评论、编辑和管理多维表格docs:doc 查看、评论、编辑和管理文档docs:document.media:upload 上传图片和附件到云文档中drive:drive 查看、评论、编辑和管理云空间中所有文件sheets:spreadsheet 查看、评论、编辑和管理电子表格tenant_access_token``user_access_token✓✓

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有