接入指南
多维表格(Bitable)是飞书云文档下的一个产品。它可以是一个表格,也可以是无数个应用。
1.形态
一篇多维表格可以理解成是一个应用(app),标记该应用的唯一标识叫 apptoken;
每篇多维表格是由有多个数据表(table)组成的,标记该数据表的唯一标识叫 tableid;
作为一个应用它会有多种形态存在;
可以作为一个独立应用存在,也可以作为一个模块(block)与飞书文档、飞书表格结合在一起。
飞书云文档中 | 飞书文档中 | 飞书表格中 |
---|---|---|
Bitable app | Bitable doc block | Bitable sheet block |
即在"飞书云文档"中新建的多维表格 | 即在"飞书文档"中插入的多维表格 | 即在"飞书表格"中新建的多维表格 |
URL 以 feishu.cn/base 开头 | URL 以 feishu.cn/docs、feishu.cn/docx 开头 | URL 以 feishu.cn/sheets 开头 |
支持 | 支持 | 支持 |
![]() | ![]() | ![]() |
*通过 API 在飞书表格(Sheets)中新建数据表暂时无法在页面看到,后续会支持;
2.内容
目前开放多维表格在App、数据表、视图、字段、记录、高级权限设置和高级权限协作者 7 种内容的 API 。
记录可以狭义的理解为表格行;
字段可以狭义的理解为表格的列;
记录* | 字段 | 视图 | 数据表 | App | 权限 | 高级权限设置 | 高级权限协作者 |
---|---|---|---|---|---|---|---|
列出记录 记录筛选开发指南 检索记录 新增记录 新增多记录 更新记录 更新多记录 删除记录 删除多记录 | 列出字段 新增字段 更新字段 删除字段 | 列出视图 新增视图 删除视图 | 列出数据表 新增数据表 新增多数据表 删除数据表 删除多数据表 | 获取元数据 更新多维表格元数据 新建多维表格 复制多维表格 删除多维表格 | 增加权限 移除权限 更新权限 列出列表 转移拥有者 判断是否有权限 更新文档设置 | 列出自定义权限 新增自定义权限 删除自定义权限 更新自定义权限 | 列出协作者 新增协作者 删除协作者 |
最多 20000条/记录 | 最多150个/字段 | 最多200个/视图 | 最多100个/表格 | -- | -- | 最多30条/自定义权限 | 最多200个/自定义权限协作者 |
注意:列出记录一次最多支持列出 500 条;
操作多条记录(限制在 500 条/次以下)的结果是全部成功或者全部失败,不存在部分结果。
同一时刻,对同一篇多维表格最好只请求一次 API 写操作。
3.鉴权
-
在使用
tenant_access_token
前,请确保你的应用已经是文档的所有者或者协作者,否则会调用失败。
-
多维表格大部分接口都支持通过
user_access_token
和
tenant_access_token
两种身份进行调用。但仍然有部分接口只支持其中一种身份,请开发者在调用前,仔细阅读对应接口的说明文档。
-
使用
tenant_access_token
前,请确保你所使用的应用在云文档的协作者列表里。现阶段,你可以通过使用
tenant_access_token
来创建一篇多维表格,再使用
tenant_access_token
来进行进一步的操作。
user_access_token | tenant_access_token |
---|---|
用户身份鉴权 token 有效期为7200秒 当该token被刷新之后,老的 token 随即失效 | 应用身份鉴权 token 有效时间2小时 当token有效期<30分,可刷新得到新token 在2小时之内,新老token同时有效 |
获取用户身份访问凭证 | 获取应用身份访问凭证 |
适合小程序、网页应用等场景 | 适合纯后台服务等场景 |
4.限制
QPS 限制
- 每个接口都有接口调用的频率限制,可参考频控策略。
- 对于接口的批量操作,单次最高 500 条记录,且响应状态是全部成功或者失败,不存在部分结果。
接口报错
当请求不符合某些特定条件时会报错,如果因为部分参数不符合要求而导致报错,意味着当次请求所有的内容提交都失败了,不会对线上的数据造成影响。具体可参考:服务端错误码说明
5.字段类型
接口类型 | 支持 | 不支持 |
---|---|---|
列出记录 | 全支持 | -- |
新增记录 更新记录 | 多行文本、单选、多选、日期、人员、附件、复选框、超链接、数字、单向关联、电话号码、地理位置 | 双向关联 公式 查找引用 |
列出字段 | 全支持 | -- |
新增字段 更新字段 | 多行文本、单选、多选、日期、数字、人员、附件、单向关联、双向关联、复选框、超链接、公式(不支持设置公式表达式)、创建人、修改人、创建时间、最后更新时间、自动编号、电话号码、地理位置 | 查找引用 |
6.参数说明
API 地址:https://open.feishu.cn/open-apis/bitable/v1/apps/:app_token/tables/:table_id/records/:record_id
app_token
Bitable app
- 在飞书云文档中打开一篇多维表格,其 URL 中 app_token 是下图框住部分;
Bitable doc block
- 调用获取文档所有块,在返回结果中检索,其中 bitable.token 字段的值 AW3Qbtr2cakCnesXzXVbbsrIcVT_tblkIYhz52o6G5nx是用 _ 隔开的 app_token 和 table_id;
{
"bitable": {
"token": "AW3Qbtr2cakCnesXzXVbbsrIcVT_tblkIYhz52o6G5nx"
},
"block_id": "Mgeadqo4CoeoOGxI7Lgb4GNicEd",
"block_type": 18,
"parent_id": "YUqpdO2eLo7xJdxy5RQbuQBdctf"
}
Bitable sheet block
- 调用获取表格元数据,在返回结果中检索,其中 blockType 的值为 BITABLE_BLOCK 时,blockToken 字段的值AW3Qbtr2cakCnesXzXVbbsrIcVT_tblkIYhz52o6G5nx是用 _ 隔开的 app_token 和 table_id;
{
"blockInfo": {
"blockToken": "AW3Qbtr2cakCnesXzXVbbsrIcVT_tblkIYhz52o6G5nx",
"blockType": "BITABLE_BLOCK"
},
"columnCount": 0,
"frozenColCount": 0,
"frozenRowCount": 0,
"index": 0,
"rowCount": 0,
"sheetId": "***",
"title": "*** "
}
table_id
Bitable app
- 在 Bitable app 中打开一篇多维表格,其 URL 中 table_id 是下图中框住部分;
- 对于其它场景的多维表格,需要通过列出数据表接口获取;
view_id
- 打开任意一篇多维表格,其 URL 中 view_id 是下图中框住部分;
- 或者通过列出视图接口获取。暂时无法获取到 Bitable doc block 中表格的 view_id;
record_id
- 需要通过列出记录接口获取;
field_id
- 需要通过列出字段接口获取;
role_id
- 需要通过列出自定义权限接口获取;
member_id
- 需要通过列出协作者接口获取;