# 接入指南
多维表格（Base）是飞书云文档下的一个产品。它可以是一个表格，也可以是无数个应用。warning
本文档已废弃，不再维护。你可参考[多维表格概述](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/bitable-overview)了解本文内容。
## 形态
一篇多维表格可以理解成是一个应用（app），标记该应用的唯一标识叫 app_token
每篇多维表格是由多个数据表（table）组成的，标记该数据表的唯一标识叫 table_id
作为一个应用它会有多种形态存在；
可以作为一个独立应用存在，也可以作为一个模块（block）与飞书文档、飞书表格结合在一起。
| 飞书云文档中 | 飞书文档中 | 飞书表格中 |
| --------- | --------------- | ------- | ----------- | --------- |
| Base app | Base doc block | Base sheet block |
| 即在"**飞书云文档**"中新建的多维表格 | 即在"**飞书文档**"中插入的多维表格 | 即在"**飞书表格**"中新建的多维表格 |
| URL 以 ==**feishu.cn/base**== 开头 | URL 以 ==**feishu.cn/docs**==、==**feishu.cn/docx**== 开头 | URL 以 ==**feishu.cn/sheets**== 开头 |
| 支持 | 支持 | 支持 |
||  ||
> *通过 API 在飞书表格（Sheets）中新建数据表暂时无法在页面看到，后续会支持；
## 内容
目前开放多维表格在App、数据表、视图、字段、记录、高级权限设置和高级权限协作者 7 种内容的 API 。
记录可以狭义的理解为表格行；
字段可以狭义的理解为表格的列；
| 记录* | 字段 | 视图 | 数据表 | App | 权限 | 高级权限设置 |高级权限协作者 |
| --------- | --------------- | ------- | -------- | ------- |-------| ----- |-----|
|[列出记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-record/list)
[记录筛选开发指南](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/filter)
[检索记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-record/get)
[新增记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-record/create)
[新增多记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-record/batch_create)
[更新记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-record/update)
[更新多记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-record/batch_update)
[删除记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-record/delete)
[删除多记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-record/batch_delete)| [列出字段](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-field/list)
[新增字段](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-field/create)
[更新字段](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-field/update)
[删除字段](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-field/delete) | [列出视图](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-view/list)
[新增视图](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-view/create)
[删除视图](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-view/delete) | [列出数据表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table/list)
[新增数据表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table/create)
[新增多数据表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table/batch_create)
[删除数据表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table/delete)
[删除多数据表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table/batch_delete)| [获取元数据](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app/get)
[更新多维表格元数据](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app/update)
[新建多维表格](https://open.feishu.cn/document/ukTMukTMukTM/uQTNzUjL0UzM14CN1MTN)
[复制多维表格](https://open.feishu.cn/document/ukTMukTMukTM/uYTNzUjL2UzM14iN1MTN)
[删除多维表格]([删除文件](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/file/delete))
|[增加权限](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/permission-member/create)
[移除权限](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/permission-member/delete)
[更新权限](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/permission-member/update)
[列出列表](https://open.feishu.cn/document/ukTMukTMukTM/uATN3UjLwUzN14CM1cTN)
[转移拥有者](https://open.feishu.cn/document/ukTMukTMukTM/uQzNzUjL0czM14CN3MTN)
[判断是否有权限](https://open.feishu.cn/document/ukTMukTMukTM/uYzN3UjL2czN14iN3cTN)
[更新文档设置](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/permission-public/patch) | [列出自定义权限](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-role/list)
[新增自定义权限](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-role/create)
[删除自定义权限](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-role/delete)
[更新自定义权限](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-role/update)
| [列出协作者](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-role-member/list)
[新增协作者](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-role-member/create)
[删除协作者](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-role-member/delete)|
| 最多 20000条/记录 | 最多150个/字段 | 最多200个/视图 | 最多100个/表格 | -- | -- | 最多30条/自定义权限 | 最多200个/自定义权限协作者 |
> 注意：列出记录一次最多支持列出 500 条；
>
> 操作多条记录（限制在 500 条/次以下）的结果是全部成功或者全部失败，不存在部分结果。
>
> 同一时刻，对同一篇多维表格最好只请求一次 API 写操作。
## 鉴权
**注意事项**：- 在使用 `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 最大有效期为2小时左右
当该token被刷新之后，老的 token 随即失效|**应用身份鉴权**
token 有效时间2小时
当token有效期<30分，可刷新得到新token
在2小时之内，新老token同时有效|
| [获取用户身份访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM) | [获取应用身份访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)|
| 适合小程序、网页应用等场景 | 适合纯后台服务等场景 |
## 限制
### QPS 限制
- 每个接口都有接口调用的频率限制，可参考[频控策略](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)。
- 对于接口的批量操作，单次最高 500 条记录，且响应状态是全部成功或者失败，不存在部分结果。
### 接口报错
当请求不符合某些特定条件时会报错，如果因为部分参数不符合要求而导致报错，意味着当次请求所有的内容提交都失败了，不会对线上的数据造成影响。具体可参考：[服务端错误码说明](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN)
## 字段类型
| 接口类型 | 支持 | 不支持 |
| --------- | --------------- | ------- |
|[列出记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-record/list)| 全支持 | -- |
| [新增记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-record/create)
[更新记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-record/update)| 多行文本、条码、单选、多选、日期、人员、附件、复选框、超链接、数字、单向关联、双向关联、电话号码、地理位置| 公式
查找引用 |
| [列出字段](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-field/list) | 全支持 | -- |
| [新增字段](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-field/create)
[更新字段](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-field/update) |多行文本、条码、单选、多选、日期、数字、人员、附件、单向关联、双向关联、复选框、超链接、公式（不支持设置公式表达式）、创建人、修改人、创建时间、最后更新时间、自动编号、电话号码、地理位置 | 查找引用 |
## 参数说明
**API 地址**：
https://open.feishu.cn/open-apis/bitable/v1/apps/:app_token/tables/:table_id/records/:record_id
### app_token
#### **多维表格**
在飞书云空间中打开一篇多维表格，URL 以 ==**feishu.cn/base**== 开头，该多维表格的 app_token 是下图框住部分：
#### **知识库下的多维表格**
知识库中的多维表格，URL 以 ==**feishu.cn/wiki**== 开头。此时，你需调用知识库相关[获取知识空间节点信息](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/wiki-v2/space/get_node)接口获取多维表格的 app_token。
如下返回示例，当 obj_type 的值为 bitable 时，obj_token 字段的值==AW3Qbtr2cakCnesXzXVbbsrIcVT==是多维表格的 app_token：
```json
{
"node":{
"space_id":"6946843325487912356",
"node_token":"wikcnKQ1k3p******8Vabcef",
"obj_token":"AW3Qbtr2cakCnesXzXVbbsrIcVT", // 多维表格的 app_token
"obj_type":"bitable",
"parent_node_token":"wikcnKQ1k3p******8Vabcef",
"node_type":"origin",
"origin_node_token":"wikcnKQ1k3p******8Vabcef",
"origin_space_id":"6946843325487912356",
"has_child":false,
"title":"标题",
"obj_create_time":"1642402428",
"obj_edit_time":"1642402428",
"node_create_time":"1642402428",
"creator":"ou_xxxxx",
"owner":"ou_xxxxx"
}
}
```
#### **云文档嵌入多维表格**
- 调用[获取文档所有块](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block/list)，在返回结果中检索，其中 bitable.token 字段的值 ==AW3Qbtr2cakCnesXzXVbbsrIcVT_tblkIYhz52o6G5nx==是用 _ 隔开的 app_token 和 table_id；
-
```json
{
"bitable": {
"token": "AW3Qbtr2cakCnesXzXVbbsrIcVT_tblkIYhz52o6G5nx"
},
"block_id": "Mgeadqo4CoeoOGxI7Lgb4GNicEd",
"block_type": 18,
"parent_id": "YUqpdO2eLo7xJdxy5RQbuQBdctf"
}
```
#### **电子表格嵌入多维表格**
- 调用[获取表格元数据](https://open.feishu.cn/document/ukTMukTMukTM/uETMzUjLxEzM14SMxMTN)，在返回结果中检索，其中 blockType 的值为 ==BITABLE_BLOCK== 时，blockToken 字段的值==AW3Qbtr2cakCnesXzXVbbsrIcVT_tblkIYhz52o6G5nx==是用 _ 隔开的 app_token 和 table_id；
-
```json
{
"blockInfo": {
"blockToken": "AW3Qbtr2cakCnesXzXVbbsrIcVT_tblkIYhz52o6G5nx",
"blockType": "BITABLE_BLOCK"
},
"columnCount": 0,
"frozenColCount": 0,
"frozenRowCount": 0,
"index": 0,
"rowCount": 0,
"sheetId": "***",
"title": "*** "
}
```
### table_id
#### **多维表格**
- 打开一篇多维表格，其 URL 中 table_id 是下图中框住部分：
- 对于其它场景的多维表格，需要通过[列出数据表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table/list)接口获取
### view_id
- 打开任意一篇多维表格，其 URL 中 view_id 是下图中框住部分：
- 或者通过[列出视图](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-view/list)接口获取。暂时无法获取到嵌入到云中多维表格的 view_id
### record_id
- 需要通过[列出记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-record/list)接口获取
### field_id
- 需要通过[列出字段](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-field/list)接口获取
### role_id
- 需要通过[列出自定义权限](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-role/list)接口获取
### member_id
- 需要通过[列出协作者](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-role-member/list)接口获取