飞书API（5）：查看多维表 28 种数据类型的数据结构

2024-04-21 23:52
文章标签 查看 数据结构 数据类型 api 28 多维 飞书

本文主要是介绍飞书API（5）：查看多维表 28 种数据类型的数据结构，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

一、引入

前面我们用于测试的数据集其实都是比较常用的数据，比如说文本、数字、单选等，但飞书多维表并不仅仅只有这些数据，截止发文，飞书多维表应用上支持28种数据类型，在数据层面飞书官方只提供了23种数据类型，5种合并了，如下表格：多行文本、条码、Email邮箱三种数据类型都合并到编码 1，都用文本表示，数字、进度、货币、评分都合并到编码 2，都用数字表示。

数据类型编码数据类型中文描述数据类型对应英文描述
1多行文本、条码Text,Barcode
1Email邮箱Email
2数字、进度、货币、评分Number,Progress,Currency,Rating
3单选SingleSelect
4多选MultiSelect
5日期DateTime
7复选框Checkbox
11人员User
13电话号码Phone
15超链接Url
17附件Attachment
18单向关联SingleLink
19查找引用Lookup
20公式Formula
21双向关联DuplexLink
22地理位置Location
23群组GroupChat
24流程Stage
1001创建时间CreatedTime
1002最后更新时间ModifiedTime
1003创建人CreatedUser
1004修改人ModifiedUser
1005自动编号AutoNumber
3001按钮Button

本文就来认识一下这些数据类型读取到的数据都长什么样，以便后期的数据处理。

二、了解字段类型数据结构

由于类型太多，这里分类来查看，先简单分为几类：

  • 文本类：1（多行文本、条码、Email）、3（单选）、4（多选）、13（电话号码）、1005（自动编号）
  • 数字类：2（数字、进度、货币、评分）
  • 日期类：5（日期）、1001（创建时间）、1002（最后更新时间）
  • 人员和群组类：11（人员）、23（群组）、1003（创建人）、1004（修改人）
  • 关联和引用类：15（超链接）、17（附件）、18（单向关联）、19（查找引用）、21（双向关联）
  • 其他：7（复选框）、20（公式）、22（地理位置）、24（流程）、3001（按钮）

飞书官方也有提供一个数据结构文档，可以查看字段参数的说明，不过缺少一些数据示例的展示，可以结合使用。

2.1 文本类

文本类：1（多行文本、条码、Email）、3（单选）、4（多选）、13（电话号码）、1005（自动编号）

新建一个数据表，按上一行的数据类型创建字段，如下图，然后填充一些测试值。
为了方便查看读取的数据，建议列名和数据类型保持一致，避免后续需要来回核对某个字段的数据类型，而且不容易出错。
image.png

接下来使用 API 调试台来读取表单数据看看各个数据类型返回的数据结构。
打开 API 调试台，在左侧的 API 列表依次打开：云文档>多维表格>记录，找到查询记录，打开该 API。

温馨提示：
1、不清楚怎么查找参考《飞书API（2）：通过 Python 读取多维表数据》中的“1.1 获取 demo”小节；
2、前面已经把文档授权给应用，所以应用可以直接读取。如果是新建的文档，需要授权，参考《飞书API（1）：读取飞书多维表数据》中的“3、创建多维表，并设置应用操作多维表的权限”小节。

我的表单链接为：

https://xxx.feishu.cn/base/PtRdbPjCFa5Og5sry0lcD1yPnKg?table=tblKPtVpk0xLDmAD&view=vew4gNVM5T

其中，“PtRdbPjCFa5Og5sry0lcD1yPnKg”为“app_token”，“tblKPtVpk0xLDmAD”为“table_id”。
分别将参数填写到路径参数。
image.png

注意请求体中的内容把它清楚掉，保留一对大括号即可：{}。
image.png

配置好了，发起请求：点击开始调试。可以看到返回的数据结构如下：
image.png

