飞书开放平台 Server API 文档

主题

列出字段 ​

获取多维表格数据表中的的所有字段。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/bitable/v1/apps/:app_token/tables/:table_id/fields
HTTP MethodGET
接口频率限制20 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可base:field:read 获取字段信息 bitable:app 查看、评论、编辑和管理多维表格 bitable:app:readonly 查看、评论和导出多维表格

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

路径参数 ​

名称类型描述
app_tokenstring多维表格 App 的唯一标识。不同形态的多维表格，其 app_token 的获取方式不同： - 如果多维表格的 URL 以 ==feishu.cn/base== 开头，该多维表格的 app_token 是下图高亮部分： app_token.png
- 如果多维表格的 URL 以 ==feishu.cn/wiki== 开头，你需调用知识库相关获取知识空间节点信息接口获取多维表格的 app_token。当 obj_type 的值为 bitable 时，obj_token 字段的值才是多维表格的 app_token。
了解更多，参考多维表格 app_token 获取方式。
示例值："appbcbWCzen6D8dezhoCH2RpMAh"
table_idstring多维表格数据表的唯一标识。获取方式： - 你可通过多维表格 URL 获取 table_id，下图高亮部分即为当前数据表的 table_id - 也可通过列出数据表接口获取 table_id

示例值："tblsRc9GRRXKqhvW"

查询参数 ​

名称类型必填描述
view_idstring否多维表格中视图的唯一标识。获取方式：
- 在多维表格的 URL 地址栏中，view_id 是下图中高亮部分： view_id.png - 通过列出视图接口获取。暂时无法获取到嵌入到云文档中的多维表格的 view_id。
注意： 当 filter 参数 或 sort 参数不为空时，请求视为对数据表中的全部数据做条件过滤，指定的 view_id 会被忽略。
示例值：vewOVMEXPF
text_field_as_arrayboolean否控制字段描述 description 数据的返回格式，默认为 false。true 表示 description 将以数组形式返回，如： json `{ "description": [ { "text": "字段的描述", "type": "text" }` ] }
示例值：true
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
示例值：fldwJ4YrtB
page_sizeint否分页大小
示例值：10
默认值：20
数据校验规则：
- 最大值：100

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ has_moreboolean是否还有更多项
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
  └ totalint总数
  └ itemsapp.table.fieldForList\[\]字段信息
    └ field_namestring多维表格字段名称。名称中的首尾空格将会被去除。
    └ typeint多维表格字段类型
可选值有：
- 1: 文本 - 2: 数字 - 3: 单选 - 4: 多选 - 5: 日期 - 7: 复选框 - 11: 人员 - 13: 电话号码 - 15: 超链接 - 17: 附件 - 18: 关联 - 20: 公式 - 21: 双向关联 - 22: 地理位置 - 23: 群组 - 1001: 创建时间 - 1002: 最后更新时间 - 1003: 创建人 - 1004: 修改人 - 1005: 自动编号
    └ propertyapp.table.field.property字段属性，具体可参考字段编辑指南。
      └ optionsapp.table.field.property.option\[\]单选、多选字段的选项信息
        └ namestring选项名
        └ idstring选项 ID，创建时不允许指定 ID
        └ colorint选项颜色
      └ formatterstring数字、公式字段的显示格式
      └ date_formatterstring日期、创建时间、最后更新时间字段的显示格式
      └ auto_fillboolean日期字段中新纪录自动填写创建时间
      └ multipleboolean人员字段中允许添加多个成员，单向关联、双向关联中允许添加多个记录
      └ table_idstring单向关联、双向关联字段中关联的数据表的 ID
      └ table_namestring单向关联、双向关联字段中关联的数据表的名字
      └ back_field_namestring双向关联字段中关联的数据表中对应的双向关联字段的名字
      └ auto_serialapp.field.property.auto_serial自动编号类型
        └ typestring自动编号类型
可选值有：
- custom: 自定义编号 - auto_increment_number: 自增数字
        └ optionsapp.field.property.auto_serial.options\[\]自动编号规则列表
          └ typestring自动编号的可选规则项类型
