Skip to content

接入指南 ​

Note 在接入新版文档 OpenAPI 前,请先阅读新版文档 OpenAPI 接入指引。

形态 ​

新版文档编辑器由文档级演进到段落级,「段落」通常也称之为「块」,在新版文档的数据结构中将其定义为 Block。Block 作为内容结构化的组成元素,是有着明确含义的信息单元。多个 Block 间可以形成树状关系的层级内容,树的根节点本身也是一个特殊类型的 Block,其被称为 Page Block。对于形成了父子关系的 Block,儿子 Block 被称之为 Children。

块列表 ​

类型描述
page文档 Block,是整个文档树的根节点
text文本 Block
headingN标题 Block,headingN,N 取值范围1~9
bullet无序列表 Block
ordered有序列表 Block
code代码块 Block
quote引用 Block
todo任务 Block
bitable多维表格 Block
callout高亮块 Block
chat_card会话卡片 Block
diagramUML 图 Block
divider分割线 Block
file文件 Block
grid分栏 Block
grid_column分栏列 Block
iframe内嵌 Block
image图片 Block
isv三方 Block
mindnote思维笔记 Block
sheet电子表格 Block
table表格 Block
table_cell单元格 Block
view视图 Block
quote_container引用容器 Block
task任务 Block
okrOKR Block
okr_objectiveOKR Objective Block
okr_key_resultOKR Key Result Block
okr_progressOKR 进展 Block
add_ons文档小组件 Block
jira_issueJira 问题 Block
wiki_catalogWiki 子目录 Block
undefined未支持 Block

Block 类型枚举值定义:点击查看 BlockType。

限制 ​

QPS 限制 ​

每个接口都有调用频率限制,具体可参考对应接口文档的频控说明。

接口错误 ​

当请求不符合某些特定条件时会报错,具体可参考对应接口文档「错误码」部分。

能力边界 ​

当前新版文档 OpenAPI 操作 Block 能力边界:

Block创建读取内容编辑内容
Callout支持支持支持
Table支持支持支持
Text支持支持支持
Divider支持--
Grid支持支持支持
Iframe支持支持不支持
ChatCard支持--
Image支持--
File支持--
TableCell-支持支持
GridColumn-支持支持
View-支持不支持
ISV支持--
Bitable支持--
Sheet支持--
Mindnote不支持--
Diagram不支持不支持不支持
QuoteContainer支持支持支持
Task不支持--
OKR支持支持-
OKR Objective-支持-
OKR Key Result-支持-
OKR Progress-支持-
Add Ons支持支持-
Jira 问题-支持-
Wiki 子目录支持支持-
Undefined---
  1. ==-== 表示不在支持范围内,比如:
    • 不支持直接创建 TableCell,因为在对 Table 添加行或列时,会自动创建 TableCell;
    • 不支持直接读取 Bitable,可根据返回的 Bitable ==Token== 调用对应的 Bitable 开放接口。
  2. Block 类型枚举值定义:点击查看 BlockType。

查询文档基本信息 ​

查询文档的最新版本号、标题,该接口只返回文档的基本信息,并不返回文档内容。

bash
curl --location --request GET 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌

查询文档纯文本内容 ​

获取文档的纯文本内容,不包含富文本格式信息。

bash
curl --location --request GET 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/raw_content' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌

获取文档所有块 ​

对指定文档所有的块进行深度遍历并分页返回。

BASH
curl --location --request GET 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/blocks?page_size=100&document_revision_id=-1' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌

创建文档 ​

支持通过 folder_token 参数指定云空间目录。

bash
curl --location --request POST 'https://open.feishu.cn/open-apis/docx/v1/documents?folder_token=fldcnbCHL8OAtkcYHnPzZi1yupN' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌

获取块 ​

查询指定块的富文本内容。

此接口不会返回子块信息, 如需获取请结合使用 「获取所有子块」。

bash
curl --location --request GET 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/blocks/doxcnC4cO4qUui6isgnpofh5edc?document_revision_id=-1' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌

