配置 LarkSheet 数据源
最近更新时间：2024.04.17 11:10:54
首次发布时间：2023.09.15 15:35:45
DataSail 支持将普通飞书表格或多维表格当做数据源，将表格中的数据同步至任意 DataSail 支持的批式 Writer 数据源中。
本文将为您介绍 LarkSheet 数据源的配置和离线任务可视化的配置能力。
1 支持的版本
- 任意 SaaS 版本的飞书普通电子表格和多维表格。
2 使用限制
子账号新建数据源时，需要有项目的管理员角色，方可以进行新建数据源操作。各角色对应权限说明，详见：管理成员
LarkSheet 数据源目前仅支持离线读。
DataSail 目前只支持飞书普通电子表格的接入，不支持 wiki 中的表格。
飞书电子表格没有表头的概念，但为了飞书电子表格导入任务具有更好的规范性，我们约定：
表格中的第一行会作为表头 。表头需要是：从 A1 单元格开始的，连续的，非空的，不能重名的一系列单元格。 表头只用于做字段映射，不会参与数据传输。
例如表头行数据如下：- 非法表头（D列为空）
A
B
C
D
E
姓名
年龄
爱好
学校
- 非法表头（A列为空）
A
B
C
D
E
姓名
年龄
爱好
学校
- 非法表头（B、D列名重复，均为“爱好”）
A
B
C
D
E
姓名
爱好
年龄
爱好
- 合法表头（ABCD 四列可以导入到目标数据源中）
A
B
C
D
E
姓名
年龄
爱好
学校
注意
在任务正常上线后，需要保证表头的稳定，不要轻易修改表头。任务执行前会进行表头校验，如出现非法表头或者跟任务中的字段映射对不齐时，会主动报错: Invalid sheet header
3 使用前提
- DataSail 飞书表格接入通过飞书 OpenApi 来进行数据读取，因此需要确保同步任务使用的独享数据集成资源组具有访问公网的能力，具体操作详见：资源组VPC开通公网
- DataSail 飞书表格接入需要表格 owner 授权“飞书云文档应用（又称飞书企业自建应用）”来进行数据抓取，因此需要:
- 提前在飞书开放平台创建“企业自建应用”，并授予企业自建应用关于电子表格的读取权限。详见企业自建应用的开发流程。
- 在飞书电子表格中，添加文档应用，添加已创建的“企业自建应用”，并授予相应阅读或编辑权限。
- 提前在飞书开放平台创建“企业自建应用”，并授予企业自建应用关于电子表格的读取权限。详见企业自建应用的开发流程。
4 支持的字段类型
因飞书电子表格无强制的 Schema 约束，DataSail 会将表格中的每个单元格统一当做 string 来处理，目标 Writer 数据源中对应的字段最好也是 string 类型，否则会可能会出现数据格式转化出错导致的作业失败。
5 数据同步任务开发
5.1 创建数据源
新建数据源操作详见配置数据源，以下为您介绍 LarkSheet 数据源配置相关信息：
参数 | 说明 |
|---|---|
基本配置 | |
数据源类型 | LarkSheet |
接入方式 | 连接串 |
数据源名称 | 数据源的名称，可自行设置，仅支持中文，英文，数字，“_”，100个字符以内。 |
参数配置 | |
APP ID | 进入飞书开放平台，单击已创建成功的企业自建应用，进入到凭证与基础信息界面，在应用凭证处，获取应用唯一的 APP ID 标识。 |
APP Secret | 在凭证与基础信息界面，获取应用的 APP Secret 秘钥，此秘钥在创建应用时由平台自动生成。 |
飞书开放平台域名 | 开放平台域名默认为 https://open.feishu.cn 说明 如果是普通 SaaS 版飞书，不需要修改飞书开放平台域名；除非使用私部版本飞书，才需要修改飞书开放平台域名。 |
5.2 新建离线任务
LarkSheet 数据源测试连通性成功后，进入到数据开发界面，开始新建 LarkSheet 相关通道任务。
新建任务方式详见离线数据同步。
5.3 可视化配置说明
任务创建成功后，您可根据实际情况，配置 LarkSheet 批式读通道任务。
5.3.1 配置 LarkSheet 离线读
数据来源选择 LarkSheet，并完成以下相关参数配置：
其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数。
参数 | 说明 |
|---|---|
*数据源类型 | 下拉选择 LarkSheet 数据源类型。 |
*数据源名称 | 已在数据源管理中注册成功的 LarkSheet 数据源，下拉可选。 |
*表格类型 | 支持选择飞书表格和多维表格两种类型。 |
*飞书链接 | 在输入框中写入飞书电子表格对应的 URL 连接。 注意 多张飞书电子表格写入同一个目标端时，必须保证这多张电子表格拥有完全相同的表头。 |
5.3.2 字段映射
数据来源和目标端配置完成后，需要指定来源和目标端的字段映射关系，根据字段映射关系，数据集成任务将源端字段中的数据，写入到目标端对应字段中。
您可通过以下三种方式操作字段映射关系：
- 自动添加：单击自动添加按钮，根据两端数据表信息，可以自动填充来源和目标的字段信息。
- 手动添加：单击手动添加按钮，可以手动编辑来源和目标的字段信息，可以逐个添加。
- 移动\删除字段：您也可以根据需要移动字段映射顺序或删除字段。
5.3.3 可选高级参数
LarkSheet 离线读时，您可在任务运行参数 > 自定义参数设置中填写任务执行时所需的高级参数，如图所示：
常见高级参数如下：
参数 | 描述 | 默认值 |
|---|---|---|
job.reader.batch_size | 从飞书 OpenApi 单次请求获取的行数，当表格中有复杂公式导致作业失败时，建议调低该参数。 | 2000 |
job.reader.skip_nums | 配置方式为一个数组，比如： [10, 20]。 | []，代表不会跳过任何行 |
6 常见问题
6.1 导入目标数据源的数据不是普通文本内容，是 json 串
- 问题描述：
比如在表格中是一个普通的字符串："IES在线-IM"，导入目标数据源中变成如下图所示的 json 串。
- 问题原因：
这类问题一般是由下列原因导致的：- 单元格带有格式，比如有颜色，或者是超链接；
- 单元格中包含特殊字符，如 & 等；
- 单元格即使清除了格式，但是同一字符串中不同字符的大小不一致。比如上述例子中，"IES"是3号字体，"在线" 却是4号字体；
- 单元格是超链接格式。
- 解决方案：
在任务的运行参数设置中，新增一个高级参数：job.reader.lark.valueRenderOption=ToString。
如下图所示：
6.2 点击字段映射中的“自动添加”按钮时报错：请将文档正确分享给云文档应用
出现此异常提醒，请检查以下几项：
- 请确保 LarkSheet 数据源已经通过连通性测试。
- 请确保飞书表格已经添加了“云文档应用”，添加方式如下：
- 确保表格无特殊权限设置，一般权限设置如下：
6.3 任务执行失败，执行日志中报错如下图：
- 问题原因：
飞书单元格过大，或者有一些列使用了公式，导致调取lark openapi超时（20s） - 解决方案：
- 尝试配置高级参数：
job.reader.batch_size，将参数对应的值降低，减少单次读取的数据量。 - 上述调参后若还是出现异常，请确认表格中是否含有公式，可将公式粘贴成纯文本后，再导入数据。
- 尝试配置高级参数：
6.4 飞书表头字段有啥特殊限制吗？
前后不要出现空格、制表符等不可见字符，否则会引起任务失败。
注意
表头不能有以下几种情况：
- 超链接；
- 格式不一样的单元格，比如前两个字跟后两个字颜色不一样等
否则在拉取飞书表格 Schema 的时候也会报错（如下图所示）。因此推荐使用纯文本来做表头，且表头不要有一些自定义的格式。
6.5 支持公式或者计算列的导入吗？
目前多维表格中暂不支持列中包含公式或计算列。
6.6 如何导入飞书文档链接 & url
表格内容若是“飞书云文档链接”，则一般会自动转为标题，此时导入目标数据源后，也会是标题形式。
若需要导入文档链接，需要在表格中进行以下操作：
- 清空单元格。
- 双击单元格，进入输入状态。
- 粘贴文档链接，鼠标光标移至链接上，出现 hover 时，单击取消链接按钮，如下图所示：