简单介绍一下整一个响应体的数据结构，将整个结构抽象一下，基本如下。

  • 最外层是三组键值对构成，键分别是“code”、“data”和“msg”。当“code”为 0 时表示请求成功，如果请求失败时，则没有“data”键。
  • “data”的值又嵌套三组键值对，键分别是“has_more”、“items”和“total”。“has_more”用于判断是否有翻页，如果有，该值为“true”，并在同级下会多一组键值对，键是“page_token”，该参数的值是用于获取下一页的标识（可将查询参数中的“page_size”设置小一些，重新发起请求查看结果）。
  • “items”的值是一个列表结构，每个元素都是一条数据记录，每条数据记录有两组键值对，键分别是“fields”和“record_id”。前者存放真实的数据，以键值对“字段名:值”的形式记录数据，后者是每一行的唯一标识。
{"code": 0,"data": {"has_more": false,"items": [{"fields": {字段名:值,字段名:值},"record_id": "recuax3DpzWCW4"},{"fields": {字段名:值,字段名:值},"record_id": "recuax3DpzdSXv"},{"fields": {字段名:值,字段名:值},"record_id": "recuax3Dpz1dTA"}],"total": 10},"msg": "success"
}

了解完大致结构，接下来单独抽取“fields”，查看每个字段返回的值。

{"多行文本": [{"text": "我是文本1","type": "text"}],"条码": [{"text": "475495794","type": "text"}],"Email": [{"link": "mailto:ceshi@ceshi.com","text": "ceshi@ceshi.com","type": "url"}],"自动编号": "1""电话号码": "13549857286","单选": "单选11","多选": ["多选11","多选22"],
}

结合原多维表数据可以看出：

  • “多行文本”、“条码”和“Email”的字段值是使用一个列表包裹，首个元素值的“text”键的值才是多维表上用户输入的信息，只不过“Email”的首个元素多了一个“link”键；
  • “自动编号”、“电话号码”和“单选”的字段值都是一个字符串，记录的都是用户输入的信息；
  • “多选”的字段值是一个列表，里面每个元素都是用户输入的信息。

image.png

2.2 数字类

数字类：2（数字、进度、货币、评分）

用和《1.1 文本类》类似的方法查看数字类的返回信息。
新建表单数据如下：
image.png

调接口返回数据如下：

{"数字-小数": 1.33,"数字-整数": 1,"评分": 5,"货币": 5.22,"进度": 0.7
}

结合多维表数据和返回数据可以看出：“数字”、“进度”、“货币”和“评分”的字段值都是一个数值，记录的都是用户输入的信息。

2.3 日期类

日期类：5（日期）、1001（创建时间）、1002（最后更新时间）

用和《1.1 文本类》类似的方法查看数字类的返回信息。
新建表单数据如下：
image.png

调接口返回数据如下：

{"创建时间": 1713683411000,"日期": 1711900800000,"日期-时间": 1712301240000,"最后更新时间": 1713683658000
}

结合多维表数据和返回数据可以看出：“日期”、“创建时间”和“最后更新时间”的字段值都是一个毫秒级别的时间戳，需要转换为时间格式才能获取到用户输入的信息。

2.4 人员和群组

人员和群组类：11（人员）、23（群组）、1003（创建人）、1004（修改人）

用和《1.1 文本类》类似的方法查看数字类的返回信息。
新建表单数据如下：
image.png

调接口返回数据如下：

