云文档概述
业务介绍
云文档是飞书在线文档、电子表格、多维表格、知识库、云空间等产品的统称。你可以调用云文档的相关接口，完成以下操作：
上传、下载文件
创建、编辑各类在线文档
管理你所有的文件和文件夹、知识库
目前云文档开放能力已覆盖在线文档、电子表格、多维表格、知识库以及云空间等产品，但出于产品定位及战略考虑，思维笔记不在支持范围内。
业务模型
云文档业务域以“资源”为中心进行开放，资源的关系图如下：
Warning
- 根据使用访问凭证的不同 云空间 分为 应用云空间（tenant_access_token）和 个人云空间（user_access_token），应用云空间 无法通过UI界面管理，只能通过文件管理API管理，参考下一节接入流程「访问应用自有资源」。
- 应用拥有独立的应用云空间，包含文件夹、文件、文档、电子表格和多维表格等资源。
资源的定义如下：
| 资源 | 标识 | 资源定义 |
|---|---|---|
| 云空间 | root_token | 用于管理所有云文档资源的容器。 |
| 文件夹 | folder_token | 用于管理文件和其它文件夹的容器。 |
| 文件 | file_token | 各种类型的文件的统称，泛指云空间内所有的文件。 |
| 文档 | doc_token | 飞书在线文档。 |
| 电子表格 | spreadsheet_token | 飞书电子表格。 |
| 多维表格 | app_token | 飞书多维表格。 |
| 知识库 | space_id | 以树状目录管理文件的容器。 |
| 节点 | node_token | 知识库中云文档资源(obj_token)的挂载点。 |
| 评论 | comment_id | 飞书在线文档中的评论。 |
接入流程
| 序号 | 步骤 | 操作方法 |
|---|---|---|
| 1 | 创建应用 | 根据应用的使用场景选择创建企业自建应用 或创建应用商店应用 |
| 2 | 申请应用接口调用权限 | 根据需要调用的接口文档中描述的「权限要求」到开发者后台申请应用权限 |
| 3 | 访问应用自有资源 | 访问凭证使用 tenant_access_token 可以直接访问应用自有资源： 文件夹、文档、电子表格、多维表格 |
| 4 | 访问用户自有资源 | 访问凭证使用 user_access_token 可以直接访问用户自有资源： 文件夹、文档、电子表格、多维表格 |
| 5 | 使用tenant_access_token访问应用非自有资源 | 1. 访问其他用户的文档、电子表格、多维表格 需要取得文档所有者的授权 - 需要应用开启机器人能力 - 需要所有者打开对应的文档，在页面右上方「...」->「...更多」-> 「添加文档应用」入口添加 2. 访问 知识库需要获得知识库管理员的授权 - 需要应用开启机器人能力 - 需要知识库管理员打开知识库节点文档，在页面右上方「...」->「...更多」-> 「添加文档应用」入口添加 |
| 6 | 使用user_access_token访问用户非自有资源 | 1. 访问其他用户的文档、电子表格、多维表格 需要取得文档所有者的授权 - 需要所有者打开对应的文档，在页面右上方「分享」入口添加 2. 访问其他用户文件夹需要取得文件夹所有者的授权 - 需要所有者在我的空间找到目标文件夹，右键菜单中「分享」入口添加 3. 访问知识库需要获得知识库管理员的授权 - 需要知识库管理员打开知识库节点文档，在页面右上方「分享」入口添加 |
| 7 | 接口测试 | 你可以在 API 调试台 中快速调试这些 API ，使用方法参见API 调试台使用指南 |
| 8 | 事件订阅 | 需要到开发者后台配置事件回调地址,确保回调地址公网可访问。可参考事件监听示例、事件订阅概述 |
| 9 | 日志检索 | 当调用接口返回失败时，从返回的header部分获取 X-Tt-Logid: 20220501181xxx8035096193288FA。 再到应用管理后台，用服务端日志检索 分析问题。 |
场景教学
| 文档和知识库 | 电子表格和多维表格 |
|---|---|
基于云文档的周报管理 - 本示例介绍如何使用开放平台云文档能力进行团队周报管理。通过周报模版文档每周定时创建出新一周周报，并给团队成员授权文档编辑权限，自动将新周报文档归档到知识库指定节点，然后通过群机器人发送群消息通知所有人更新本周周报内容。  | 基于电子表格销售额统计 - 本示例介绍如何使用飞书电子表格的开放能力实现将外部销售额数据同步到电子表格中并进行总额统计的功能演示。通过接口创建出新的电子表格，然后写入外部数据、添加SUM统计公式并设置样式，最后给指定用户设置文档权限。  |
知识库周报文档待办事项每日提醒 - 本示例介绍如何使用开放平台云文档能力通过知识库接口查找到最近一期周报文档，用文档内容获取接口读取出周报中的待办事项，提取出待办事项的内容、负责人、截止时间并封装为提醒消息，发送消息到团队群进行待办事项的每日提醒。  | 基于多维表格的敏捷项目周期管理 - 本示例介绍如何使用多维表格进行敏捷项目管理，通过日历开放能力将项目版本迭代周期创建为公开日历，供全团队订阅。  |
文档数据迁移后替换文档中链接 - 本示例介绍如何使用开放平台云文档能力，在数据迁移场景将本地文件导入到飞书云文档，提取飞书文档中过期的链接，并修正为导入后的新链接地址。  |
常见问题
云文档
6. 云文档资源相关 token（id） 和 type 说明？
8. 如何使用应用身份（tenant_access_token）访问云文档资源？
9. 如何使用用户身份（user_access_token）访问云文档资源？
云空间
3. 如何让应用（tenant_access_token）访问个人云空间中的文件夹？
4. 如何获取文件夹、文件以及各种类型的在线文档token信息？
权限
1. 如何获取应用访问凭证 tenant_access_token？
2. 如何获取用户身份访问凭证 user_access_token？
3. 如何将应用（tenant_access_token）创建的文档分享给个人访问？
4. 如何将个人创建的文档分享给应用（tenant_access_token）访问？
5. 如何将个人创建的文件夹分享给应用（tenant_access_token）访问？
知识库
帮助与反馈
- 如果你在阅读开放文档的过程中发现文档描述有任何问题，请使用划词反馈（选中错误的信息，会浮出「点击纠错」的按钮），请在补充描述中指正我们的错误，我们会第一时间进行修正。
- 如果你在使用开放平台的时候遇到任何问题，请先阅读相关模块的「常见问题」文档。如果还不能解决的问题，可以点击网页右下角「技术支持」按钮，我们会有专业的技术专家提供咨询服务。