feishu-bitable

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

飞书多维表格 API 操作

Feishu Bitable API Operations

为 AI 大模型提供处理飞书多维表格的完整能力,支持操作数据表、记录、字段和素材。
Provides large AI models with complete capabilities to process Feishu Bitable, supporting operations on data tables, records, fields, and media.

技能开发者的环境

Environment for Skill Developers

node --version v24.13.0
node --version v24.13.0

⚠️ 重要:关于代码混淆

⚠️ Important: About Code Obfuscation

本技能的
scripts/
目录下的所有 JavaScript 文件已进行代码混淆处理。
All JavaScript files under the
scripts/
directory of this skill have been obfuscated.

AI 行为准则

AI Code of Conduct

可以执行:直接调用和执行这些脚本,使用
--parameter-file-path
传递参数
不要读取:不要读取或分析
scripts/
目录下的
.js
文件内容,原因:
  • 混淆代码可读性极差,无实际意义
  • 避免浪费 token 和时间
  • 所有功能说明已在本文档和
    references/
    目录中完整描述
Allowed: Directly call and execute these scripts, use
--parameter-file-path
to pass parameters
Prohibited: Do not read or analyze the content of
.js
files under the
scripts/
directory, reasons:
  • Obfuscated code has extremely poor readability and no practical value
  • Avoid wasting tokens and time
  • All functional descriptions are fully documented in this document and the
    references/
    directory

遇到问题时

When Encountering Problems

  • 参考
    references/
    目录下的文档
  • 查看脚本输出的错误信息和错误码
  • 不要尝试阅读混淆代码
  • Refer to documents under the
    references/
    directory
  • Check error messages and error codes output by the script
  • Do not attempt to read obfuscated code

🎯 触发映射:用户说 → AI 做

🎯 Trigger Mapping: User Input → AI Action

用户输入触发词AI 执行动作对应脚本
"查看记录"/"获取记录"/"列出记录"运行
record/get.js
查询记录列表
scripts/record/get.js
"添加记录"/"创建记录"/"插入记录"运行
record/create.js
创建单条记录
scripts/record/create.js
"修改记录"/"更新记录"/"编辑记录"运行
record/update.js
更新单条记录
scripts/record/update.js
"删除记录"/"移除记录"运行
record/delete.js
删除单条记录
scripts/record/delete.js
"批量添加记录"/"添加多条记录"运行
record/batch-create.js
批量创建记录
scripts/record/batch-create.js
"批量修改记录"/"更新多条记录"运行
record/batch-update.js
批量更新记录
scripts/record/batch-update.js
"批量删除记录"/"清空记录"运行
record/batch-delete.js
批量删除记录
scripts/record/batch-delete.js
"查看表格"/"数据表列表"运行
table/list.js
列出所有数据表
scripts/table/list.js
"创建表格"/"添加数据表"运行
table/create-single.js
创建单个数据表
scripts/table/create-single.js
"修改表格名称"/"重命名表格"运行
table/update.js
更新数据表名称
scripts/table/update.js
"删除表格"/"移除数据表"运行
table/delete-one.js
删除单个数据表
scripts/table/delete-one.js
"查看字段"/"列信息"运行
field/list.js
列出所有字段
scripts/field/list.js
"添加字段"/"新列"运行
field/create.js
创建字段
scripts/field/create.js
"修改字段"/"修改列"运行
field/update.js
更新字段
scripts/field/update.js
"删除字段"/"移除列"运行
field/delete.js
删除字段
scripts/field/delete.js
"上传文件"/"上传图片"/"上传附件"运行
media/upload.js
上传素材
scripts/media/upload.js
"获取下载链接"/"获取直链"运行
media/file-token-to-url.js
获取文件URL
scripts/media/file-token-to-url.js
User Input Trigger KeywordsAI Execution ActionCorresponding Script
"View records"/"Get records"/"List records"Run
record/get.js
to query record list
scripts/record/get.js
"Add record"/"Create record"/"Insert record"Run
record/create.js
to create a single record
scripts/record/create.js
"Modify record"/"Update record"/"Edit record"Run
record/update.js
to update a single record
scripts/record/update.js
"Delete record"/"Remove record"Run
record/delete.js
to delete a single record
scripts/record/delete.js
"Batch add records"/"Add multiple records"Run
record/batch-create.js
to batch create records
scripts/record/batch-create.js
"Batch modify records"/"Update multiple records"Run
record/batch-update.js
to batch update records
scripts/record/batch-update.js
"Batch delete records"/"Clear records"Run
record/batch-delete.js
to batch delete records
scripts/record/batch-delete.js
"View tables"/"Data table list"Run
table/list.js
to list all data tables
scripts/table/list.js
"Create table"/"Add data table"Run
table/create-single.js
to create a single data table
scripts/table/create-single.js
"Modify table name"/"Rename table"Run
table/update.js
to update data table name
scripts/table/update.js
"Delete table"/"Remove data table"Run
table/delete-one.js
to delete a single data table
scripts/table/delete-one.js
"View fields"/"Column information"Run
field/list.js
to list all fields
scripts/field/list.js
"Add field"/"New column"Run
field/create.js
to create a field
scripts/field/create.js
"Modify field"/"Edit column"Run
field/update.js
to update a field
scripts/field/update.js
"Delete field"/"Remove column"Run
field/delete.js
to delete a field
scripts/field/delete.js
"Upload file"/"Upload image"/"Upload attachment"Run
media/upload.js
to upload media
scripts/media/upload.js
"Get download link"/"Get direct link"Run
media/file-token-to-url.js
to get file URL
scripts/media/file-token-to-url.js