{"人员": [{"email": "","en_name": "user1","id": "ou_4007a8a82cc6e0874524edda12ce94b1","name": "user1"}],"人员-允许多个": [{"email": "","en_name": "user2","id": "ou_ff61f5c95f505aa9a9e724a43f81e8c9","name": "user2"},{"email": "","en_name": "user1","id": "ou_4007a8a82cc6e0874524edda12ce94b1","name": "user1"}],"修改人": [{"email": "","en_name": "user1","id": "ou_4007a8a82cc6e0874524edda12ce94b1","name": "user1"}],"创建人": [{"email": "","en_name": "user1","id": "ou_4007a8a82cc6e0874524edda12ce94b1","name": "user1"}],"序号": "1","群组": [{"avatar_url": "https://s1-imfile.feishucdn.com/static-resource/avatar/default-avatar_9fb72564-d52a-49b0-9de8-f79071a02286_96.webp","id": "oc_8b6ac124bd908dce5c5facfb41c4dd4e","name": "(无主题)"}],"群组-允许多个": [{"avatar_url": "https://s1-imfile.feishucdn.com/static-resource/avatar/default-avatar_9fb72564-d52a-49b0-9de8-f79071a02286_96.webp","id": "oc_8b6ac124bd908dce5c5facfb41c4dd4e","name": "(无主题)"},{"avatar_url": "https://s3-imfile.feishucdn.com/static-resource/avatar/default-avatar_44ae0ca3-e140-494b-956f-78091e348435_96.webp","id": "oc_da64ef01c4c85a02e4f1198a45d57e85","name": "二人组"}]
}

结合多维表数据和返回数据可以看出：

  • “人员”、“创建人”和“修改人”的字段值都是一个列表，列表的每个元素记录每个人员的“email”、“en_name”、“id”和“name”，其中“en_name”为英文名字，“name”为昵称，“id”是用户唯一标识，可用于飞书机器人在飞书群聊中 @ 对应的用户。不同点在于“人员”支持多个值，而“创建人”和“修改人”只能支持一个值。当“人员”拥有多个值时，每个用户的信息都记录在一个列表的元素；
  • “群组”的字段值结构和“人员”的差不多，只是记录的信息不一样，“name”记录群名，“avatar_url”是群的头像。

2.5 关联和引用

关联和引用类：15（超链接）、17（附件）、18（单向关联）、19（查找引用）、21（双向关联）

用和《1.1 文本类》类似的方法查看数字类的返回信息。
新建表单数据如下：
image.png

相关值的配置：

  • 单向关联：关联《1.1 文本类》的数据表，“单向关联-允许多记录”则是在下图的“允许添加多个记录”前面打勾。

image.png

  • 双向关联：关联《1.1 文本类》的数据表，“双向关联-允许多记录”则是在下图的“允许添加多个记录”前面打勾。

image.png

  • 查找引用：关联《1.1 文本类》的数据表，根据“自动编号”字段进行匹配，然后返回列“多行文本”的“原值”。

image.png

调接口返回数据如下：

{"单向关联": {"link_record_ids": ["recuax3DpzWCW4"]},"单向关联-允许多记录": {"link_record_ids": ["recuax3DpzWCW4","recuax3DpzdSXv"]},"双向关联": {"link_record_ids": ["recuax3DpzWCW4"]},"双向关联-允许多记录": {"link_record_ids": ["recuax3DpzWCW4","recuax3DpzdSXv"]},"查找引用": {"type": 1,"value": [{"text": "我是文本1","type": "text"}]},"自动编号": "1","超链接": {"link": "https://vl933ry4wy.feishu.cn/base/PtRdbPjCFa5Og5sry0lcD1yPnKg?table=tbl3cvd797CmyEnN&view=vewdFnsmWn","text": "测试数据类型"},"附件": [{"file_token": "Cm3Vb8fe4oLPw4xgChZcOa2Mnhe","name": "image.png","size": 956,"tmp_url": "https://open.feishu.cn/open-apis/drive/v1/medias/batch_get_tmp_download_url?file_tokens=Cm3Vb8fe4oLPw4xgChZcOa2Mnhe","type": "image/png","url": "https://open.feishu.cn/open-apis/drive/v1/medias/Cm3Vb8fe4oLPw4xgChZcOa2Mnhe/download"},{"file_token": "UgSYbwu7oo4XNrxsikVchUPxndg","name": "image.png","size": 2187,"tmp_url": "https://open.feishu.cn/open-apis/drive/v1/medias/batch_get_tmp_download_url?file_tokens=UgSYbwu7oo4XNrxsikVchUPxndg","type": "image/png","url": "https://open.feishu.cn/open-apis/drive/v1/medias/UgSYbwu7oo4XNrxsikVchUPxndg/download"}]
}

