一、引入
前面我们用于测试的数据集其实都是比较常用的数据,比如说文本、数字、单选等,但飞书多维表并不仅仅只有这些数据,截止发文,飞书多维表应用上支持28种数据类型,在数据层面飞书官方只提供了23种数据类型,5种合并了,如下表格:多行文本、条码、Email邮箱三种数据类型都合并到编码 1,都用文本表示,数字、进度、货币、评分都合并到编码 2,都用数字表示。
数据类型编码 | 数据类型中文描述 | 数据类型对应英文描述 |
---|---|---|
1 | 多行文本、条码 | Text,Barcode |
1 | 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(自动编号)
新建一个数据表,按上一行的数据类型创建字段,如下图,然后填充一些测试值。
为了方便查看读取的数据,建议列名和数据类型保持一致,避免后续需要来回核对某个字段的数据类型,而且不容易出错。
接下来使用 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”。
分别将参数填写到路径参数。
注意请求体中的内容把它清楚掉,保留一对大括号即可:{}
。
配置好了,发起请求:点击开始调试。可以看到返回的数据结构如下:
简单介绍一下整一个响应体的数据结构,将整个结构抽象一下,基本如下。
- 最外层是三组键值对构成,键分别是“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”键;
- “自动编号”、“电话号码”和“单选”的字段值都是一个字符串,记录的都是用户输入的信息;
- “多选”的字段值是一个列表,里面每个元素都是用户输入的信息。
2.2 数字类
数字类:2(数字、进度、货币、评分)
用和《1.1 文本类》类似的方法查看数字类的返回信息。
新建表单数据如下:
调接口返回数据如下:
{
"数字-小数": 1.33,
"数字-整数": 1,
"评分": 5,
"货币": 5.22,
"进度": 0.7
}
结合多维表数据和返回数据可以看出:“数字”、“进度”、“货币”和“评分”的字段值都是一个数值,记录的都是用户输入的信息。
2.3 日期类
日期类:5(日期)、1001(创建时间)、1002(最后更新时间)
用和《1.1 文本类》类似的方法查看数字类的返回信息。
新建表单数据如下:
调接口返回数据如下:
{
"创建时间": 1713683411000,
"日期": 1711900800000,
"日期-时间": 1712301240000,
"最后更新时间": 1713683658000
}
结合多维表数据和返回数据可以看出:“日期”、“创建时间”和“最后更新时间”的字段值都是一个毫秒级别的时间戳,需要转换为时间格式才能获取到用户输入的信息。
2.4 人员和群组
人员和群组类:11(人员)、23(群组)、1003(创建人)、1004(修改人)
用和《1.1 文本类》类似的方法查看数字类的返回信息。
新建表单数据如下:
调接口返回数据如下:
{
"人员": [
{
"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 文本类》类似的方法查看数字类的返回信息。
新建表单数据如下:
相关值的配置:
- 单向关联:关联《1.1 文本类》的数据表,“单向关联-允许多记录”则是在下图的“允许添加多个记录”前面打勾。
- 双向关联:关联《1.1 文本类》的数据表,“双向关联-允许多记录”则是在下图的“允许添加多个记录”前面打勾。
- 查找引用:关联《1.1 文本类》的数据表,根据“自动编号”字段进行匹配,然后返回列“多行文本”的“原值”。
调接口返回数据如下:
{
"单向关联": {
"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 文本类》类似的方法查看数字类的返回信息。
新建表单数据如下:
调接口返回数据如下:
{
"公式-数字": {
"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”}] |
1 | 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 | 无返回值 |