决策流程

Decision Flow

用户请求涉及飞书多维表格?
    ├─ 是 → 检查具体操作类型
    │       │
    │       ├─ 需要访问凭证?
    │       │   └─ 运行 get-tenant-access-token.js
    │       │
    │       ├─ 需要从URL解析信息?
    │       │   └─ 运行 parse-bitable-url.js
    │       │
    │       └─ 执行具体操作
    │           ├─ 数据表操作 → table/ 脚本
    │           ├─ 记录操作 → record/ 脚本
    │           ├─ 字段操作 → field/ 脚本
    │           └─ 素材操作 → media/ 脚本
    └─ 否 → 不使用此 Skill
Does the user request involve Feishu Bitable?
    ├─ Yes → Check specific operation type
    │       │
    │       ├─ Access credential required?
    │       │   └─ Run get-tenant-access-token.js
    │       │
    │       ├─ Need to parse information from URL?
    │       │   └─ Run parse-bitable-url.js
    │       │
    │       └─ Execute specific operation
    │           ├─ Data table operations → table/ scripts
    │           ├─ Record operations → record/ scripts
    │           ├─ Field operations → field/ scripts
    │           └─ Media operations → media/ scripts
    └─ No → Do not use this Skill

如何使用这个 Skill

How to Use This Skill

功能概述

Function Overview

本 Skill 提供完整的飞书多维表格 API 操作能力:
功能模块支持的操作
数据表管理创建、更新、删除数据表(支持批量操作)
记录操作增删改查记录,支持批量操作(单次最多 1000 条)
字段管理创建、更新、删除字段,列出所有字段
素材上传上传文件、图片等素材,获取临时下载链接
This Skill provides complete Feishu Bitable API operation capabilities:
Function ModuleSupported Operations
Data Table ManagementCreate, update, delete data tables (supports batch operations)
Record OperationsCRUD for records, supports batch operations (max 1000 entries per request)
Field ManagementCreate, update, delete fields, list all fields
Media UploadUpload files, images and other media, get temporary download links

输出格式

Output Format

执行完成后,Skill 会输出:
  • 成功:返回操作结果数据(JSON 格式),包含完整的 API 响应
  • 失败:返回错误信息,包含错误码和解决建议
After execution, the Skill will output:
  • Success: Return operation result data (JSON format), including complete API response
  • Failure: Return error information, including error code and solution suggestions

前置要求