创建块 ​

为指定块创建一批子块,并插入到特定位置。此接口返回值是被新创建子块的富文本内容。

如不指定版本,默认使用最新版本。

bash
curl --location --request POST 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/blocks/doxcnAJ9VRRJqVMYZ1MyKnavXWe/children?document_revision_id=120' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌 \
--header 'Content-Type: application/json' \
--data-raw '{
    "index": 0,
    "children": [
        {
            "block_type": 2,
            "text": {
                "elements": [
                    {
                        "text_run": {
                            "content": "多人实时协同,插入一切元素。不仅是在线文档,更是",
                            "text_element_style": {
                                "background_color": 14,
                                "text_color": 5
                            }
                        }
                    },
                    {
                        "text_run": {
                            "content": "强大的创作和互动工具",
                            "text_element_style": {
                                "background_color": 14,
                                "bold": true,
                                "text_color": 5
                            }
                        }
                    }
                ],
                "style": {}
            }
        }
    ]
}'

更新块 ​

更新指定块,并返回其更新后的富文本内容。

如不指定版本,默认使用最新版本

bash
curl --location --request PATCH 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/blocks/doxcnC4cO4qUui6isgnpofh5edc' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌 \
--header 'Content-Type: application/json' \
--data-raw '{
    "update_text_elements":{
        "elements":[
            {
                "text_run": {
                        "content": "云空间",
                        "text_element_style": {
                            "link": {
                                "url": "https%3A%2F%2Fbytedance.feishu.cn%2Fdrive%2Fhome%2F"
                            }
                        }
                    }
            }
        ]
    }
}'

批量更新块 ​

批量更新指定块,并返回其更新后的富文本内容。

如不指定版本,默认使用最新版本

bash
curl --location --request PATCH 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/blocks/batch_update' \
--header 'Authorization: Bearer u-xxx'  # 调用前请替换为真实的访问令牌  
--header 'Content-Type: application/json' \
--data-raw '{
    "requests": [
        {
            "block_id": "doxcnk0i44OMOaouw8AdXuXrp6b",
            "merge_table_cells": {
                "column_end_index": 2,
                "column_start_index": 0,
                "row_end_index": 1,
                "row_start_index": 0
            }
        },
        {
            "block_id": "doxcn0K8iGSMW4Mqgs9qlyTP50d",
            "update_text_elements": {
                "elements": [
                    {
                        "text_run": {
                            "content": "Hello",
                            "text_element_style": {
                                "background_color": 2,
                                "bold": true,
                                "italic": true,
                                "strikethrough": true,
                                "text_color": 2,
                                "underline": true                            }
                        }
                    },
                    {
                        "text_run": {
                            "content": "World ",
                            "text_element_style": {
                                "italic": true
                            }
                        }
                    },
                    {
                        "mention_doc": {
                            "obj_type": 22,
                            "token": "doxcnAJ9VRRJqVMYZ1MyKnayXWe",
                            "url": "https://test.feishu.cn/docx/doxcnAJ9VRRJqVMYZ1MyKnayXWe"
                        }
                    }
                ]
            }
        }
    ]
}'

删除块 ​

指定需要操作的块,删除其指定范围的子块,并返回应用操作后的文档版本。

我们可以将新版文档看成一颗 Block 树,删除块可看成是删除其父亲块的孩子,即先明确要删除的块是其父亲块的第几个孩子,然后再调用本接口进行删除。

bash
curl --location --request DELETE 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/blocks/doxcnAJ9VRRJqVMYZ1MyKnavXWe/children/batch_delete?document_revision_id=-1' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌 \
--header 'Content-Type: application/json' \
--data-raw '{
   "start_index": 0,
   "end_index": 1
}'

获取所有子块 ​

指定需要操作的块, 分页遍历其子块的富文本内容。

此接口仅返回子块的富文本内容。

bash
curl --location --request GET 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/blocks/doxcnAJ9VRRJqVMYZ1MyKnavXWe/children?document_revision_id=-1&page_size=10' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌

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