feishu-bitable

$27

用户意图

工具

action

必填参数

常用可选

查表有哪些字段

feishu_bitable_app_table_field

list

app_token, table_id

-

查记录

feishu_bitable_app_table_record

list

app_token, table_id

filter, sort, field_names

新增一行

feishu_bitable_app_table_record

create

app_token, table_id, fields

-

批量导入

feishu_bitable_app_table_record

batch_create

app_token, table_id, records (≤500)

-

更新一行

feishu_bitable_app_table_record

update

app_token, table_id, record_id, fields

-

批量更新

feishu_bitable_app_table_record

batch_update

app_token, table_id, records (≤500)

-

创建多维表格

feishu_bitable_app

create

name

folder_token

创建数据表

feishu_bitable_app_table

create

app_token, name

fields

创建字段

feishu_bitable_app_table_field

create

app_token, table_id, field_name, type

property

创建视图

feishu_bitable_app_table_view

create

app_token, table_id, view_name, view_type

-

🎯 核心约束（Schema 未透露的知识）

📚 详细参考文档

当遇到字段配置、记录值格式问题或需要完整示例时，查阅以下文档：

• 字段 Property 配置详解 - 每种字段类型创建/更新时需要的 property 参数结构（单选的 options、进度的 min/max、关联的 table_id 等）

• 记录值数据结构详解 - 每种字段类型在记录中对应的 fields 值格式（人员字段只传 id、日期是毫秒时间戳、附件需先上传等）

• 使用场景完整示例 - 8 个完整场景示例（创建表模式对比、批量导入、筛选查询、附件处理、关联字段等）

何时查阅:

• 创建/更新字段时收到 125408X 错误码（property 结构错误）→ 查 field-properties.md

• 写入记录时收到 125406X 错误码（字段值转换失败）→ 查 record-values.md

• 需要完整的操作流程和参数示例 → 查 examples.md

1. 字段类型与值格式必须严格匹配

Bitable 最大的坑：不同字段类型对 value 的数据结构要求完全不同。

#### 最易错的字段类型（完整列表见 record-values.md ）

type

ui_type

字段类型

正确格式

❌ 常见错误

11

User

人员

[{id: "ou_xxx"}]

传字符串 "ou_xxx" 或 [{name: "张三"}]

5

DateTime

日期

1674206443000（毫秒）

传秒时间戳或字符串

3

SingleSelect

单选

"选项名"

传数组 ["选项名"]

4

MultiSelect

多选

["选项1", "选项2"]

传字符串 "选项1"

15

Url

超链接

{link: "...", text: "..."}

只传字符串 URL

17

Attachment

附件

[{file_token: "..."}]

传外部 URL 或本地路径

强制流程：

• 先调用 feishu_bitable_app_table_field.list 获取字段的 type 和 ui_type

• 根据上表或 record-values.md 构造正确格式

• 错误码 125406X 或 1254015 → 检查字段值格式

人员字段特别注意：

• 默认使用 open_id（ou_...），与 calendar/task 一致

• 格式：[{id: "ou_xxx"}]（数组对象）

• 只能传 id 字段，不能传 name/email 等

📌 核心使用场景

完整示例: 查阅 examples.md 了解更多场景（创建表模式对比、空行处理、附件上传、关联字段等）

场景 1: 查字段类型（必做第一步）

{

  "action": "list",

  "app_token": "S404b...",

  "table_id": "tbl..."

}

返回：包含每个字段的 field_id、field_name、type、ui_type、property

场景 2: 批量导入客户数据

{

  "action": "batch_create",

  "app_token": "S404b...",

  "table_id": "tbl...",

  "records": [

    {

      "fields": {

        "客户名称": "Bytedance",

        "负责人": [{"id": "ou_xxx"}],

        "签约日期": 1674206443000,

        "状态": "进行中"

      }

    },

    {

      "fields": {

        "客户名称": "飞书",

        "负责人": [{"id": "ou_yyy"}],

        "签约日期": 1675416243000,

        "状态": "已完成"

      }

    }

  ]

}