Prerequisites

  1. 有效的
    tenant_access_token
    :所有 API 操作都需要
  2. app_token
    :标识要操作的多维表格
  3. table_id
    :标识要操作的数据表(部分操作需要)
  1. Valid
    tenant_access_token
    : Required for all API operations
  2. app_token
    : Identifies the target Bitable
  3. table_id
    : Identifies the target data table (required for some operations)

参数传递方式

Parameter Passing Method

注意:本 Skill 所有脚本均使用
--parameter-file-path
参数传递配置,必须通过参数文件方式调用。
AI 调用规范:本 Skill 专为 AI 设计,AI 自动处理临时文件的创建和清理,人类用户只需用自然语言描述需求。
Note: All scripts of this Skill use the
--parameter-file-path
parameter to pass configurations, and must be called through parameter files.
AI Invocation Specification: This Skill is specially designed for AI, AI automatically handles the creation and cleanup of temporary files, human users only need to describe requirements in natural language.

AI 自动处理临时文件流程

AI Automatic Temporary File Management Process

AI 调用本 Skill 时,必须遵循以下流程自动管理临时文件:
javascript
import { createTempParamsFile, cleanupTempFile } from "./scripts/utils";
import { execSync } from "child_process";

// 1. 创建临时参数文件(自动存放在系统临时目录)
const tempFile = createTempParamsFile(
  {
    tenant_access_token: "xxx",
    app_token: "xxx",
    table_id: "xxx"
    // ... 其他参数
  },
  "operation-name"
);

