创建飞书多维表格数据源

使用飞书多维表格作为数据源,Quick BI用户可以无缝将飞书多维表格中丰富的数据表数据导入到Quick BI中,以进行更深入的可视化分析和商业智能挖掘。企业数据分析团队可以利用飞书多维表格的数据管理优势和Quick BI的强大数据分析功能,实现高效的数据协作和实时的业务洞察。本文将为您介绍如何创建飞书多维表格数据源。

前提条件

限制说明

  • 仅专业版支持创建飞书多维表格数据源。

  • 飞书多维表格的数据表支持多种字段类型,您可以通过飞书多维表格解析规则,查看飞书多维表格字段与Quick BI字段类型的映射关系。

  • 飞书多维表格数据源存在以下功能限制

    • 使用飞书多维表格数据源创建的数据集

      • 不支持使用自定义SQL、抽取加速、关联建模及占位符功能。

      • 不支持基于该数据集创建趋势分析表、多维分析表。

    • 不支持使用监控告警、自助取数功能。

  • 由于飞书侧限制,自20241031日起,飞书基础免费版接口累计可调用次数为1万次/月。若该调用量无法满足需求,您可升级至其他飞书版本扩容调用次数。具体请参见飞书自建应用API调用量上限调整说明

操作步骤

将飞书多维表格接入Quick BI主要有获取飞书应用授权信息、获取飞书多维表格分享链接、创建飞书多维表格数据源三个步骤。

  • 如果您的组织已在组织管理 > 办公软件接入处完成飞书接口授权,那么在创建飞书多维表格数据源时,系统将自动为您读取已接入的应用信息,请确保飞书组织内安装的应用已为最新应用版本。您可以直接跳至步骤二:获取多维表格链接操作。

  • 如果您的组织当前未在组织管理 > 办公软件接入处完成飞书接口授权,您可以联系您所在组织管理员进行配置,也可以添加自建应用,完成飞书多维表格数据的接入,请参考步骤一:获取应用授权信息开始操作。

步骤一:获取应用授权信息

您需要在飞书开放平台中创建企业自建应用,并获取相关授权信息,用于后续在Quick BI中创建数据源时认证使用。具体操作说明如下。

  1. 登录飞书开放平台,点击创建企业自建应用,在创建弹窗中维护应用的相关信息,完成后点击创建image

  2. Quick BI是通过API接口读取飞书多维表格数据,因此您需要为当前应用申请飞书API接口的权限。在应用的开发者后台,选择左侧导航栏权限管理,在API权限页签下为当前创建的应用配置所需权限。image

    您需要勾选以下API权限并点击批量开通

    • 查看、评论、编辑和管理云空间中所有文件

    • 查看、评论、编辑和管理多维表格

    • 查看、评论和导出多维表格

    • 管理应用自身资源

    • 获取应用信息

  3. 点击提示弹窗中的确认并前往创建应用版本image

  4. 在跳转版本管理与发布页面中,选择创建版本image

  5. 维护版本详情,完成后点击保存 > 申请线上发布,即可完成当前应用的发布。image

  6. 在应用的开发者后台 > 凭证与基础信息页面,复制并保存当前应用的App IDApp Secretimage

步骤二:获取多维表格链接

登录飞书云文档,找到需要接入Quick BI的目标多维表格,复制并保存分享链接。具体操作说明如下。

  1. 在飞书云文档的文档列表中,找到需要接入Quick BI的目标多维表格,点击其操作列下拉列表中的分享image

    说明

    对于接入Quick BI的飞书多维表格,目前存在以下限制,请您提前确认表格是否符合以下限制。

    • 单个表格页列数不能超过100列,行数不能超过10000行。

    • 不支持导入包含附件、关联、查找引用字段类型的表格,您可以通过参考飞书多维表格解析规则中的字段映射详情表格,查看支持导入Quick BI的字段类型。

    • 不支持继承表格中的计算公式,导入后将仅保留数值。

  2. 分享文档弹窗中设置链接的分享范围。image

    说明

    当链接分享范围设置为仅文档协作者可通过链接访问时,需要添加当前自建应用到表格的文档应用中。image

  3. 点击复制链接按钮,复制并保存当前表格的分享链接。image

步骤三:创建数据源