结合多维表数据和返回数据可以看出：

  • “超链接”的数据结构是两组键值对，键“link”记录者链接内容，“text”记录链接的名称。
  • “附件”的数据结构是一个列表，当有多个附件时，一个附件作为一个元素。每个元素中都有六组键值对，键“file_token”记录附件的唯一标识，该值可用于将图片插入多维表的附件列；键“name”记录附件名称；键“size”记录附件大小，单位：B；键“tmp_url”记录临时链接，访问之后会返回一个公网可访问的图片网址供下载图片（注意：访问“tmp_url”需要 access token 鉴权）；键“type”记录附件类型，比如图片、文件等；键“url”记录图片的 API 链接，访问该链接返回一个二进制流数据，可直接写入本地图片（注意：访问时需要 access token 鉴权）。
  • “单向关联”和“双向关联”的字段值结构基本一致，都是返回一个简直对，键“link_record_ids”的值是一个列表，列表中的每个元素是我们引用的数据行的“record_id”。
  • “查找引用”的字段值由两组键值对构成，键“type”记录数据类型，键“value”记录引用的值。该字段有点套娃的意思，将目标字段返回的数据结构在键“value”中重新记录一遍。

2.6 其他

其他：7（复选框）、20（公式）、22（地理位置）、24（流程）、3001（按钮）

位置、按钮、流程
用和《1.1 文本类》类似的方法查看数字类的返回信息。
新建表单数据如下：
image.png

调接口返回数据如下：

{"公式-数字": {"type": 2,"value": [10]},"公式-文本": {"type": 1,"value": [{"text": "公式1","type": "text"}]},"地理位置": {"address": "东长安街","adname": "东城区","cityname": "北京市","full_address": "天安门广场，北京市北京市东城区东长安街","location": "116.397755,39.903179","name": "天安门广场","pname": "北京市"},"复选框": true,"自动编号": "1"
}

结合多维表数据和返回数据可以看出：

  • “复选框”的字段值是“true”或者“false”；
  • “公式”的字段值返回两组键值对，键“type”记录字符类型，另外一个键“value”记录字段值。公式的值一般只有两种：字符串和数字，即使是日期，也是以数字显示，不过“type”类型则是 5；
  • “地理位置”的字段值返回七组键值对，分别是详细地址（“address”）、区（“adname”）、城市（“cityname”）、省（“pname”）、完整地址（“full_address”）、经纬度（“location”）和地名（“name”）
  • “流程”和“按钮”这两个数据类型暂时没有返回值。

三、小结

整体上，我们可以分两部分来查看整个数据结构：

  • 第一部分是外层的结构，如下：
{"code": 0,"data": {"has_more": false,"items": [{"fields": {字段名:值,字段名:值},"record_id": "recuax3DpzWCW4"},{"fields": {字段名:值,字段名:值},"record_id": "recuax3DpzdSXv"},{"fields": {字段名:值,字段名:值},"record_id": "recuax3Dpz1dTA"}],"total": 10},"msg": "success"
}
  • 第二部分是“fields”的结构，“fields”值的每组键值对可能包含的数据类型示例如下：
