# 接入指南
在接入新版文档 OpenAPI 前，请先阅读[新版文档 OpenAPI 接入指引](https://feishu.feishu.cn/docx/ICI7dp1Uioh4EvxXn0HcxUapn0c)。
## 形态
新版文档编辑器由文档级演进到段落级，「段落」通常也称之为「**块**」，在新版文档的数据结构中将其定义为 **Block**。Block 作为内容结构化的组成元素，是有着明确含义的信息单元。多个 Block 间可以形成树状关系的层级内容，树的根节点本身也是一个特殊类型的 Block，其被称为 Page Block。对于形成了父子关系的 Block，儿子 Block 被称之为 Children。

## 块列表
| **类型**   | **描述**         | 
| --------- | --------------- |
|page | 文档 Block，是整个文档树的根节点 |
|text | 文本 Block|
|heading**N** | 标题 Block，heading**N**，**N** 取值范围1~9|
|bullet | 无序列表 Block|
|ordered | 有序列表 Block|
|code | 代码块 Block|
|quote | 引用 Block|
|todo | 任务 Block|
|bitable | 多维表格 Block |
|callout | 高亮块 Block|
|chat_card | 会话卡片 Block|
|diagram | UML 图 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|
|okr|OKR Block|
|okr_objective|OKR Objective Block|
|okr_key_result|OKR Key Result Block|
|okr_progress|OKR 进展 Block|
|add_ons|文档小组件 Block|
|jira_issue|Jira 问题 Block|
|wiki_catalog|Wiki 子目录 Block|
|undefined|未支持 Block|
> Block 类型枚举值定义：[点击查看 BlockType](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/data-structure/block#e8ce4e8e)。
## 限制

### 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](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/data-structure/block#e8ce4e8e)。
## 查询文档基本信息

查询文档的**最新版本号**、**标题**，该接口只返回文档的基本信息，并不返回文档内容。
```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' # 调用前请替换为真实的访问令牌
```  

## 创建块
为指定块创建一批子块，并插入到特定位置。此接口返回值是被新创建子块的富文本内容。<br>
> 如不指定版本，默认使用最新版本。
```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"
                        }
                    }
                ]
            }
        }
    ]
}'
```

## 删除块
指定需要操作的块，删除其指定范围的子块，并返回应用操作后的文档版本。<br>
> 我们可以将新版文档看成一颗 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' # 调用前请替换为真实的访问令牌
```