新版文档接入指南

本文目标读者

需要通过 OpenAPI 操作新版文档的开发者；

调用旧版文档 OpenAPI 返回 95053 错误码的开发者。

本文解决什么问题

协助开发者顺利地接入新版文档 OpenAPI。

什么是新版文档

了解什么是新版文档

如何区分新、旧版文档

a. 通过链接

新版文档：https://:domain/docx/:doc_token

旧版文档：https://:domain/docs/:doc_token

b. 通过文件类型

新版文档：文件类型为 docx

旧版文档：文件类型为 doc

在云文档不同接口的上下文中，对「文件类型」表述不一，其可能被称为 type、types、parent_type、docs_type、file_type 以及 obj_type 等。

是否需要接入新版文档 OpenAPI

首先，如果你的应用调用了云文档下的接口，那么请先根据以下接口说明进行自查。

a. 新旧文档不共用接口：

接口	说明
创建文档	新旧文档不共用该接口，新版文档提供了新接口。
获取文档富文本内容	新旧文档不共用该接口，新版文档提供了新接口。
编辑文档内容	新旧文档不共用该接口，新版文档提供了新接口。
获取文档纯文本内容	新旧文档不共用该接口，新版文档提供了新接口。
获取文档元信息	新旧文档不共用该接口，并且新版文档不再单独提供获取元数据接口。查询新文档元数据请使用：获取元数据。
获取文档中的电子表格的元数据	新旧文档不共用该接口，新版文档不再提供。如果你需要对新版文档使用该接口，请通过「技术支持」与我们联系。

b. 新旧文档共用接口：

接口	说明
复制文件	新旧文档共用该接口，通过「文件类型」进行区分。
移动文件	新旧文档共用该接口，通过「文件类型」进行区分。
删除文件	新旧文档共用该接口，通过「文件类型」进行区分。
增加权限	新旧文档共用该接口，通过「文件类型」进行区分。
更新协作者权限	新旧文档共用该接口，通过「文件类型」进行区分。
移除协作者权限	新旧文档共用该接口，通过「文件类型」进行区分。
判断协作者是否有某权限	新旧文档共用该接口，通过「文件类型」进行区分。
获取协作者列表	新旧文档共用该接口，通过「文件类型」进行区分。
转移拥有者	新旧文档共用该接口，通过「文件类型」进行区分。
获取文档公共设置	新旧文档共用该接口，通过「文件类型」进行区分。
更新文档公共设置	新旧文档共用该接口，通过「文件类型」进行区分。
获取文件统计信息	新旧文档共用该接口，通过「文件类型」进行区分。
创建事件订阅	新旧文档共用该接口，通过「文件类型」进行区分。
获取订阅状态	新旧文档共用该接口，通过「文件类型」进行区分。
更新订阅状态	新旧文档共用该接口，通过「文件类型」进行区分。
创建导入任务	新旧文档共用该接口，通过「文件类型」进行区分。
查询导入结果	新旧文档共用该接口，通过「文件类型」进行区分。
添加已有云文档至知识库	新旧文档共用该接口，通过「文件类型」进行区分。
获取评论列表	新旧文档共用该接口，通过「文件类型」进行区分。
获取评论	新旧文档共用该接口，通过「文件类型」进行区分。
添加评论	新旧文档共用该接口，通过「文件类型」进行区分。
更新回复	新旧文档共用该接口，通过「文件类型」进行区分。
删除回复	新旧文档共用该接口，通过「文件类型」进行区分。
解决/恢复评论	新旧文档共用该接口，通过「文件类型」进行区分。
搜索文档	新旧文档共用该接口，请求体参数 `docs_types` 均为 `doc`。

其次，请根据实际业务场景判断是否需要接入新版文档 OpenAPI，以下提供几个建议供参考：

及时接入。用户通过 Web 界面或其它自动化途径创建了一篇新版文档，开放应用需要通过 OpenAPI 对文档进行编辑，由于还没接入新版文档的 OpenAPI，导致无法完成操作。这类由于能力缺失导致应用功能受损的场景需要及时接入。

排期接入。应用内使用了旧版文档带内容创建文档接口新建文档，并且使用了旧版文档编辑文档接口等，其中所有操作均是通过旧版文档 OpenAPI 闭环实现，那么这类场景可根据实际需要排期接入即可。但长期来看，随着新版文档渗透率的不断提升，并且新文档未来还会有更多新特性，所以建议尽早排期接入，从而使自己的应用拥有操作新版文档的能力。

无需处理。对于新旧文档共用接口，新版文档跟旧版文档是同个接口，只需通过接口参数中的「文件类型」来区分新旧文档。而对于新版文档，只要确认接口传入的「文件类型」正确，那么就无需特别处理。

新版文档 OpenAPI 功能范围

核心概念

新版文档从旧版文档的「文档级」进化到「段落级」，「段落」通常也称之为「块」，新版文档将其定义为 Block。 Block 作为内容结构化组成元素，是有着明确含义的信息单元。

Block 有多种形式，可以是一段文字、一张电子表格、一张图片或一个多维表格等，但大体上可分为几大类，比如文本类 Block、容器类 Block 等。

多个 Block 间可以形成树状关系的层级内容，从结构来看新版文档就是一棵 Block 树，在 OpenAPI 中将这棵树称为 Document，树的根节点也是一个 Block，其被称为 Page Block。对于形成了父子关系的 Block，在新版文档中将父子关系中的孩子称之为 Children。

至此，我们引出新版 OpenAPI 中最核心的两个概念及其能力：

文档（Document）

获取文档基本信息接口，获取新版文档最新版本号、标题等；

获取文档纯文本内容接口，获取新版文档的纯文本内容；

获取文档所有块接口，遍历新版文档所有块的富文本内容；

创建文档接口，创建新版文档。

块（Block）

获取块接口，查询指定块的富文本内容；

创建块接口，为指定块创建一批子块；

更新块接口，更新指定块；

批量更新块接口，批量更新指定块；

删除块接口，删除指定块；

获取所有子块接口，遍历指定块的所有子块富文本内容。

数据模型

新版文档 OpenAPI 数据结构

新版文档接入指南

本文目标读者#

本文解决什么问题#

什么是新版文档#

如何区分新、旧版文档#

是否需要接入新版文档 OpenAPI#

新版文档 OpenAPI 功能范围#

核心概念#

数据模型#