数据类型编码数据类型中文描述数据类型对应英文描述数据示例
1多行文本、条码Text,Barcode“多行文本”: [{“text”: “我是文本1”,“type”: “text”}]
1Email邮箱Email“Email”: [{“link”: “mailto:ceshi@ceshi.com”,“text”: “ceshi@ceshi.com”,“type”: “url”}]
2数字、进度、货币、评分Number,Progress,Currency,Rating“数字”: 1.33
3单选SingleSelect“单选”: “单选11”
4多选MultiSelect“多选”: [“多选11”,“多选22”]
5日期DateTime“日期”: 1711900800000
7复选框Checkbox“复选框”: true
11人员User“人员”: [{“email”: “”,“en_name”: “user1”,“id”: “ou_4007a8a82cc6e0874524edda12ce94b1”,“name”: “user1”}]
13电话号码Phone“电话号码”: “13549857286”
15超链接Url“超链接”: {
“link”: “https://xxx.feishu.cn/base/PtRdbPjCFa5Og5sry0lcD1yPnKg?table=tbl3cvd797CmyEnN&view=vewdFnsmWn”,
“text”: “测试数据类型”
}
17附件Attachment“附件”: [
{
“file_token”: “Cm3Vb8fe4oLPw4xgChZcOa2Mnhe”,
“name”: “image.png”,
“size”: 956,
“tmp_url”: “https://open.feishu.cn/open-apis/drive/v1/medias/batch_get_tmp_download_url?file_tokens=Cm3Vb8fe4oLPw4xgChZcOa2Mnhe”,
“type”: “image/png”,
“url”: “https://open.feishu.cn/open-apis/drive/v1/medias/Cm3Vb8fe4oLPw4xgChZcOa2Mnhe/download”
}
]
18单向关联SingleLink“单向关联”: {“link_record_ids”: [“recuax3DpzWCW4”]}
19查找引用Lookup“查找引用”: {“type”: 1,“value”: [{“text”: “我是文本1”,“type”: “text”}]}
20公式Formula
21双向关联DuplexLink“双向关联”: {“link_record_ids”: [“recuax3DpzWCW4”]}
22地理位置Location“地理位置”: {
“address”: “东长安街”,
“adname”: “东城区”,
“cityname”: “北京市”,
“full_address”: “天安门广场，北京市北京市东城区东长安街”,
“location”: “116.397755,39.903179”,
“name”: “天安门广场”,
“pname”: “北京市”
}
23群组GroupChat“群组”: [{“avatar_url”: “https://s1-imfile.feishucdn.com/static-resource/avatar/default-avatar_9fb72564-d52a-49b0-9de8-f79071a02286_96.webp”,“id”: “oc_8b6ac124bd908dce5c5facfb41c4dd4e”,“name”: “(无主题)”}]
24流程Stage无返回值
1001创建时间CreatedTime同日期
1002最后更新时间ModifiedTime同日期
1003创建人CreatedUser同人员
1004修改人ModifiedUser同人员
1005自动编号AutoNumber“自动编号”: “1”
3001按钮Button无返回值

这篇关于飞书API（5）：查看多维表 28 种数据类型的数据结构的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！


http://www.chinasem.cn/article/924350。

相关文章

Linux如何查看文件权限的命令

Linux如何查看文件权限的命令

《Linux如何查看文件权限的命令》Linux中使用ls-R命令递归查看指定目录及子目录下所有文件和文件夹的权限信息,以列表形式展示权限位、所有者、组等详细内容... 目录linux China编程查看文件权限命令输出结果示例这里是查看tomcat文件夹总结Linux 查看文件权限命令ls -l 文件或文件夹
阅读更多...
SpringBoot监控API请求耗时的6中解决解决方案

SpringBoot监控API请求耗时的6中解决解决方案

《SpringBoot监控API请求耗时的6中解决解决方案》本文介绍SpringBoot中记录API请求耗时的6种方案,包括手动埋点、AOP切面、拦截器、Filter、事件监听、Micrometer+... 目录1. 简介2.实战案例2.1 手动记录2.2 自定义AOP记录2.3 拦截器技术2.4 使用Fi
阅读更多...
详解MySQL中JSON数据类型用法及与传统JSON字符串对比

详解MySQL中JSON数据类型用法及与传统JSON字符串对比

《详解MySQL中JSON数据类型用法及与传统JSON字符串对比》MySQL从5.7版本开始引入了JSON数据类型,专门用于存储JSON格式的数据,本文将为大家简单介绍一下MySQL中JSON数据类型... 目录前言基本用法jsON数据类型 vs 传统JSON字符串1. 存储方式2. 查询方式对比3. 索引
阅读更多...
Knife4j+Axios+Redis前后端分离架构下的 API 管理与会话方案(最新推荐)

Knife4j+Axios+Redis前后端分离架构下的 API 管理与会话方案(最新推荐)

《Knife4j+Axios+Redis前后端分离架构下的API管理与会话方案(最新推荐)》本文主要介绍了Swagger与Knife4j的配置要点、前后端对接方法以及分布式Session实现原理,... 目录一、Swagger 与 Knife4j 的深度理解及配置要点Knife4j 配置关键要点1.Spri
阅读更多...
Mysql实现范围分区表(新增、删除、重组、查看)

Mysql实现范围分区表(新增、删除、重组、查看)

《Mysql实现范围分区表(新增、删除、重组、查看)》MySQL分区表的四种类型（范围、哈希、列表、键值）,主要介绍了范围分区的创建、查询、添加、删除及重组织操作,具有一定的参考价值,感兴趣的可以了解... 目录一、mysql分区表分类二、范围分区（Range Partitioning1、新建分区表：2、分
阅读更多...
Python变量与数据类型全解析(最新整理)

Python变量与数据类型全解析(最新整理)

《Python变量与数据类型全解析(最新整理)》文章介绍Python变量作为数据载体,命名需遵循字母数字下划线规则,不可数字开头,大小写敏感,避免关键字,本文给大家介绍Python变量与数据类型全解析... 目录1、变量变量命名规范python数据类型1、基本数据类型数值类型(Number)：布尔类型(bo
阅读更多...
HTML5 getUserMedia API网页录音实现指南示例小结

HTML5 getUserMedia API网页录音实现指南示例小结

《HTML5getUserMediaAPI网页录音实现指南示例小结》本教程将指导你如何利用这一API，结合WebAudioAPI，实现网页录音功能,从获取音频流到处理和保存录音，整个过程将逐步... 目录1. html5 getUserMedia API简介1.1 API概念与历史1.2 功能与优势1.3
阅读更多...
Windows的CMD窗口如何查看并杀死nginx进程

Windows的CMD窗口如何查看并杀死nginx进程

《Windows的CMD窗口如何查看并杀死nginx进程》：本文主要介绍Windows的CMD窗口如何查看并杀死nginx进程问题,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地... 目录Windows的CMD窗口查看并杀死nginx进程开启nginx查看nginx进程停止nginx服务
阅读更多...
如何确定哪些软件是Mac系统自带的? Mac系统内置应用查看技巧

如何确定哪些软件是Mac系统自带的? Mac系统内置应用查看技巧

《如何确定哪些软件是Mac系统自带的?Mac系统内置应用查看技巧》如何确定哪些软件是Mac系统自带的？mac系统中有很多自带的应用，想要看看哪些是系统自带，该怎么查看呢？下面我们就来看看Mac系统内... 在MAC电脑上，可以使用以下方法来确定哪些软件是系统自带的：1.应用程序文件夹打开应用程序文件夹
阅读更多...
Linux查看系统盘和SSD盘的容量、型号及挂载信息的方法

Linux查看系统盘和SSD盘的容量、型号及挂载信息的方法

《Linux查看系统盘和SSD盘的容量、型号及挂载信息的方法》在Linux系统中,管理磁盘设备和分区是日常运维工作的重要部分,而lsblk命令是一个强大的工具,它用于列出系统中的块设备（blockde... 目录1. 查看所有磁盘的物理信息方法 1：使用 lsblk（推荐）方法 2：使用 fdisk -l（
阅读更多...

Copyright China编程 23002807@qq.com

沪ICP备2023033072号-2