可选值有：
- system_number: 自增数字位,value范围1-9 - fixed_text: 固定字符，最大长度：20 - created_time: 创建时间，支持格式 "yyyyMMdd"、"yyyyMM"、"yyyy"、"MMdd"、"MM"、"dd"
          └ valuestring与自动编号的可选规则项类型相对应的取值
      └ locationapp.field.property.location地理位置输入方式
        └ input_typestring地理位置输入限制
可选值有：
- only_mobile: 只允许移动端上传 - not_limit: 无限制
      └ formula_expressionstring公式字段的表达式
      └ allowed_edit_modesallowed_edit_modes字段支持的编辑模式
        └ manualboolean是否允许手动录入
        └ scanboolean是否允许移动端录入
      └ minnumber(float)进度、评分等字段的数据范围最小值
      └ maxnumber(float)进度、评分等字段的数据范围最大值
      └ range_customizeboolean进度等字段是否支持自定义范围
      └ currency_codestring货币币种
      └ ratingrating评分字段的相关设置
        └ symbolstring评分字段的符号展示
      └ typeapp.table.field.property.type设置公式字段的数据类型
注意：非所有多维表格都支持该能力。请参考获取多维表格元数据接口返回的formula_type 判断，当 formula_type 等于 2 时，表示需要设置该字段。
        └ data_typeint公式字段对应的数据类型
可选值有：
- 1: 文本（默认值）、条码 - 2: 数字（默认值）、进度、货币、评分 - 3: 单选 - 4: 多选 - 5: 日期 - 7: 复选框 - 11: 人员 - 13: 电话号码 - 15: 超链接 - 17: 附件 - 18: 单向关联 - 20: 公式 - 21: 双向关联 - 22: 地理位置 - 23: 群组 - 1001: 创建时间 - 1002: 最后更新时间 - 1003: 创建人 - 1004: 修改人 - 1005: 自动编号
        └ ui_propertyapp.table.field.property.type.ui_property公式数据属性
          └ currency_codestring货币币种
          └ formatterstring数字、公式字段的显示格式
          └ range_customizeboolean进度等字段是否支持自定义范围
          └ minnumber(float)进度、评分等字段的数据范围最小值
          └ maxnumber(float)进度、评分等字段的数据范围最大值
          └ date_formatterstring日期、创建时间、最后更新时间字段的显示格式
          └ ratingrating评分字段的相关设置
            └ symbolstring评分字段的符号展示
        └ ui_typestring公式字段在界面上的展示类型，例如进度字段是数字的一种展示形态。了解更多，参考字段编辑指南。
可选值有：
- Number: 数字 - Progress: 进度 - Currency: 货币 - Rating: 评分 - DateTime: 日期
      └ filter_infoapp.table.field.property.lookup_filter查找引用关系
        └ target_tablestring引用表格
        └ filter_infoapp.table.field.property.filter_info查找条件
          └ conjunctionstring多个筛选条件的关系
可选值有：
- and: 与 - or: 或
          └ conditionsapp.table.field.property.filter_info.condition\[\]筛选条件
            └ field_idstring用于过滤的字段唯一ID
            └ operatorstring过滤操作的类型
可选值有：
- is: 等于 - isNot: 不等于 - contains: 包含 - doesNotContain: 不包含 - isEmpty: 为空 - isNotEmpty: 不为空 - isGreater: 大于 - isGreaterEqual: 大于等于 - isLess: 小于 - isLessEqual: 小于等于
            └ valuestring筛选值
            └ condition_idstring过滤条件的唯一ID
            └ field_typeint用于过滤的字段类型
    └ descriptionunion字段的描述。可能是数组或字符串类型。由请求参数 text_field_as_array 决定。
    └ is_primaryboolean是否是索引列
    └ field_idstring多维表格字段 ID
    └ ui_typestring字段在界面上的展示类型，例如进度字段是数字的一种展示形态。了解更多，参考字段编辑指南。