字段值格式：

• 人员：[{id: "ou_xxx"}]（数组对象）

• 日期：毫秒时间戳

• 单选：字符串

• 多选：字符串数组

限制: 最多 500 条记录

场景 3: 筛选查询（高级筛选）

{

  "action": "list",

  "app_token": "S404b...",

  "table_id": "tbl...",

  "filter": {

    "conjunction": "and",

    "conditions": [

      {

        "field_name": "状态",

        "operator": "is",

        "value": ["进行中"]

      },

      {

        "field_name": "截止日期",

        "operator": "isLess",

        "value": ["ExactDate", "1740441600000"]

      }

    ]

  },

  "sort": [

    {

      "field_name": "截止日期",

      "desc": false

    }

  ]

}

filter 说明：

• 支持 10 种 operator（is/isNot/contains/isEmpty 等，见附录 C）

• ⚠️ **isEmpty/isNotEmpty 必须传 value: []**（虽然逻辑上不需要值，但 API 要求必须传空数组）

• 日期筛选可使用 ["Today"]、["ExactDate", "时间戳"] 等

• sort 可指定多个排序字段

🔍 常见错误与排查

错误码

错误现象

根本原因

解决方案

1254064

DatetimeFieldConvFail

日期字段格式错误

必须用毫秒时间戳（如 1772121600000），不能用字符串（"2026-02-27"、RFC3339）或秒级时间戳

1254068

URLFieldConvFail

超链接字段格式错误

必须用对象 {text: "显示文本", link: "URL"}，不能直接传字符串 URL

1254066

UserFieldConvFail

人员字段格式错误或 ID 类型不匹配

必须传 [{id: "ou_xxx"}]，确认 user_id_type

1254015

Field types do not match

字段值格式与类型不匹配

先 list 字段，按类型构造正确格式

1254104

RecordAddOnceExceedLimit

批量创建超过 500 条

分批调用，每批 ≤ 500

1254291

Write conflict

并发写冲突

串行调用 + 延迟 0.5-1 秒

1254303

AttachPermNotAllow

附件未上传到当前表格

先调用上传素材接口

1254045

FieldNameNotFound

字段名不存在

检查字段名（包括空格、大小写）

📚 附录：背景知识

A. 资源层级关系

App (多维表格应用)

 ├── Table (数据表) ×100

 │    ├── Record (记录/行) ×20,000

 │    ├── Field (字段/列) ×300

 │    └── View (视图) ×200

 └── Dashboard (仪表盘)

B. 筛选条件 operator 列表

operator

含义

支持字段

value 要求

is

等于

所有

单个值

isNot

不等于

除日期外

单个值

contains

包含

除日期外

可多个值

doesNotContain

不包含

除日期外

可多个值

isEmpty

为空

所有

必须为 []

isNotEmpty

不为空

所有

必须为 []

isGreater

大于

数字、日期

单个值

isGreaterEqual

大于等于

数字（不支持日期）

单个值

isLess

小于

数字、日期

单个值

isLessEqual

小于等于

数字（不支持日期）

单个值

日期字段特殊值: ["Today"], ["Tomorrow"], ["ExactDate", "时间戳"] 等（完整列表见 examples.md）

C. 使用限制

限制项

上限

数据表 + 仪表盘

100（单个 App）

记录数

20,000（单个数据表）

字段数

300（单个数据表）

视图数

200（单个数据表）

批量创建/更新/删除

500（单次 API 调用）

单元格文本

10 万字符

单选/多选选项

20,000（单个字段）

单元格附件

100

单元格人员

1,000

D. 其他约束

• 从其他数据源同步的数据表，不支持增删改记录

• 公式字段、查看引用字段是只读的

• 删除操作无法恢复

• 视图筛选条件使用 field_id，需先调用 field.list 获取