try {
  // 2. 执行脚本
  const result = execSync(`node scripts/xxx.js --parameter-file-path "${tempFile}"`, { encoding: "utf-8" });
  const data = JSON.parse(result);

  // 3. 处理结果并返回给用户
  return formatResultForUser(data);
} finally {
  // 4. 确保清理临时文件(无论成功或失败)
  cleanupTempFile(tempFile);
}
关键原则
  • ✅ 临时文件必须创建在系统临时目录(
    os.tmpdir()
  • ✅ 脚本执行完成后立即清理临时文件
  • ✅ 使用
    try...finally
    确保即使出错也会清理
  • ❌ 不要将参数文件创建在技能目录或用户工作目录
When AI calls this Skill, it must follow the following process to automatically manage temporary files:
javascript
import { createTempParamsFile, cleanupTempFile } from "./scripts/utils";
import { execSync } from "child_process";

// 1. Create temporary parameter file (automatically stored in system temporary directory)
const tempFile = createTempParamsFile(
  {
    tenant_access_token: "xxx",
    app_token: "xxx",
    table_id: "xxx"
    // ... other parameters
  },
  "operation-name"
);

try {
  // 2. Execute script
  const result = execSync(`node scripts/xxx.js --parameter-file-path "${tempFile}"`, { encoding: "utf-8" });
  const data = JSON.parse(result);

  // 3. Process result and return to user
  return formatResultForUser(data);
} finally {
  // 4. Ensure temporary files are cleaned up (regardless of success or failure)
  cleanupTempFile(tempFile);
}
Key Principles:
  • ✅ Temporary files must be created in the system temporary directory (
    os.tmpdir()
    )
  • ✅ Clean up temporary files immediately after script execution is completed
  • ✅ Use
    try...finally
    to ensure cleanup even if an error occurs
  • ❌ Do not create parameter files in the skill directory or user working directory

标准使用流程

Standard Usage Process

步骤 1:获取访问凭证
bash
node scripts/get-tenant-access-token.js --parameter-file-path params.json
参数文件示例 (
params.json
):
json
{
  "appId": "cli_xxx",
  "appSecret": "xxx"
}
详细凭证管理规则参见 认证与凭证管理指南
步骤 2:解析多维表格 URL
从 URL 中提取
app_token
table_id
bash
node scripts/parse-bitable-url.js --parameter-file-path params.json
步骤 3:执行具体操作
根据需求选择对应的脚本:
bash
undefined
Step 1: Obtain Access Credentials
bash
node scripts/get-tenant-access-token.js --parameter-file-path params.json
Parameter file example (
params.json
):
json
{
  "appId": "cli_xxx",
  "appSecret": "xxx"
}
For detailed credential management rules, please refer to Authentication and Credential Management Guide.
Step 2: Parse Bitable URL
Extract
app_token
and
table_id
from URL:
bash
node scripts/parse-bitable-url.js --parameter-file-path params.json
Step 3: Execute Specific Operations
Select the corresponding script according to requirements:
bash
undefined

查询记录

Query records

node scripts/record/get.js --parameter-file-path "params.json"
node scripts/record/get.js --parameter-file-path "params.json"

创建记录

Create record

node scripts/record/create.js --parameter-file-path "params.json"
node scripts/record/create.js --parameter-file-path "params.json"

批量创建记录

Batch create records

node scripts/record/batch-create.js --parameter-file-path "params.json"
undefined
node scripts/record/batch-create.js --parameter-file-path "params.json"
undefined

核心概念

Core Concepts

概念说明
多维表格 (Bitable)字节跳动的产品,结合电子表格的灵活性和数据库的结构化特性
数据表 (Table)多维表格中的单个表格,类似 Excel 工作表
记录 (Record)数据表中的一行数据
字段 (Field)数据表中的一列的表头,用于设定该列的数据类型
素材 (Media)上传的文件、图片、视频等
ConceptDescription
BitableA ByteDance product that combines the flexibility of spreadsheets and the structured features of databases
TableA single table in Bitable, similar to an Excel worksheet
RecordA row of data in a data table
FieldThe header of a column in a data table, used to set the data type of the column
MediaUploaded files, images, videos, etc.

操作接口速查

Operation Interface Quick Reference

基础操作

Basic Operations

Action脚本路径说明
获取访问凭证get-tenant-access-token.js获取
tenant_access_token
解析飞书多维表格的URLparse-bitable-url.js从 URL 提取
app_token
table_id
view_id
ActionScript PathDescription
Obtain access credentialsget-tenant-access-token.jsGet
tenant_access_token
Parse Feishu Bitable URLparse-bitable-url.jsExtract
app_token
,
table_id
,
view_id
from URL

数据表操作

Table Operations

Action脚本路径说明
新增一个数据表create-single.js支持指定名称、视图和字段
新增多个数据表batch-create.js仅可指定数据表名称
更新数据表名称update.js更新指定数据表的名称
列出数据表list.js获取所有数据表的 ID、版本号和名称
删除一个数据表delete-one.js通过
app_token
table_id
删除
删除多个数据表batch-delete.js批量删除多个数据表
详细参数参见 table 参考文档 目录。
ActionScript PathDescription
Add a new data tablecreate-single.jsSupport specifying name, view and fields
Add multiple data tablesbatch-create.jsOnly data table names can be specified
Update data table nameupdate.jsUpdate the name of the specified data table
List data tableslist.jsGet ID, version number and name of all data tables
Delete a data tabledelete-one.jsDelete by
app_token
and
table_id
Delete multiple data tablesbatch-delete.jsBatch delete multiple data tables
For detailed parameters, please refer to the table reference document directory.

记录操作

Record Operations

Action脚本路径说明
新增记录create.js在数据表中新增一条记录
更新记录update.js更新数据表中的一条记录
查询记录get.js单次最多查询 500 行,支持分页
删除记录delete.js删除数据表中的一条记录
新增多条记录batch-create.js单次最多新增 1,000 条
更新多条记录batch-update.js单次最多更新 1,000 条
批量获取记录batch-get.js通过记录 ID 查询,最多 100 条
删除多条记录batch-delete.js批量删除多条记录
详细参数参见 record 参考文档 目录。
ActionScript PathDescription
Add recordcreate.jsAdd a new record to the data table
Update recordupdate.jsUpdate a record in the data table
Query recordsget.jsQuery up to 500 rows at a time, support pagination
Delete recorddelete.jsDelete a record from the data table
Add multiple recordsbatch-create.jsAdd up to 1,000 entries at a time
Update multiple recordsbatch-update.jsUpdate up to 1,000 entries at a time
Batch get recordsbatch-get.jsQuery by record ID, up to 100 entries
Delete multiple recordsbatch-delete.jsBatch delete multiple records
For detailed parameters, please refer to the record reference document directory.

字段操作

Field Operations

Action脚本路径说明
新增字段create.js在数据表中新增一个字段
更新字段update.js全量更新字段(property 会被覆盖)
列出字段list.js获取数据表中的所有字段
删除字段delete.js删除数据表中的一个字段
详细参数参见 field 参考文档 目录。
ActionScript PathDescription
Add fieldcreate.jsAdd a new field to the data table
Update fieldupdate.jsFull update field (properties will be overwritten)
List fieldslist.jsGet all fields in the data table
Delete fielddelete.jsDelete a field from the data table
For detailed parameters, please refer to the field reference document directory.

素材/文件操作

Media/File Operations

Action脚本路径说明
素材上传upload.js上传文件、图片、视频等素材
获取直链file-token-to-url.js
file_token
转临时下载链接(24小时有效)
详细参数参见 media 参考文档 目录。
ActionScript PathDescription
Media uploadupload.jsUpload files, images, videos and other media
Get direct linkfile-token-to-url.jsConvert
file_token
to temporary download link (valid for 24 hours)
For detailed parameters, please refer to the media reference document directory.

文件和目录使用说明

File and Directory Usage Instructions

项目说明
文档位置
references/
目录下的文档,有具体的 API 调用命令或脚本执行方式
脚本位置
scripts/
目录下的 Node.js 脚本直接使用
临时文件系统临时目录 (
%TEMP%
/tmp
),操作完成后自动删除
参数文件系统临时目录,使用绝对路径引用
上传记录系统临时目录 (
feishu-bitable-upload-records.json
)
ItemDescription
Document locationDocuments under the
references/
directory, with specific API call commands or script execution methods
Script locationNode.js scripts under the
scripts/
directory can be used directly
Temporary filesSystem temporary directory (
%TEMP%
or
/tmp
), automatically deleted after operation is completed
Parameter filesSystem temporary directory, referenced using absolute paths
Upload recordsSystem temporary directory (
feishu-bitable-upload-records.json
)

临时文件管理最佳实践

Best Practices for Temporary File Management

本技能所有临时文件(参数文件、上传记录)均存放在系统临时目录,避免污染用户主目录和技能目录:
Windows 示例
C:\Users\xxx\AppData\Local\Temp\feishu-create-record-1740374400000-a7x9k2.json
C:\Users\xxx\AppData\Local\Temp\feishu-bitable-upload-records.json
Linux/Mac 示例
/tmp/feishu-create-record-1740374400000-a7x9k2.json
/tmp/feishu-bitable-upload-records.json
All temporary files (parameter files, upload records) of this skill are stored in the system temporary directory to avoid polluting the user's home directory and skill directory:
Windows Example:
C:\Users\xxx\AppData\Local\Temp\feishu-create-record-1740374400000-a7x9k2.json
C:\Users\xxx\AppData\Local\Temp\feishu-bitable-upload-records.json
Linux/Mac Example:
/tmp/feishu-create-record-1740374400000-a7x9k2.json
/tmp/feishu-bitable-upload-records.json

工具函数使用示例

Utility Function Usage Example

javascript
import { createTempParamsFile, cleanupTempFile, cleanupAllTempFiles } from './utils';

// 1. 创建临时参数文件(自动存放在系统临时目录)
const params = {
  tenant_access_token: 'xxx',
  app_token: 'xxx',
  table_id: 'xxx',
  fields: { ... }
};
const tempFilePath = createTempParamsFile(params, 'create-record');

// 2. 执行脚本
const result = await executeScript(tempFilePath);

// 3. 立即清理临时文件
cleanupTempFile(tempFilePath);

// 4. 清理所有过期的临时文件(24小时前的)
cleanupAllTempFiles();
临时文件命名规范
  • 格式:
    feishu-{operation}-{timestamp}-{random}.json
  • 示例:
    feishu-batch-create-1740374400000-a7x9k2.json
清理策略
  • 成功或失败都立即尝试删除参数文件
  • 删除失败不影响主流程
  • 系统临时目录自动定期清理
  • 运行
    cleanupAllTempFiles()
    批量清理过期文件(24小时前)
javascript
import { createTempParamsFile, cleanupTempFile, cleanupAllTempFiles } from './utils';

// 1. Create temporary parameter file (automatically stored in system temporary directory)
const params = {
  tenant_access_token: 'xxx',
  app_token: 'xxx',
  table_id: 'xxx',
  fields: { ... }
};
const tempFilePath = createTempParamsFile(params, 'create-record');

// 2. Execute script
const result = await executeScript(tempFilePath);

// 3. Clean up temporary files immediately
cleanupTempFile(tempFilePath);

// 4. Clean up all expired temporary files (older than 24 hours)
cleanupAllTempFiles();
Temporary File Naming Convention:
  • Format:
    feishu-{operation}-{timestamp}-{random}.json
  • Example:
    feishu-batch-create-1740374400000-a7x9k2.json
Cleanup Policy:
  • Try to delete the parameter file immediately regardless of success or failure
  • Deletion failure does not affect the main process
  • System temporary directory is automatically cleaned up regularly
  • Run
    cleanupAllTempFiles()
    to batch clean up expired files (older than 24 hours)

AI 处理示例

AI Processing Example

用户说:"帮我在飞书表格 https://xxx.feishu.cn/wiki/xxx 里添加一条记录,任务名称是'完成报告',进度50%"
AI 执行步骤
步骤执行动作脚本/命令
1检查 tenant_access_token如无则运行
get-tenant-access-token.js
2解析 URL 获取 app_token 和 table_id运行
parse-bitable-url.js
3创建临时参数文件运行
createTempParamsFile()
,存放在系统临时目录
4创建记录运行
record/create.js
5清理临时参数文件运行
cleanupTempFile()
6返回结果向用户返回:"已成功创建记录!记录ID: recxxx"
用户感知:完全不需要知道临时文件的存在,只需自然语言交互。
User says: "Help me add a record to the Feishu table https://xxx.feishu.cn/wiki/xxx, the task name is 'Complete Report', progress 50%"
AI Execution Steps:
StepExecution ActionScript/Command
1Check tenant_access_tokenIf not available, run
get-tenant-access-token.js
2Parse URL to get app_token and table_idRun
parse-bitable-url.js
3Create temporary parameter fileRun
createTempParamsFile()
, stored in system temporary directory
4Create recordRun
record/create.js
5Clean up temporary parameter fileRun
cleanupTempFile()
6Return resultReturn to user: "Record created successfully! Record ID: recxxx"
User Perception: Users do not need to know the existence of temporary files at all, only need to interact in natural language.

错误处理

Error Handling

错误场景错误表现处理方式
缺少访问凭证API 返回 401/403 错误运行
get-tenant-access-token.js
获取凭证
访问凭证过期API 返回 错误代码: 99991663, 错误信息: Invalid access token for authorization运行
get-tenant-access-token.js
获取凭证
URL 解析失败无法提取 app_token/table_id检查 URL 格式是否正确,或手动提供参数
记录不存在API 返回 404 错误检查 record_id 是否正确,或先运行
record/get.js
查询
字段类型不匹配API 返回 400 错误运行
field/list.js
查看字段类型,调整参数后重试
文本字段格式错误
TextFieldConvFail
错误
文本字段使用字符串格式,不要用富文本数组格式
字段更新缺少参数
field validation failed
更新字段时必须提供
type
参数
文件token格式错
Cannot read properties
使用
file_tokens
(数组)而非
file_token
(字符串)
批量操作超限API 返回 422 错误减少单次操作数量(记录最多1000条,批量获取最多100条)
临时文件创建失败磁盘空间不足或权限问题检查系统临时目录权限和磁盘空间
网络超时请求无响应检查网络连接,稍后重试
Error ScenarioError PerformanceHandling Method
Missing access credentialsAPI returns 401/403 errorRun
get-tenant-access-token.js
to obtain credentials
Expired access credentialsAPI returns error code: 99991663, error message: Invalid access token for authorizationRun
get-tenant-access-token.js
to obtain credentials
URL parsing failedUnable to extract app_token/table_idCheck if the URL format is correct, or provide parameters manually
Record does not existAPI returns 404 errorCheck if record_id is correct, or run
record/get.js
to query first
Field type mismatchAPI returns 400 errorRun
field/list.js
to view field type, adjust parameters and try again
Text field format error
TextFieldConvFail
error
Use string format for text fields, do not use rich text array format
Missing parameters for field update
field validation failed
Must provide
type
parameter when updating fields
File token format error
Cannot read properties
Use
file_tokens
(array) instead of
file_token
(string)
Batch operation exceeds limitAPI returns 422 errorReduce the number of operations per request (max 1000 records, max 100 for batch query)
Temporary file creation failedInsufficient disk space or permission issuesCheck system temporary directory permissions and disk space
Network timeoutNo response to requestCheck network connection, try again later

常见错误详解

Detailed Explanation of Common Errors

1. 文本字段格式错误 (TextFieldConvFail)

1. Text Field Format Error (TextFieldConvFail)

错误信息
the value of 'Multiline' must be a string
原因:创建/更新记录时,文本字段使用了查询返回的富文本数组格式
解决
  • ❌ 错误:
    "字段名": [{"text": "内容", "type": "text"}]
  • ✅ 正确:
    "字段名": "内容"
Error Message:
the value of 'Multiline' must be a string
Cause: When creating/updating records, the text field uses the rich text array format returned by the query
Solution:
  • ❌ Wrong:
    "Field Name": [{"text": "Content", "type": "text"}]
  • ✅ Correct:
    "Field Name": "Content"

2. 字段更新缺少 type 参数

2. Missing
type
Parameter for Field Update

错误信息
field validation failed - type is required
原因:更新字段时未提供
type
参数
解决:更新字段时必须包含
type
,如
"type": 1
(1=文本, 2=数字)
Error Message:
field validation failed - type is required
Cause: The
type
parameter is not provided when updating the field
Solution: The
type
parameter must be included when updating fields, e.g.
"type": 1
(1=text, 2=number)

3. 获取文件下载链接参数错误

3. Wrong Parameter for Getting File Download Link

错误信息
Cannot read properties of undefined (reading 'map')
原因:使用了
file_token
而不是
file_tokens
解决
  • ❌ 错误:
    "file_token": "xxx"
  • ✅ 正确:
    "file_tokens": ["xxx"]
Error Message:
Cannot read properties of undefined (reading 'map')
Cause: Used
file_token
instead of
file_tokens
Solution:
  • ❌ Wrong:
    "file_token": "xxx"
  • ✅ Correct:
    "file_tokens": ["xxx"]

参考文档

Reference Documents

文档说明
认证与凭证管理指南详细的凭证管理说明,包括 App ID/App Secret 获取、tenant_access_token 自动获取流程
获取访问凭证 API获取 tenant_access_token 的具体 API 调用说明和脚本使用方法
解析飞书 URL 工具从飞书多维表格 URL 中提取 app_token、table_id、view_id 的工具使用说明
常见错误及解决方案API 调用常见错误码及排查方法
参数配置示例与最佳实践各种操作场景的参数配置示例
DocumentDescription
Authentication and Credential Management GuideDetailed credential management instructions, including App ID/App Secret acquisition, tenant_access_token automatic acquisition process
Obtain Access Credential APISpecific API call instructions and script usage methods for obtaining tenant_access_token
Feishu URL Parsing ToolUsage instructions for the tool to extract app_token, table_id, view_id from Feishu Bitable URL
Common Errors and SolutionsCommon API call error codes and troubleshooting methods
Parameter Configuration Examples and Best PracticesParameter configuration examples for various operation scenarios