可选值有：
- Text: 多行文本 - Barcode: 条码 - Number: 数字 - Progress: 进度 - Currency: 货币 - Rating: 评分 - SingleSelect: 单选 - MultiSelect: 多选 - DateTime: 日期 - Checkbox: 复选框 - User: 人员 - GroupChat: 群组 - Phone: 电话号码 - Url: 超链接 - Attachment: 附件 - SingleLink: 单向关联 - Formula: 公式 - DuplexLink: 双向关联 - Location: 地理位置 - CreatedTime: 创建时间 - ModifiedTime: 最后更新时间 - CreatedUser: 创建人 - ModifiedUser: 修改人 - AutoNumber: 自动编号
    └ is_hiddenboolean是否是隐藏字段

响应体示例 ​

json
{
    "code": 0,
    "data": {
        "has_more": false,
        "items": [
            {
                "field_id": "fldYWaldeW",
                "field_name": "多行文本",
                "is_primary": true,
                "property": null,
                "type": 1,
                "ui_type": "Text"
            },
            {
                "field_id": "fldctOury6",
                "field_name": "人员",
                "is_primary": false,
                "property": {
                    "multiple": true
                },
                "type": 11,
                "ui_type": "User"
            },
            {
                "field_id": "fldhAppMQX",
                "field_name": "单选",
                "is_primary": false,
                "property": {
                    "options": [
                        {
                            "color": 0,
                            "id": "opt5XoXIB0",
                            "name": "选项1"
                        }
                    ]
                },
                "type": 3,
                "ui_type": "SingleSelect"
            },
            {
                "field_id": "fldmeqmpVA",
                "field_name": "多选",
                "is_primary": false,
                "property": {
                    "options": [
                        {
                            "color": 0,
                            "id": "opt5XoXIB0",
                            "name": "选项1"
                        },
                        {
                            "color": 1,
                            "id": "optCvWAQfP",
                            "name": "选项2"
                        }
                    ]
                },
                "type": 4,
                "ui_type": "MultiSelect"
            },
            {
                "field_id": "fldXhExGte",
                "field_name": "群组",
                "is_primary": false,
                "property": {
                    "multiple": true
                },
                "type": 23,
                "ui_type": "GroupChat"
            },
            {
                "field_id": "fldUeGSYKO",
                "field_name": "日期",
                "is_primary": false,
                "property": {
                    "auto_fill": false,
                    "date_formatter": "yyyy/MM/dd"
                },
                "type": 5,
                "ui_type": "DateTime"
            },
            {
                "field_id": "fldQfY0kQq",
                "field_name": "附件",
                "is_primary": false,
                "property": null,
                "type": 17,
                "ui_type": "Attachment"
            },
            {
                "field_id": "fldPlbgodf",
                "field_name": "索引",
                "is_primary": false,
                "property": null,
                "type": 1,
                "ui_type": "Text"
            },
            {
                "field_id": "fldJU9aVuL",
                "field_name": "复选框",
                "is_primary": false,
                "property": null,
                "type": 7,
                "ui_type": "Checkbox"
            },
            {
                "field_id": "fldM2XDZx6",
                "field_name": "超链接",
                "is_primary": false,
                "property": null,
                "type": 15,
                "ui_type": "Url"
            },
            {
                "field_id": "fld6oN4ILr",
                "field_name": "电话号码",
                "is_primary": false,
                "property": null,
                "type": 13,
                "ui_type": "Phone"
            },
            {
                "field_id": "fldaQAG9aL",
                "field_name": "数据表",
                "is_primary": false,
                "property": {
                    "multiple": true,
                    "table_id": "tbltDA6cN3ou5r43",
                    "table_name": "数据表"
                },
                "type": 18,
                "ui_type": "SingleLink"
            },
            {
                "field_id": "fldNubyO2U",
                "field_name": "数据表 2",
                "is_primary": false,
                "property": {
                    "back_field_id": "fld0poyvPk",
                    "back_field_name": "数据表 6",
                    "multiple": true,
                    "table_id": "tbltDA6cN3ou5r43",
                    "table_name": "数据表"
                },
                "type": 21,
                "ui_type": "DuplexLink"
            },
            {
                "field_id": "fld2VT2n9r",
                "field_name": "地理位置",
                "is_primary": false,
                "property": {
                    "location": {
                        "input_type": "not_limit"
                    }
                },
                "type": 22,
                "ui_type": "Location"
            },
            {
                "field_id": "fldRITHRhg",
                "field_name": "公式",
                "is_primary": false,
                "property": {
                    "formatter": ""
                },
                "type": 20,
                "ui_type": "Formula"
            },
            {
                "field_id": "fldNM5yXpL",
                "field_name": "创建时间",
                "is_primary": false,
                "property": {
                    "date_formatter": "yyyy/MM/dd"
                },
                "type": 1001,
                "ui_type": "CreatedTime"
            },
            {
                "field_id": "fldhSAWlAT",
                "field_name": "创建人",
                "is_primary": false,
                "property": null,
                "type": 1003,
                "ui_type": "CreatedUser"
            },
            {
                "field_id": "fldksdalhG",
                "field_name": "修改人",
                "is_primary": false,
                "property": null,
                "type": 1004,
                "ui_type": "ModifiedUser"
            },
            {
                "field_id": "fldAXRUmB4",
                "field_name": "最后更新时间",
                "is_primary": false,
                "property": {
                    "date_formatter": "yyyy/MM/dd"
                },
                "type": 1002,
                "ui_type": "ModifiedTime"
            },
            {
                "field_id": "fldfujMlXf",
                "field_name": "条码",
                "is_primary": false,
                "property": {
                    "allowed_edit_modes": {
                        "manual": true,
                        "scan": true
                    }
                },
                "type": 1,
                "ui_type": "Barcode"
            },
            {
                "field_id": "fldiVqhh9r",
                "field_name": "查找引用",
                "is_primary": false,
                "property": null,
                "type": 19,
                "ui_type": "Lookup"
            },
            {
                "field_id": "fld4WsysqF",
                "field_name": "自动编号",
                "is_primary": false,
                "property": {
                    "auto_serial": {
                        "type": "auto_increment_number"
                    }
                },
                "type": 1005,
                "ui_type": "AutoNumber"
            },
            {
                "field_id": "fldMy4SfrI",
                "field_name": "货币",
                "is_primary": false,
                "property": {
                    "currency_code": "CNY",
                    "formatter": "0.00"
                },
                "type": 2,
                "ui_type": "Currency"
            },
            {
                "field_id": "fldj1QnQXO",
                "field_name": "进度",
                "is_primary": false,
                "property": {
                    "formatter": "0%",
                    "max": 1,
                    "min": 0,
                    "range_customize": false
                },
                "type": 2,
                "ui_type": "Progress"
            },
            {
                "field_id": "fldQhSzWbx",
                "field_name": "评分",
                "is_primary": false,
                "property": {
                    "formatter": "0",
                    "max": 5,
                    "min": 1,
                    "rating": {
                        "symbol": "star"
                    }
                },
                "type": 2,
                "ui_type": "Rating"
            }
        ],
        "page_token": "fldQhSzWbx",
        "total": 25
    },
    "msg": "success"
}

