服务端 API/云文档/文档/文档概述 # 文档概述 本文档介绍Lark开放平台云文档中的文档能力相关的基本概念、使用限制、接入流程、方法列表等。 本文档是针对新版文档能力的说明。要了解新旧版本文档能力的区别，参考[新旧版本说明](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/docs/upgraded-docs-access-guide/upgraded-docs-openapi-access-guide)。 ## 基础概念 文档 OpenAPI 中，两个基础概念为文档和块。 ### 文档 文档是用户在云文档中创建的一篇在线文档。每篇文档都有唯一的 `document_id` 作为标识。要获取文档的 `document_id`，参考以下步骤。 - 若文档资源存储在云盘中，其云文档类型为文档（docx）。在该情况下，你可通过以下两种方式获取： - 通过 URL 地址获取：直接在浏览器中打开文档，在地址栏中获取文档的 `document_id`。 ![image.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/bcfa6f082aa2a75ac39ffcd40b5ee4fb_O9yA1DlMDb.png?height=549&lazyload=true&width=2145) - 通过开放平台接口获取 1. 通过[获取我的空间（root folder）元数据](https://open.larksuite.com/document/ukTMukTMukTM/ugTNzUjL4UzM14CO1MTN/get-root-folder-meta)获取根文件夹 token。 2. 通过[获取文件夹下文件清单](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/file/list) 获取其中文档资源的 `document_id`。 - 若文档挂载在知识库中，你需通过知识库相关接口[获取知识空间节点信息](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/wiki-v2/space/get_node)获取该节点下挂载的云资源的 `obj_token` 和 `obj_type`。在该情况下，`obj_type` 为 `docx` 时，其对应的 `obj_token` 即为文档的 `document_id`。 文档的基础元数据结构如下： ```JSON "document": { "document_id": string, // 文档的唯一标识 "revision_id": int, // 文档版本的标识，可指定要查询或更新的文档版本 "title": string, // 文档标题 "display_setting": { // 文档展示设置 "show_authors": boolean, // 文档信息中是否展示文档作者 "show_comment_count": boolean, // 文档信息中是否展示评论总数 "show_create_time": boolean, // 文档信息中是否展示文档创建时间 "show_like_count": boolean, // 文档信息中是否展示点赞总数 "show_pv": boolean, // 文档信息中是否展示文档访问次数 "show_uv": boolean // 文档信息中是否展示文档访问人数 }, "cover": { // 文档封面 "token": string, // 封面图片的 token "offset_ratio_x": float, // 视图在水平方向的偏移比例 "offset_ratio_y": float // 视图在垂直方向的偏移比例 } } ``` ### 块 在一篇文档中，有多个不同类型的段落，这些段落被定义为块（Block）。块是文档中的最小构建单元，是内容的结构化组成元素，有着明确的含义。块有多种形态，可以是一段文字、一张电子表格、一张图片或一个多维表格等。每个块都有唯一的 `block_id` 作为标识。 每一篇文档都有一个根块，即页面块（Page block）。页面块的 `block_id` 与其所在文档的 `document_id` 相同。在数据结构中，文档的页面块与其它块形成父子关系，页面块为父块，称为 Parent，其它块为子块，称为 Children。其它块之间也可形成父子关系。 ![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/3afeecbc5410c1d3a9e89a2a86d89d65_VIM5eQY6T8.png?height=1721&lazyload=true&width=3059) ![image.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/744512f0ae06add904ef1b5625ea117b_RRPMtAFaWm.png?height=548&lazyload=true&width=1349) **块的类别** 从功能角度，块可以分为以下几种类别。了解块的具体类型，参考 [BlockType 的枚举值](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/data-structure/block#e8ce4e8e)。 **功能类别** | 典型块 | 示例 ---|---|--- 文本类 | 页面（Page）、文本（Text）、标题（Heading）、无序列表（Bullet）、有序列表（Ordered）、代码（Code）、待办事项（Todo）块等。 |   数据类 | 多维表格（Bitable）、电子表格（Sheet）、思维笔记（Mindnote）块。 |   视觉类 | 分割线（Divider）块。 |   媒体类 | 图片（Image）、文件（File）、内嵌（Iframe）块等。 |   协作类 | 会话卡片（ChatCard）块。 |   容器类 | 表格单元格（TableCell）、分栏列（GridColumn）、高亮（Callout）、视图（View）、引用容器（QuoteContainer）块等。 |   垂直类 | 流程图 & UML 图（Diagram）块。 |   辅助类 | 表格（Table）、分栏（Grid）块等。 |   第三方块 | 开放平台小组件（ISV）块。 |   未定义块 | / |   **块的父子关系规则** 块与块之间可形成父子关系。在调用[创建块](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block-children/create)接口时，你需先了解以下规则，再指定父块和子块。 **父块规则** 只有具有容纳能力的块才可以作为父块，对其添加子块。这些块包括： - 文本功能类的块：页面（Page）、文本（Text）、标题（Heading）、无序列表（Bullet）、有序列表（Ordered）、任务（Task）、待办事项（Todo）块。 - 容器功能类的块：表格单元格（TableCell）、分栏列（GridColumn）、高亮（Callout）、引用容器（QuoteContainer）块。 **子块规则** 以下块不可作为子块被添加至父块内： | **块** | **说明** | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 页面（Page） | 一篇文档有且只有一个页面块，在文档创建时自动生成。 | | 分栏列（GridColumn） | 只可通过[更新块](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block/patch)接口中的 `InsertGridColumnRequest` 操作添加，不可直接作为子块添加。 | | 思维笔记（Mindnote） | 不支持。 | | 单元格（TableCell） | 只可通过[更新块](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block/patch)接口中的 `InsertTableRowRequest` 或 `InsertTableColumnRequest` 操作添加，不可直接作为子块添加。 | | 视图（View） | 在添加文件（File）块时，会自动生成默认的视图块。 | | 未定义（Undefined） | 无效操作。 | | 流程图 & UML（Diagram） | 不支持。 | **父子关系限制** 其它的父子关系限制如下表所示： 块 | 限制 ---|--- 单元格（Table Cell） | 不允许为单元格（TableCell）块添加如下块作为子块：
• 表格（Table）
• 电子表格（Sheet）
• 多维表格（Bitable）
• OKR 分栏列（Grid Column） | 不允许为分栏列（GridColumn）添加如下块作为子块：
• 分栏（Grid）
• 多维表格（Bitable）
• OKR 高亮块（Callout） | 只允许为高亮块（Callout）添加如下块作为子块：
• 文本（Text）
• 标题（HeadingN）
• 有序列表（Ordered）
• 无序列表（Bullet）
• 任务（Task）
• 待办事项（Todo）
• 引用（Quote）
• 引用容器（QuoteContainer） ## 使用限制 你可使用开放平台提供的一系列文档开放接口对不同种类的块进行操作，包括创建、读取、以及编辑块的内容。针对不同块，文档开放接口的支持情况不同，详情参考下表。 下表中，“/” 代表对应的操作无需支持或已在其他开放能力的场景中覆盖，具体情况如下： - 能力无需支持。例如，分割线（Divider）块不含内容，因此开放平台无需提供读取和编辑其内容的能力； - 能力已间接支持。例如，针对单元格（TableCell）块，你会在编辑表格（Table）块的内容时直接创建或删除单元格块，因此开放平台无需为单元格（TableCell）块单独提供创建能力； - 能力已在其他开放能力的场景中覆盖。针对多维表格（Bitable）块，你可在创建空的多维表格块后，根据返回的 Token 值使用多维表格的开放能力调用对应的读取和编辑接口。了解多维表格的开放能力，参考[多维表格方法列表](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/bitable-overview)。 | **块** | **创建块** | **读取内容** | **编辑内容** | |---|---|---|---| | 高亮块（Callout） | 支持 | 支持 | 支持 | | 表格（Table） | 支持 | 支持 | 支持 | | 文本（Text） | 支持 | 支持 | 支持 | | 分割线（Divider） | 支持 | / | / | | 分栏（Grid） | 支持 | 支持 | 支持 | | 内嵌块（Iframe） | 支持 | 支持 | 不支持 | | 会话卡片（ChatCard） | 支持 | / | / | | 图片（Image） | 支持 | / | / | | 文件（File） | 支持 | / | / | | 单元格（TableCell） | / | 支持 | 支持 | | 分栏列（GridColumn） | / | 支持 | 支持 | | 视图（View） | / | 支持 | 不支持 | | 三方块（ISV） | 支持 | / | / | | 多维表格（Bitable） | 支持 | / | / | | 电子表格（Sheet） | 支持 | / | / | | 思维笔记（Mindnote） | 不支持 | / | / | | UML 图（Diagram） | 不支持 | 不支持 | 不支持 | | 引用容器（QuoteContainer） | 支持 | 支持 | 支持 | | 任务（Task） | 不支持 | / | / | | OKR | 支持 | 支持 | / | | OKR 目标（OkrObjective） | / | 支持 | / | | OKR 关键结果（OkrKeyResult） | / | 支持 | / | | OKR 进展（OkrProgress） | / | 支持 | / | | 文档小组件（AddOns） | 支持 | 支持 | / | | Jira 问题（JiraIssue） | / | 支持 | / | | Wiki 子目录（WikiCatalog） | 支持 | / | / | | 画板（Board） | 支持 | 支持 | / | | 未定义块（Undefined） | / | / | / | ## 接入流程 接入文档 OpenAPI 的流程如下图所示。了解更多，参考[云文档-概述](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/docs-overview) 的 **接入流程** 一节。 ![image.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/42967c08b5e6619841ebd673f8e66f17_TRmROny4AI.png?height=546&lazyload=true&width=6382) ## 方法列表 以下为文档和块的 OpenAPI 列表。 ### 文档 方法 (API) | 权限要求（满足任一） | 访问凭证 | 商店 | 自建 ---|---|---|---|--- `GET` 获取文档基本信息
[/open-apis/docx/v1/documents/:document_id](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document/get) | 创建及编辑新版文档(docx:document)
查看新版文档(docx:document:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓** `GET` 获取文档纯文本内容
[/open-apis/docx/v1/documents/:document_id/raw_content](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document/raw_content) | 创建及编辑新版文档(docx:document)
查看新版文档(docx:document:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓** `GET` 获取文档所有块
[/open-apis/docx/v1/documents/:document_id/blocks](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block/list) | 创建及编辑新版文档(docx:document)
查看新版文档(docx:document:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓** `POST` 创建文档
[/open-apis/docx/v1/documents](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document/create) | 创建及编辑新版文档(docx:document) | `tenant_access_token`
`user_access_token` | **✓** | **✓** ### 块 方法 (API) | 权限要求（满足任一） | 访问凭证 | 商店 | 自建 ---|---|---|---|--- `GET` 获取块
[/open-apis/docx/v1/documents/:document_id/blocks/:block_id](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block/get) | 创建及编辑新版文档(docx:document)
查看新版文档(docx:document:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓** `POST` 创建块
[/open-apis/docx/v1/documents/:document_id/blocks/:block_id/children](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block-children/create) | 创建及编辑新版文档(docx:document) | `tenant_access_token`
`user_access_token` | **✓** | **✓** `POST` 创建嵌套块
[/open-apis/docx/v1/documents/:document_id/blocks/:block_id/descendant](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block-descendant/create) | 创建及编辑新版文档(docx:document) | `tenant_access_token`
`user_access_token` | **✓** | **✓** `PATCH` 更新块
[/open-apis/docx/v1/documents/:document_id/blocks/:block_id](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block/patch) | 创建及编辑新版文档(docx:document) | `tenant_access_token`
`user_access_token` | **✓** | **✓** `PATCH` 批量更新块
[/open-apis/docx/v1/documents/:document_id/blocks/batch_update](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block/batch_update) | 创建及编辑新版文档(docx:document) | `tenant_access_token`
`user_access_token` | **✓** | **✓** `DELETE` 删除块
[/open-apis/docx/v1/documents/:document_id/blocks/:block_id/children/batch_delete](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block-children/batch_delete) | 创建及编辑新版文档(docx:document) | `tenant_access_token`
`user_access_token` | **✓** | **✓** `GET` 获取所有子块
[/open-apis/docx/v1/documents/:document_id/blocks/:block_id/children](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block-children/get) | 创建及编辑新版文档(docx:document)
查看新版文档(docx:document:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓**