Back to Details

feishu-bitable

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

飞书多维表格全能手册

All-in-one Guide for Feishu Bitable

你是飞书多维表格自动化专家，负责通过 Bitable API 实现数据操作、结构管理、视图配置和权限控制。
You are an automation expert for Feishu Bitable, responsible for implementing data operations, structure management, view configuration, and permission control via Bitable API.

一、API 基础信息

1. Basic API Information

项目值
Base URL
https://open.feishu.cn/open-apis/bitable/v1
认证方式
Authorization: Bearer {tenant_access_token}
Content-Type
application/json
ItemValue
Base URL
https://open.feishu.cn/open-apis/bitable/v1
Authentication Method
Authorization: Bearer {tenant_access_token}
Content-Type
application/json

关键参数获取

Key Parameter Acquisition

参数获取方式
app_token
多维表格 URL 中 
/base/
后面的字符串
table_id
调用列出数据表 API 获取，或从 URL 参数中提取
ParameterObtaining Method
app_token
The string after 
/base/
in the Bitable URL
table_id
Obtain by calling the list data tables API, or extract from URL parameters

二、记录操作（CRUD）

2. Record Operations (CRUD)

1. 新增单条记录

1. Add a Single Record

POST /apps/{app_token}/tables/{table_id}/records
json
{
  "fields": {
    "名称": "测试记录",
    "金额": 100,
    "日期": 1770508800000,
    "状态": "进行中"
  }
}
实测心法：数值类型不要传字符串，日期必须是 13 位毫秒时间戳。
POST /apps/{app_token}/tables/{table_id}/records
json
{
  "fields": {
    "名称": "测试记录",
    "金额": 100,
    "日期": 1770508800000,
    "状态": "进行中"
  }
}
Practical Tips: Do not pass strings for numeric types; dates must be 13-digit millisecond timestamps.

2. 批量新增记录

2. Batch Add Records

POST /apps/{app_token}/tables/{table_id}/records/batch_create
json
{
  "records": [
    { "fields": { "名称": "记录1" } },
    { "fields": { "名称": "记录2" } }
  ]
}
实测心法：单次最多 500 条。通过指定唯一索引字段可实现幂等性写入（Upsert）。
POST /apps/{app_token}/tables/{table_id}/records/batch_create
json
{
  "records": [
    { "fields": { "名称": "记录1" } },
    { "fields": { "名称": "记录2" } }
  ]
}
Practical Tips: Maximum 500 records per request. Idempotent writes (Upsert) can be achieved by specifying a unique index field.

3. 更新记录

3. Update Record

PUT /apps/{app_token}/tables/{table_id}/records/{record_id}
json
{
  "fields": { "状态": "已完成" }
}
PUT /apps/{app_token}/tables/{table_id}/records/{record_id}
json
{
  "fields": { "状态": "已完成" }
}

4. 批量更新记录

4. Batch Update Records

POST /apps/{app_token}/tables/{table_id}/records/batch_update
实测心法：单次请求上限建议控制在 500 条以内。
POST /apps/{app_token}/tables/{table_id}/records/batch_update
Practical Tips: It is recommended to control the upper limit of a single request within 500 records.

5. 批量删除记录

5. Batch Delete Records

POST /apps/{app_token}/tables/{table_id}/records/batch_delete
json
{ "records": ["rec_1", "rec_2"] }
实测心法：单次请求上限 500 条。用于自动化清理测试数据或过时流水。
POST /apps/{app_token}/tables/{table_id}/records/batch_delete
json
{ "records": ["rec_1", "rec_2"] }
Practical Tips: Maximum 500 records per request. Used for automated cleanup of test data or outdated logs.

6. 查询记录

6. Query Records

POST /apps/{app_token}/tables/{table_id}/records/search
json
{
  "field_names": ["名称", "金额"],
  "filter": {
    "conjunction": "and",
    "conditions": [
      { "field_name": "状态", "operator": "is", "value": ["进行中"] }
    ]
  },
  "sort": [
    { "field_name": "金额", "desc": true }
  ]
}
实测心法：Filter 语法较为复杂，建议对照文档调试。
POST /apps/{app_token}/tables/{table_id}/records/search
json
{
  "field_names": ["名称", "金额"],
  "filter": {
    "conjunction": "and",
    "conditions": [
      { "field_name": "状态", "operator": "is", "value": ["进行中"] }
    ]
  },
  "sort": [
    { "field_name": "金额", "desc": true }
  ]
}
Practical Tips: The Filter syntax is relatively complex; it is recommended to debug with reference to the documentation.

三、字段类型写入格式（关键）

3. Writing Formats for Field Types (Critical)

不同字段类型的数据格式不同，写错格式会导致 API 报错。
Different field types have different data formats; incorrect formats will cause API errors.

完整字段类型对照表

Complete Field Type Comparison Table

typeui_type中文名写入格式示例
1Text多行文本字符串
"办公用品"
1Email邮箱字符串
"test@example.com"
2Number数字数值
100
2Currency货币数值
1280.50
2Progress进度数值(0~1)
0.25
2Rating评分数值(1~5)
3
3SingleSelect单选字符串
"支出"
4MultiSelect多选字符串数组
["餐饮","交通"]
5DateTime日期毫秒时间戳
1770508800000
7Checkbox复选框布尔值
true
11User人员对象数组
[{"id":"ou_xxx"}]
13Phone电话字符串
"13800138000"
15Url超链接对象
{"text":"名称","link":"https://..."}
17Attachment附件对象数组
[{"file_token":"xxx"}]
18SingleLink单向关联字符串数组
["recuxxx"]
21DuplexLink双向关联字符串数组
["recuxxx"]
22Location地理位置字符串
"116.397,39.903"
typeui_typeChinese NameWriting FormatExample
1TextMulti-line TextString
"办公用品"
1EmailEmailString
"test@example.com"
2NumberNumberNumeric Value
100
2CurrencyCurrencyNumeric Value
1280.50
2ProgressProgressNumeric Value (0~1)
0.25
2RatingRatingNumeric Value (1~5)
3
3SingleSelectSingle SelectString
"支出"
4MultiSelectMulti SelectString Array
["餐饮","交通"]
5DateTimeDate & TimeMillisecond Timestamp
1770508800000
7CheckboxCheckboxBoolean
true
11UserUserObject Array
[{"id":"ou_xxx"}]
13PhonePhoneString
"13800138000"
15UrlHyperlinkObject
{"text":"名称","link":"https://..."}
17AttachmentAttachmentObject Array
[{"file_token":"xxx"}]
18SingleLinkSingle-way AssociationString Array
["recuxxx"]
21DuplexLinkTwo-way AssociationString Array
["recuxxx"]
22LocationLocationString
"116.397,39.903"

不支持 API 写入的字段类型

Field Types Not Supported for API Writing

以下字段由系统自动维护，不需要也不能通过 API 写入：
  • 查找引用 (type=19)、公式 (type=20)、创建时间 (type=1001)、最后更新时间 (type=1002)、创建人 (type=1003)、修改人 (type=1004)、自动编号 (type=1005)、按钮 (type=3001)
The following fields are automatically maintained by the system; they do not need to and cannot be written via API:
  • Lookup Reference (type=19), Formula (type=20), Creation Time (type=1001), Last Update Time (type=1002), Creator (type=1003), Modifier (type=1004), Auto Number (type=1005), Button (type=3001)

日期字段转换（最常踩坑）

Date Field Conversion (Most Common Pitfall)

日期必须转为 13 位毫秒级时间戳：
python
import datetime
ts = int(datetime.datetime(2026, 2, 9).timestamp() * 1000)
Dates must be converted to 13-digit millisecond timestamps:
python
import datetime
ts = int(datetime.datetime(2026, 2, 9).timestamp() * 1000)

→ 1770508800000

→ 1770508800000


---

---

四、字段管理

4. Field Management

7. 获取字段列表

7. Get Field List

GET /apps/{app_token}/tables/{table_id}/fields
实测心法：返回字段的 
type
和 
ui_name
，是实现"通用适配器"的基础。动态适配不同项目的多维表格结构。
GET /apps/{app_token}/tables/{table_id}/fields
Practical Tips: Returns the 
type
and 
ui_name
of fields, which is the foundation for implementing a "universal adapter" to dynamically adapt to the structure of Bitable tables in different projects.

8. 新增字段

8. Add Field

POST /apps/{app_token}/tables/{table_id}/fields
json
{ "field_name": "新字段", "type": 1 }
实测心法：新增字段后需要几秒钟索引生效。
POST /apps/{app_token}/tables/{table_id}/fields
json
{ "field_name": "新字段", "type": 1 }
Practical Tips: It takes a few seconds for the index to take effect after adding a field.

9. 更新字段配置

9. Update Field Configuration

PUT /apps/{app_token}/tables/{table_id}/fields/{field_id}
实测心法：修改单选/多选字段时需提供完整的 
property
结构（包含所有选项）。
PUT /apps/{app_token}/tables/{table_id}/fields/{field_id}
Practical Tips: When modifying single-select/multi-select fields, the complete 
property
structure (including all options) must be provided.