获取飞书授权信息及多维表格分享链接后,您需要将其添加至Quick BI数据源新建页面中,以接入飞书中的多维表格。具体操作说明如下。

  1. 登录Quick BI工作台 > 数据源,点击数据源页面右上角的新建数据源image

  2. 新建数据源页面选择应用服务 > 飞书多维表格image

  3. 在跳转配置页面中,填入通过步骤一、步骤二获取的飞书端相关授权信息及多维表格链接。

    • 如果您的组织已在组织管理 > 办公软件接入处完成飞书接口授权,那么在创建飞书多维表格数据源时,系统将自动为您读取已授权的应用,请确保该应用已被授予飞书侧多维表格相关接口的调用权限。image

    • 如果您的组织未在组织管理办公软件接入处完成飞书接口授权,您需要将在步骤一中创建的企业自建应用的相关授权信息配置在此处。

      image

      配置内容

      配置说明

      AppKey

      填入飞书自建应用的唯一标识,对应飞书开发者后台凭证与基础信息页面中的 App ID。image

      AppSecret

      填入飞书自建应用的密钥,在创建当前应用时由飞书平台自动生成。对应飞书开发者后台凭证与基础信息页面中的App Secret。image

      飞书表格链接

      填入飞书多维表格分享链接,对应飞书文档分享页面中复制的链接。image

  4. 点击连接测试,测试通过后页面上即会显示授权应用的信息。image

  5. 点击确定连接,跳转至数据预览页面。您可以在此预览以下信息并进行相关操作。image

    展示内容

    配置内容

    配置操作

    区域 ①

    多维表格在Quick BI系统中的展示名称

    重命名展示名称

    数据源展示名称为多维表格在Quick BI系统中的展示名称。当确认连接表格时,系统会自动识别表格名称,并作为该表格在Quick BI系统中的展示名称,您可以根据实际需求自定义修改。

    说明

    展示名称不允许使用特殊字符,且前后不能包含空格。

    区域②

    多维表格的分享链接

    跳转查看源文档

    点击表格链接旁的image图标,即可在跳转新窗口中查看当前表格在飞书端的源文档。

    区域 ③

    多维表格的表格页数量及标题

    切换表格页

    单击页签切换表格页以预览不同表格页中的数据内容,数据内容(即区域)会随着页签的切换而相应调整。

    重命名表格页

    双击名称以根据实际业务意义重命名当前表格页,默认读取飞书端多维表格中的表格页名称。

    说明

    表格页名称不允许使用特殊字符,且前后不能包含空格。

    区域 ④

    多维表格的数据内容

    数据预览

    数据预览页签下预览数据内容,并进行以下操作。

    • 修改字段名称:单击字段名称输入框,修改字段名。

    • 修改字段类型:点击字段类型图标,在下拉列表中选择合适的字段类型。支持的类型包括文本、数值、日期。image

      说明
      • 不支持导入附件、关联、查找引用的字段类型,如果您的飞书源文档中包含以上字段类型,在导入过程中将会被去除。

      • 不支持继承飞书源文档中的计算公式,导入后仅保留数值。

      • 飞书多维表格导入后,Quick BI系统会自动将飞书源文档中的字段类型,转换为对应的数据类型,具体映射关系请参考本文限制说明中的字段映射详情表格。

    字段详情

    表格接入后,会以数据库表的形式存储,数据库字段名称字段类型为生成数据库表的字段名和类型,而字段名称对应飞书多维表格中数据表的字段名称。

    您可以在此根据实际情况重命名字段名称、修改字段类型。当不需要使用某一个字段时,点击image图标即可将其删除。

    image

    说明
    • 不支持导入附件、关联、查找引用的字段类型,如果您飞书源文档中包含以上字段类型,在导入过程中将会被移除。

    • 不支持继承飞书源文档中的计算公式,导入后仅保留数值。

    • 飞书多维表格导入后,Quick BI系统会自动将飞书源文档中的字段类型,转换为对应的数据类型,具体映射关系请参考本文限制说明中的字段映射详情表格。

    自动解析

    在飞书多维表格中,一个单元格内的数据内容可能不仅仅是简单的文本或数字,它可能携带卡片、标签列表等样式以展示多维信息。当Quick BI通过API从表格中提取数据时,为保留完整的数据层次和语义信息,包含复杂信息的字段通常以JSON格式来传输。Quick BI接收到这些JSON格式的数据后,需要进一步解析成可用于数据分析的普通字段。

    此时,您可以通过开启自动解析功能,采用Quick BI侧提供的飞书多维表格解析规则,自动将JSON数据解析成对应的字段类型;也可以按需通过新建计算字段来自定义解析规则。

    默认为当前表格数据源开启自动解析状态,支持通过点击开关图标(image)调整。

    说明

    使用飞书多维表格数据源创建的数据集,在新建计算字段时,仅支持使用系统内置函数。

    设置定时同步

    当您需要每天向Quick BI多维表格数据源中定时同步最新业务数据时,您可以将定时同步开关置于开启状态,并在数据定时同步弹窗中设置每天需要同步数据的时间点。image

    说明
    • 每次同步都会全量覆盖原有数据,单个表格页的同步上限为10000行和100列。

    • 该项设置仅对当前表格页生效,如果您有多个表格页需要同步,请逐一切换至相应表格页页签设置定时同步时间。

  6. 完成配置后点击确认并连接,完成飞书表格数据源创建。image

  7. 回到数据源页面,在数据源列表中找到刚才接入的飞书多维表格数据源,点击各表格页操作列的image图标以同步数据。image

  8. (可选)您可以在数据源页面中,查看并管理已创建的飞书多维表格数据源及其下的表格页,支持进行以下操作。image

    • 预览数据表:在名称列找到需要预览的数据表,点击其名称,即可在预览数据页面查看当前数据表的内容。

    • 设置定时同步:点击定时同步开关image,修改定时同步功能的开启状态;也可以在定时同步开启的前提下,点击image图标修改定时同步的时间点。

    • 创建数据集:点击image图标,即可跳转至数据集创建页面,在当前表格页的基础上创建数据集。关于创建数据集的详细操作说明,请参见创建数据集

      说明

      请确保当前表格页的同步状态为成功,否则无法基于此表格页创建数据集。

    • 同步数据:点击image图标以手动触发同步任务。

    • 查看同步记录:点击image图标,在查看日志弹窗中查看当前表格页的历史更新记录,展示的内容包括:更新的时间、状态、耗时、日志信息,且支持根据特定的时间范围查询相关日志。image

