飞书文档API开发指南：Feishu-MCP项目深度解析

前言

飞书作为一款优秀的企业协作平台，其文档功能提供了丰富的API接口，允许开发者进行深度集成和二次开发。本文将全面解析飞书文档API的使用方法，帮助开发者快速掌握文档创建、内容管理、块操作等核心功能。

一、认证与基础准备

1. 获取访问令牌

在使用飞书文档API前，首先需要获取访问令牌。飞书提供了两种类型的令牌：

• app_access_token：应用级别的访问令牌
• tenant_access_token：租户级别的访问令牌

curl -i -X POST 'https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal' \
-H 'Content-Type: application/json' \
-d '{
    "app_id": "<your_app_id>",
    "app_secret": "<your_app_secret>"
}'

成功返回的响应包含两种令牌及其有效期：

{
  "app_access_token": "<access_token>",
  "code": 0,
  "expire": 6055,
  "msg": "ok",
  "tenant_access_token": "<tenant_access_token>"
}

二、文档基础操作

1. 创建新文档

创建文档时需要指定父文件夹token和文档标题：

curl -i -X POST 'https://open.feishu.cn/open-apis/docx/v1/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '{
    "folder_token": "<folder_token>",
    "title": "一篇新的文档"
}'

成功创建后返回文档ID和版本信息：

{
  "code": 0,
  "data": {
    "document": {
      "document_id": "<document_id>",
      "revision_id": 1,
      "title": "一篇新的文档"
    }
  },
  "msg": "success"
}

2. 获取文档信息

获取文档基本信息包括标题、显示设置等元数据：

curl -i -X GET 'https://open.feishu.cn/open-apis/docx/v1/documents/<document_id>' \
-H 'Authorization: Bearer <access_token>'

返回结果包含详细的显示设置：

{
  "display_setting": {
    "show_authors": true,
    "show_comment_count": false,
    "show_create_time": false,
    "show_like_count": false,
    "show_pv": false,
    "show_related_matters": false,
    "show_uv": false
  }
}

三、文档内容操作

1. 获取纯文本内容

获取文档的纯文本内容，适合需要提取文字信息的场景：

curl -i -X GET 'https://open.feishu.cn/open-apis/docx/v1/documents/<document_id>/raw_content?lang=0' \
-H 'Authorization: Bearer <access_token>'

2. 块(Block)操作

飞书文档采用块(Block)的概念组织内容，每个块可以是段落、标题、列表、代码块等。

获取文档块列表

curl -i -X GET 'https://open.feishu.cn/open-apis/docx/v1/documents/<document_id>/blocks?document_revision_id=-1&page_size=500' \
-H 'Authorization: Bearer <access_token>'

返回结果包含块的类型、内容和样式信息：

{
  "block_type": 1,  // 块类型代码
  "page": {
    "elements": [
      {
        "text_run": {
          "content": "示例文本",
          "text_element_style": {
            "bold": false,
            "italic": false
          }
        }
      }
    ]
  }
}

创建新块

在指定位置插入新块：

curl -i -X POST 'https://open.feishu.cn/open-apis/docx/v1/documents/<document_id>/blocks/<block_id>/children?document_revision_id=-1' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '{
    "children": [
        {
            "block_type": 2,
            "text": {
                "elements": [
                    {
                        "text_run": {
                            "content": "多人实时协同内容"
                        }
                    }
                ]
            }
        }
    ],
    "index": 0
}'

特殊块类型操作

代码块：可以指定编程语言类型

{
    "block_type": 14,
    "code": {
        "elements": [
            {
                "text_run": {
                    "content": "hello world"
                }
            }
        ],
        "style": {
            "language": 32,  // Kotlin
            "wrap": false
        }
    }
}

列表块：支持有序和无序列表

// 无序列表
{
    "block_type": 12,
    "bullet": {
        "elements": [
            {
                "text_run": {
                    "content": "无序列表项"
                }
            }
        ]
    }
}

// 有序列表
{
    "block_type": 13,
    "ordered": {
        "elements": [
            {
                "text_run": {
                    "content": "有序列表项"
                }
            }
        ]
    }
}

更新块内容

修改已有块的内容和样式：

curl -i -X PATCH 'https://open.feishu.cn/open-apis/docx/v1/documents/<document_id>/blocks/<block_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '{
    "update_text_elements": {
        "elements": [
            {
                "text_run": {
                    "content": "更新后的文本",
                    "text_element_style": {
                        "bold": true,
                        "italic": true
                    }
                }
            }
        ]
    }
}'

删除块

批量删除指定范围内的块：

curl -i -X DELETE 'https://open.feishu.cn/open-apis/docx/v1/documents/<document_id>/blocks/<block_id>/children/batch_delete' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '{
    "start_index": 0,
    "end_index": 1
}'

四、资源管理

1. 图片操作

插入图片需要两步操作：

1. 创建图片块占位符
2. 上传图片并关联到占位符

// 第一步：创建图片块
{
    "block_type": 27,
    "image": {}
}

// 第二步：上传图片
curl -X POST 'https://open.feishu.cn/open-apis/drive/v1/medias/upload_all' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: multipart/form-data' \
-F 'file=@image.png' \
-F 'file_name="test.png"' \
-F 'parent_type="docx_image"' \
-F 'parent_node="<image_block_id>"'

2. 获取图片资源

curl -i -X GET 'https://open.feishu.cn/open-apis/drive/v1/medias/<media_token>/download' \
-H 'Authorization: Bearer <access_token>'

五、文件系统操作

1. 获取根文件夹信息

curl -X GET 'https://open.feishu.cn/open-apis/drive/explorer/v2/root_folder/meta' \
-H 'Authorization: Bearer <access_token>'

2. 获取文件夹内容

curl -i -X GET 'https://open.feishu.cn/open-apis/drive/v1/files?folder_token=<folder_token>' \
-H 'Authorization: Bearer <access_token>'

3. 创建新文件夹

curl -i -X POST 'https://open.feishu.cn/open-apis/drive/v1/files/create_folder' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '{
    "folder_token": "<parent_folder_token>",
    "name": "新文件夹"
}'

六、Wiki文档处理

Wiki文档需要先转换为标准文档ID才能操作：

curl -i -X GET 'https://open.feishu.cn/open-apis/wiki/v2/spaces/get_node?obj_type=wiki&token=<wiki_token>' \
-H 'Authorization: Bearer <access_token>'

返回结果中包含对应的文档ID：

{
    "obj_token": "<document_id>",
    "obj_type": "docx"
}

总结

飞书文档API提供了完整的文档生命周期管理能力，从创建、内容编辑到资源管理，覆盖了各种协作场景的需求。通过本文的详细解析，开发者可以：

1. 快速实现文档自动化创建和管理
2. 精确控制文档内容和格式
3. 构建基于飞书文档的自动化工作流
4. 开发深度集成的企业协作应用

掌握这些API接口，将大大提升企业协作效率和自动化水平。