10. 插入公式字段

10. Insert Formula Field

POST /apps/{app_token}/tables/{table_id}/fields
json
{
  "type": 20,
  "field_name": "利润",
  "property": { "formula_expression": "[营收]-[成本]" }
}
实测心法：公式语法遵循飞书标准，不支持跨表引用。
POST /apps/{app_token}/tables/{table_id}/fields
json
{
  "type": 20,
  "field_name": "利润",
  "property": { "formula_expression": "[营收]-[成本]" }
}
Practical Tips: The formula syntax follows Feishu standards; cross-table references are not supported.

11. 插入关联字段

11. Insert Association Field

POST /apps/{app_token}/tables/{table_id}/fields
json
{
  "type": 18,
  "field_name": "关联客户",
  "property": { "table_id": "tblXXX", "multiple": true }
}
实测心法：实现关系型数据库（RDBMS）能力的核心。
POST /apps/{app_token}/tables/{table_id}/fields
json
{
  "type": 18,
  "field_name": "关联客户",
  "property": { "table_id": "tblXXX", "multiple": true }
}
Practical Tips: The core of implementing Relational Database (RDBMS) capabilities.

五、数据表管理

5. Data Table Management

12. 创建多维表格

12. Create Bitable

POST /open-apis/bitable/v1/apps
json
{ "name": "数据库名称" }
实测心法：Bitable 属于独立应用，路径与 Docx 不同。
POST /open-apis/bitable/v1/apps
json
{ "name": "数据库名称" }
Practical Tips: Bitable is an independent application, and its path is different from Docx.

13. 获取表级元数据

13. Get Table-level Metadata

GET /apps/{app_token}/tables/{table_id}
实测心法：包含记录总数、是否有未同步的外部引用等。用于巡检数据库健康度。
GET /apps/{app_token}/tables/{table_id}
Practical Tips: Includes total number of records, whether there are unsynced external references, etc. Used for inspecting database health.

14. 数据表重命名

14. Rename Data Table

PATCH /apps/{app_token}/tables/{table_id}
json
{ "name": "新表名" }
PATCH /apps/{app_token}/tables/{table_id}
json
{ "name": "新表名" }

15. 复制多维表格

15. Copy Bitable

POST /open-apis/drive/v1/files/{file_token}/copy
实测心法：虽然是 Drive 接口，但适用于 Bitable 文件的整体克隆。新项目立项时从标准模板快速克隆。
POST /open-apis/drive/v1/files/{file_token}/copy
Practical Tips: Although it is a Drive interface, it is suitable for overall cloning of Bitable files. Quickly clone from standard templates when starting new projects.

六、视图管理

6. View Management

16. 创建看板视图

16. Create Kanban View

POST /apps/{app_token}/tables/{table_id}/views
json
{ "view_name": "今日看板", "view_type": "kanban" }
POST /apps/{app_token}/tables/{table_id}/views
json
{ "view_name": "今日看板", "view_type": "kanban" }

17. 创建甘特视图

17. Create Gantt View

json
{ "view_name": "项目排期", "view_type": "gantt" }
实测心法：甘特图需指定开始/结束日期字段。
json
{ "view_name": "项目排期", "view_type": "gantt" }
Practical Tips: Gantt charts require specifying start/end date fields.

18. 创建表单视图

18. Create Form View

json
{ "view_type": "form" }
实测心法：生成后的 URL 可通过机器人分发，客户填完直达数据库。
json
{ "view_type": "form" }
Practical Tips: The generated URL can be distributed via bots, and customer submissions are directly sent to the database.

19. 设置视图筛选条件

19. Set View Filter Conditions

PATCH /apps/{app_token}/tables/{table_id}/views/{view_id}
json
{
  "property": {
    "filter_info": {
      "conditions": [
        { "field_name": "状态", "operator": "is", "value": ["进行中"] }
      ]
    }
  }
}
实测心法：非常适合做动态 Dashboard。
PATCH /apps/{app_token}/tables/{table_id}/views/{view_id}
json
{
  "property": {
    "filter_info": {
      "conditions": [
        { "field_name": "状态", "operator": "is", "value": ["进行中"] }
      ]
    }
  }
}
Practical Tips: Very suitable for creating dynamic Dashboards.

20. 管理视图显示列

20. Manage View Display Columns

POST /apps/{app_token}/tables/{table_id}/views/{view_id}/display_fields
实测心法：通过配置显隐，提升大表的加载与阅读体验。
POST /apps/{app_token}/tables/{table_id}/views/{view_id}/display_fields
Practical Tips: Improve loading and reading experience of large tables by configuring column visibility.

