飞书文档编辑技能

本技能提供使用飞书开放平台 API 创建与编辑飞书文档的完整操作指南。

前置条件

1. 应用创建与配置

创建企业自建应用：登录飞书开放平台，创建应用并添加“机器人（Bot）”能力。

申请 API 权限：在“权限管理”中，申请以下权限：

• 文档编辑权限：docx:document:write_only
• 文档查看权限：docx:document:readonly

发布应用：提交版本并发布，确保应用覆盖范围包含目标用户或部门。

2. 获取访问令牌（Access Token）

调用自建应用的获取 tenant_access_token 接口：

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

响应示例：

{
  "code": 0,
  "tenant_access_token": "t-xxx",
  "expire": 7200
}

核心操作

提取文档 ID

从文档 URL 中提取 document_id：

示例 URL：https://bigdatacenter.feishu.cn/docx/HpK2dtGu9omhMAxV12zcB6i7ngd

document_id = HpK2dtGu9omhMAxV12zcB6i7ngd

授予应用文档权限

手动添加协作者：

• 在飞书客户端中打开文档 → 点击右上角“...” → “更多” → “添加文档应用”
• 搜索并添加您的应用，并授予“可编辑”权限。

写入文本内容

接口：创建 Block（create_block）

• 路径参数：document_id = 文档 ID；block_id = 文档 ID（根节点即为文档本身）

• 请求头（Request Headers）：

  Authorization: Bearer {tenant_access_token}
  Content-Type: application/json
  

• 请求体示例（写入文本“hello”）：

  {
    "index": -1,
    "children": [
      {
        "block_type": 2,
        "text": {
          "elements": [
            {
              "text_run": {
                "content": "hello"
              }
            }
          ]
        }
      }
    ]
  }
  

读取文档内容

接口：获取文档纯文本（Get Document Plain Text）

curl -X GET "https://open.feishu.cn/open-apis/docx/v1/documents/{document_id}/plaintext" 
  -H "Authorization: Bearer {tenant_access_token}"

响应示例：

{
  "code": 0,
  "data": {
    "content": "Document text content here"
  }
}

常见问题

1. 权限错误（403 Forbidden）

• 诊断：应用未被添加为文档协作者，或 tenant_access_token 已失效。
• 解决方案：重新将应用添加为协作者，或重新获取 tenant_access_token。

2. 缺少访问令牌（错误码 99991661）

• 诊断：请求头中未携带 Authorization: Bearer {token} 字段。
• 解决方案：确保已在请求头中正确传入有效的 tenant_access_token。

3. 文档未找到（404 Not Found）

• 诊断：document_id 错误，或该文档已被删除。
• 解决方案：重新从文档 URL 中提取正确的 document_id。

参考文档

• Create Block 接口文档
• Get Document Plain Text 接口文档
• 权限配置指南

通过以上步骤，您即可通过 API 实现对飞书文档的编辑操作，支持对文本、表格、图片等多种内容类型的增、删、改、查操作。