步骤四:编辑数据源

将飞书多维表格接入Quick BI平台后,支持编辑该数据源的授权信息、表格分享链接、数据源展示名称等信息,具体操作如下。

  1. 飞书多维分析表格列表中,找到目标数据源并点击编辑按钮。image

  2. 在飞书多维表格的选择数据界面,修改飞书自建应用的授权信息。image

    配置内容

    配置说明

    已授权应用

    点击已授权应用下拉框中的image图标,页面中即会显示AppKeyAppSecret的输入框,在此维护新应用的AppKeyAppSecret。image

    飞书表格链接

    填入新表格的分享链接。

  3. 点击连通测试,校验通过后点击确定连接,即可跳转至预览数据界面。您可以在此根据实际需求编辑多维表格的展示名称、定时同步设置、字段名称、数据类型等信息,具体操作说明同创建数据源中的第5步。

  4. 完成编辑后点击确认并连接

飞书多维表格解析规则

为展示多维信息,飞书多维表格中可能会存在携带卡片、标签列表等样式的数据内容。当Quick BI通过API拉取表格数据时,包含样式化信息的字段会以JSON格式传输。在自动解析模式下,Quick BI接收到这些JSON数据后,会根据由Quick BI侧统一制定的解析规则,自动将JSON数据解析成可用于数据建模、报表制作等数据分析步骤的普通字段。

Quick BI侧支持解析的飞书多维表格字段类型及解析策略如下。

说明

暂不支持导入以下字段类型:单向关联、双向关联、查找引用、附件。

飞书多维表格字段

飞书多维表格字段类型

Quick BI字段类型

是否解析

数字、进度、货币或评分

string

数值

/

单选

string

文本

/

多选

array<string>

文本

转为string

日期

number

日期

转为日期

复选框

文本

文本

/

人员

list of object

文本

解析为name

电话号码

string

文本

/

超链接

object

文本

解析为link

公式

object

文本

/

地理位置

object

文本

解析为full_address

群组

list of object

文本

解析为name

创建时间

number

日期

转为日期

最后更新时间

number

日期

转为日期

创建人

object

文本

解析为name

修改人

object

文本

解析为name

自动编号

string

数值

/

文本

list of object

文本

解析为text

条码

list of object

文本

解析为text

邮箱

list of object

文本

解析为text

后续操作

创建数据源后,您还可以创建数据集并分析数据。

常见问题

1. 飞书多维表格连接失败的常见原因

如果您在接入飞书多维表格时出现连接失败的报错提示,请排查是否存在以下问题:

错误原因

解决方案

添加飞书应用授权时,Appkey、Appsecret 信息填写有误。image

您需要登录飞书开发者后台,重新获取待授权应用正确的Appkey、Appsecret。image

未在飞书开发者后台的权限管理页面,为飞书自建应用开启所需的API权限。image

您需要开启以下API的权限:

  • 查看、评论、编辑和管理云空间中所有文件

  • 查看、评论、编辑和管理多维表格

  • 查看、评论和导出多维表格

  • 管理应用自身资源

  • 获取应用信息

当飞书多维表格的链接分享范围是仅文档协作者可以通过链接访问时,未添加对应的企业自建应用作为文档应用。image

您需要在飞书多维表格的文档编辑页面中,添加对应的企业自建应用为文档应用,具体操作步骤如下图所示。image

当飞书多维表格的链接分享范围是仅文档协作者可以通过链接访问时,在文档编辑页面无法选对应的自建应用作为文档应用,导致添加文档应用失败。image

当前账户能在文档中添加到对应企业自建应用的前提是:创建应用版本时,在版本详情的可用范围中添加了当前账户。image

若您使用系统默认接入的应用信息,该三方应用可能未更新至最新版本。

您可以前往飞书管理后台进行应用版本更新。image