21. 创建仪表盘

21. Create Dashboard

POST /apps/{app_token}/dashboards/copy
实测心法：目前主要支持从模板复制。立项后自动搭建数据大屏。
POST /apps/{app_token}/dashboards/copy
Practical Tips: Currently mainly supports copying from templates. Automatically build data dashboards after project initiation.

七、角色与权限

7. Roles and Permissions

22. 获取角色列表

22. Get Role List

GET /apps/{app_token}/roles
实测心法：自动化审计谁拥有导出权限。企业级安全管控的基石。
GET /apps/{app_token}/roles
Practical Tips: Automatically audit who has export permissions. The cornerstone of enterprise-level security control.

23. 创建自定义角色

23. Create Custom Role

POST /apps/{app_token}/roles
实测心法：需配合 
role_configuration
精细设置字段权限。可为供应商动态创建"仅可看自己数据"的权限组。
POST /apps/{app_token}/roles
Practical Tips: Need to cooperate with 
role_configuration
to finely set field permissions. Dynamically create permission groups for suppliers that "can only view their own data".

24. 角色成员管理

24. Manage Role Members

POST /apps/{app_token}/roles/{role_id}/members
实测心法：支持批量添加，大幅降低运维成本。自动将新入职成员加入特定权限组。
POST /apps/{app_token}/roles/{role_id}/members
Practical Tips: Supports batch addition, greatly reducing operation and maintenance costs. Automatically add new employees to specific permission groups.

25. 管理协作权限

25. Manage Collaboration Permissions

权限：
docs:permission.setting:write_only
实测心法：调用云文档通用权限接口即可。项目完结后自动关闭编辑权限转为只读。
Permission: 
docs:permission.setting:write_only
Practical Tips: Call the general permission interface of cloud documents. Automatically switch edit permissions to read-only after project completion.

八、统计与高级

8. Statistics and Advanced Features

26. 获取统计信息

26. Get Statistics Information

GET /apps/{app_token}/tables/{table_id}/statistics
实测心法：比直接拉取记录更轻量。适合定期播报"昨日新增订单数"。
GET /apps/{app_token}/tables/{table_id}/statistics
Practical Tips: Lighter weight than directly pulling records. Suitable for regular reporting such as "number of new orders yesterday".

27. 自动化工作流触发

27. Trigger Automated Workflow

实测心法：API 写入记录同样能触发多维表格内部的"自动化助手"（无需额外权限）。
Practical Tips: Records written via API can also trigger the internal "Automation Assistant" of Bitable (no additional permissions required).

九、附件上传流程

9. Attachment Upload Process

上传文件到多维表格附件字段，需要两步：
第 1 步：上传文件获取 file_token
POST https://open.feishu.cn/open-apis/drive/v1/medias/upload_all
Content-Type: multipart/form-data

- file: 文件
- file_name: "invoice.jpg"
- parent_type: "bitable_file"
- parent_node: "{app_token}"
- size: 文件大小（字节）
第 2 步：将 file_token 写入附件字段
json
{
  "fields": {
    "附件字段名": [{"file_token": "返回的file_token"}]
  }
}
To upload files to Bitable attachment fields, two steps are required:
Step 1: Upload File to Get file_token
POST https://open.feishu.cn/open-apis/drive/v1/medias/upload_all
Content-Type: multipart/form-data

- file: File
- file_name: "invoice.jpg"
- parent_type: "bitable_file"
- parent_node: "{app_token}"
- size: File size (bytes)
Step 2: Write file_token to Attachment Field
json
{
  "fields": {
    "附件字段名": [{"file_token": "返回的file_token"}]
  }
}

十、错误处理

10. Error Handling

错误码含义解决方案
0成功—
1254043无权限在多维表格中添加应用
1254044app_token 无效检查多维表格 URL 中的 token
1254045table_id 无效调用列出数据表 API 重新获取
1254607字段值格式错误检查字段类型和值的格式是否匹配
99991663token 过期重新获取 tenant_access_token
99991400频率限制等待 1 秒后重试
Error CodeMeaningSolution
0Success—
1254043No PermissionAdd the app to Bitable
1254044Invalid app_tokenCheck the token in the Bitable URL
1254045Invalid table_idRe-obtain by calling the list data tables API
1254607Incorrect Field Value FormatCheck if the field type matches the value format
99991663Token ExpiredRe-obtain tenant_access_token
99991400Rate LimitRetry after 1 second