错误码 ​

HTTP状态码错误码描述排查建议
2001254000WrongRequestJson请求体错误
2001254001WrongRequestBody请求体错误
2001254002Fail导致报 1254002 错误码的场景较多，请参考以下建议排查： - 如果单次操作的内容变更较大，请尝试在单次操作中减少数据量 - 如果你并发调用了接口，请尝试控制请求间隔，稍后重试 - 如果在知识库（wiki）中创建多维表格，请检查你是否使用了知识库创建知识空间节点接口创建多维表格。在此场景下不能使用创建多维表格接口 - 请检查接口参数是否有误。例如，在分页查询多维表格时，传递了无效的 page_token，或传递了错误的数据表的 table_id - 如果该报错偶尔发生，可能是服务器超时或不稳定，请重试解决
2001254003WrongBaseTokenapp_token 错误。app_token 是多维表格 App 的唯一标识。不同形态的多维表格，其 app_token 的获取方式不同： - 如果多维表格的 URL 以 ==feishu.cn/base== 开头，该多维表格的 app_token 是下图高亮部分： app_token.png - 如果多维表格的 URL 以 ==feishu.cn/wiki== 开头，你需调用知识库相关获取知识空间节点信息接口获取多维表格的 app_token。当 obj_type 的值为 bitable 时，obj_token 字段的值才是多维表格的 app_token。 了解更多，参考多维表格 app_token 获取方式。
2001254004WrongTableIdtable_id 错误。table_id 是多维表格数据表的唯一标识。获取方式： - 你可通过多维表格 URL 获取 table_id，下图高亮部分即为当前数据表的 table_id - 也可通过列出数据表接口获取 table_id
2001254005WrongViewIdview_id 错误。view_id 是多维表格中视图的唯一标识。获取方式： - 在多维表格的 URL 地址栏中，view_id 是下图中高亮部分： view_id.png - 通过列出视图接口获取。暂时无法获取到嵌入到云文档中的多维表格的 view_id。 注意： 当 filter 参数 或 sort 参数不为空时，请求视为对数据表中的全部数据做条件过滤，指定的 view_id 会被忽略。
2001254006WrongRecordIdrecord_id 错误。record_id 是数据表中一条记录的唯一标识。通过查询记录接口获取
2001254007EmptyValue空值
2001254008EmptyView空视图
2001254009WrongFieldIdfield_id 错误。field_id 是数据表中一个字段的唯一标识。通过列出字段接口获取
2001254010ReqConvError请求错误
2001254012NotSupportFieldOrView不支持的字段或视图。注意数据表的初始索引字段仅支持以下类型： - 1：多行文本 - 2：数字 - 5：日期 - 13：电话号码 - 15：超链接 - 20：公式 - 22：地理位置
2001254013TableNameDuplicated表名重复
2001254014FieldNameDuplicated字段名重复
2001254015FieldTypeValueNotMatch字段类型和值不匹配
2001254030TooLargeResponse响应体过大
4001254036Base is copying, please try again later.复制多维表格为异步操作，该错误码表示当前多维表格仍在复制中，在复制期间无法操作当前多维表格。需要等待复制完成后再操作
2001254040BaseTokenNotFoundapp_token 不存在。不同形态的多维表格，其 app_token 的获取方式不同： - 如果多维表格的 URL 以 ==feishu.cn/base== 开头，该多维表格的 app_token 是下图高亮部分： app_token.png - 如果多维表格的 URL 以 ==feishu.cn/wiki== 开头，你需调用知识库相关获取知识空间节点信息接口获取多维表格的 app_token。当 obj_type 的值为 bitable 时，obj_token 字段的值才是多维表格的 app_token。 了解更多，参考多维表格 app_token 获取方式。
2001254041TableIdNotFoundtable_id 不存在。获取方式： - 你可通过多维表格 URL 获取 table_id，下图高亮部分即为当前数据表的 table_id - 也可通过列出数据表接口获取 table_id
2001254042ViewIdNotFoundview_id 不存在。获取方式： - 在多维表格的 URL 地址栏中，view_id 是下图中高亮部分： view_id.png - 通过列出视图接口获取。暂时无法获取到嵌入到云文档中的多维表格的 view_id。 注意： 当 filter 参数 或 sort 参数不为空时，请求视为对数据表中的全部数据做条件过滤，指定的 view_id 会被忽略。
2001254043RecordIdNotFoundrecord_id 不存在。record_id 是数据表中一条记录的唯一标识。请通过查询记录接口获取
2001254044FieldIdNotFoundfield_id 不存在。field_id 是数据表中一个字段的唯一标识。通过列出字段接口获取
2001254060TextFieldConvFail多行文本字段错误
2001254061NumberFieldConvFail数字字段错误
2001254062SingleSelectFieldConvFail单选字段错误
2001254063MultiSelectFieldConvFail多选字段错误
2001254064DatetimeFieldConvFail日期字段错误
2001254065CheckboxFieldConvFail复选框字段错误
2001254066UserFieldConvFail人员字段有误。原因可能是： - user_id_type 参数指定的 ID 类型与传入的 ID 类型不匹配 - 传入了不识别的类型或结构，目前只支持填写 id 参数，且需要传入数组 - 跨应用传入了 open_id。如果跨应用传入 ID，建议使用 user_id。不同应用获取的 open_id 不能交叉使用 - 若想对人员字段传空，可传 null
2001254067LinkFieldConvFail关联字段错误
2001254070ActionValidateFailedAction验证失败
2001254100TableExceedLimit数据表或仪表盘数量超限。每个多维表格中，数据表加仪表盘的数量最多为 100 个
2001254101ViewExceedLimit视图数量超限, 限制200个
2001254102FileExceedLimit文件数量超限
2001254103RecordExceedLimit记录数量超限, 限制20,000条
2001254104RecordAddOnceExceedLimit单次添加记录数量超限, 单次调用最多更新 1,000 条记录
2001254105ColumnExceedLimit字段数量超限
2001254130TooLargeCell格子内容过大
2001254290TooManyRequest请求过快，稍后重试
2001254291Write conflict在同一个数据表中，并发调用了读写接口或请求过快，出现冲突。请参考以下建议解决： - 确保没有并发调用多维表格读写相关接口 - 若操作量较大，建议在接口与接口之间增加 0.5 或 1 秒的延迟，也可在报错中增加重试逻辑，确保业务的稳定性 - 对于写接口，可以将接口中的查询参数 ignore_consistency_check 设置为 true，表示在读写操作时，暂时忽略一致性检查，以提高性能
2001254301OperationTypeError多维表格未开启高级权限或不支持开启高级权限
4031254302Permission denied.调用身份缺少多维表格的高级权限。你需给予调用身份数据表的 可管理 权限或多维表格的 可管理 等权限，再重新调用。具体步骤如下所示： - 对用户授予高级权限，你可在 多维表格高级权限设置 中添加用户，为用户开通足够权限；或在多维表格页面右上方 分享 入口为当前用户添加可管理权限。详情参考飞书帮助中心文档使用多维表格高级权限。 - 对应用授予高级权限，你需通过多维表格页面右上方 「...」 -> 「...更多」 ->「添加文档应用」 入口为应用添加可管理权限。 image.png 注意： 在 添加文档应用 前，你需确保目标应用至少开通了一个多维表格的 API 权限。否则你将无法在文档应用窗口搜索到目标应用。 - 你也可以在 多维表格高级权限设置 中添加用户或一个包含应用的群组，给予这个群自定义的读写等权限。
2001255001InternalError内部错误，请联系技术支持
2001255002RpcError内部错误，请联系技术支持
2001255003MarshalError序列化错误，请联系技术支持
2001255004UmMarshalError反序列化错误，请联系技术支持
2001255005ConvError内部错误，请联系技术支持
5001255040Request timed out, please try again later请求超时，进行重试
4001254607Data not ready, please try again later该报错一般是由于前置操作未执行完成，或本次操作数据太大，服务器计算超时导致。遇到该错误码时，建议等待一段时间后重试。通常有以下几种原因： - 编辑操作频繁：开发者对多维表格的编辑操作非常频繁。可能会导致由于等待前置操作处理完成耗时过长而超时的情况。多维表格底层对数据表的处理基于版本维度的串行方式，不支持并发。因此，并发请求时容易出现此类错误，不建议开发者对单个数据表进行并发请求。 - 批量操作负载重：开发者在多维表格中进行批量新增、删除等操作时，如果数据表的数据量非常大，可能会导致单次请求耗时过长，最终导致请求超时。建议开发者适当降低批量请求的 page_size 以减少请求耗时。 - 资源分配与计算开销：资源分配是基于单文档维度的，如果读接口涉及公式计算、排序等计算逻辑，会占用较多资源。例如，并发读取一个文档下的多个数据表也可能导致该文档阻塞。

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有