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

最新推荐文章于 2024-06-20 14:52:13 发布

Xin学数据

最新推荐文章于 2024-06-20 14:52:13 发布

阅读量1.1k

点赞数 9

分类专栏：飞书API解读文章标签：飞书数据结构 python

本文链接：https://blog.csdn.net/qq_45476428/article/details/138045818

版权

飞书API解读专栏收录该内容

13 篇文章 1 订阅

订阅专栏

一、引入

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

数据类型编码	数据类型中文描述	数据类型对应英文描述
1	多行文本、条码	Text,Barcode
1	Email邮箱	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 文本类》类似的方法查看数字类的返回信息。
新建表单数据如下：

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	“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	无返回值

Xin学数据

关注

9
点赞
踩
16

收藏

觉得还不错? 一键收藏
打赏
0
评论
飞书API（5）：查看多维表 28 种数据类型的数据结构

整体上，我们可以分两部分来查看整个数据结构：第一部分是外层的结构，第二部分是“fields”的结构。第一部分是通用的，而第二部分各个数据类型各有不同，具体详见文章说明。
复制链接

扫一扫