配置 LarkSheet 数据源--大数据研发治理套件-火山引擎

文档中心

大数据研发治理套件

数据源列表

配置 LarkSheet 数据源

DataSail 支持将飞书表格或多维表格当做数据源，将表格中的数据与任意 DataSail 支持的数据源进行数据同步操作。
本文将为您介绍 LarkSheet 数据源的配置和离线任务可视化的配置能力。

1 支持的版本

任意 SaaS 版本的飞书普通电子表格和多维表格。

2 使用限制

子账号新建数据源时，需要有项目的管理员角色，方可以进行新建数据源操作。各角色对应权限说明，详见：管理成员
数据写入 LarkSheet 数据源时，单次最多只支持写入 100 列数据，单次最多写入行数为 5000 行，每个单元格字段内容需小于 40000 字符，且仅支持写入 Text/String 类型，暂不支持其他数据类型写入。
数据写入 LarkSheet 数据源时，集成任务运行参数中所设置的期望最大并发数应设置为 1，不支持多并发方式写入。
数据写入多维表格时，仅支持选择 insert into 写入方式。
飞书电子表格没有表头的概念，但为了飞书电子表格导入任务具有更好的规范性，我们约定：
表格中的第一行会作为表头。表头需要是：从 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

A	B	C	D	E
姓名	年龄	爱好		学校

A	B	C	D	E
	姓名	年龄	爱好	学校

A	B	C	D	E
姓名	爱好	年龄	爱好

A	B	C	D	E
姓名	年龄	爱好	学校

3 使用前提

DataSail 飞书表格接入通过飞书 OpenApi 来进行数据读取，因此需要确保同步任务使用的独享数据集成资源组具有访问公网的能力，具体操作详见：资源组VPC开通公网
DataSail 飞书表格接入需要表格 owner 授权“飞书云文档应用（又称飞书企业自建应用）”来进行数据抓取，因此需要:
1. 提前在飞书开放平台创建“企业自建应用”，并授予企业自建应用关于电子表格的读取和编辑权限。
  具体授予权限如下：
  - 查看、编辑和管理知识库：wiki:wiki
  - 查看、评论、编辑和管理文档：docs:doc
  - 查看、评论、编辑和管理多维表格：bitable:app
  - 查看、评论、编辑和管理电子表格：sheets:spreadsheet
  - 查看、评论、编辑和管理云空间中所有文件：drive:drive
  - 判断当前用户是否有云文档权限：docs:permission.member:auth
    
    详见企业自建应用的开发流程。
2. 在飞书电子表格/多维表格中，添加文档应用，添加已创建的“企业自建应用”，并授予相应阅读或编辑权限。

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 数据源，下拉可选。若还未建立相应数据源，可单击数据源管理按钮，前往创建 LarkSheet 数据源。
*表格类型	支持选择飞书表格和多维表格两种类型。
*飞书链接	在输入框中写入飞书电子表格对应的 URL 链接。您可单击右侧的添加按钮，支持添加多张飞书电子表格。注意多张飞书电子表格写入同一个目标端时，必须保证这多张电子表格拥有完全相同的表头。多维表格如果需要同步非过滤后的数据，填写 URL 链接时，请手动将链接中末尾的 View 参数去除。支持读取飞书知识库中的飞书表格和多维表格，即 URL 中带有“wiki”字样的链接。

5.3.2 配置 LarkSheet 离线写

数据目标端选择 LarkSheet，并完成以下相关参数配置：
其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数。

参数	说明
*数据源类型	下拉选择 LarkSheet 数据源类型。
*数据源名称	已在数据源管理中注册成功的 LarkSheet 数据源，下拉可选。若还未建立相应数据源，可单击数据源管理按钮，前往创建 LarkSheet 数据源。
*表格类型	支持选择飞书表格和多维表格两种类型。
*飞书链接	在输入框中写入飞书电子表格对应的 URL 链接。说明当拥有表格可管理的权限时，支持向飞书知识库中的飞书表格和多维表格写入数据，即表格的链接为 URL 中带有“wiki”字样的链接。
*数据写入方式	写入 LarkSheet 数据源支持以下两种写入方式： insert overwrite: 先删除原有表格中的数据，再将源端新数据进行写入； insert into: 直接在表格末行写入新数据。注意写入多维表格时，仅支持选择 insert into 写入方式。

5.3.3 字段映射

数据来源和目标端配置完成后，需要指定来源和目标端的字段映射关系，根据字段映射关系，数据集成任务将源端字段中的数据，写入到目标端对应字段中。
字段映射支持选择基础模式和转换模式配置映射：

注意

基础模式和转换模式不支持互相切换，模式切换后，将清空现有字段映射中所有配置信息，一旦切换无法撤销，需谨慎操作。

转换模式：
字段映射支持数据转换，您可根据实际业务需求进行配置，将源端采集的数据，事先通过数据转换后，以指定格式输入到目标端数据库中。
转换模式详细操作说明详见4.1 转换模式
在转换模式中，你可依次配置：来源节点、数据转换、目标节点信息：

配置节点	说明
来源节点	配置数据来源 Source 节点信息：节点名称：自定义输入来源节点名称信息，只允许由数字、字母、下划线、-和.组成；且长度不能超过10。数据字段：通过自动添加、手动添加等方式添加数据来源字段信息。配置完成后，单击确认按钮，完成来源节点配置。
数据转换	单击数据转换右侧添加按钮，选择 SQL 转换方式，配置转换信息和规则：节点名称：自定义输入来源节点名称信息，只允许由数字、字母、下划线、-和.组成；且长度不能超过10。 SQL 脚本：输入 SQL 脚本转换规则，目前仅支持添加一个转换的 SQL 语句，且不能包括 “;”。配置完成后，单击确认按钮，完成数据转换节点配置。SQL 脚本示例详见4.1.2 添加转换节点。
目标节点	配置目标节点 Sink 信息：节点名称：自定义输入来源节点名称信息，只允许由数字、字母、下划线、-和.组成；且长度不能超过10。数据字段：通过自动添加、手动添加等方式添加数据目标字段信息。配置完成后，单击确认按钮，完成目标节点配置。

配置节点

说明

来源节点

配置数据来源 Source 节点信息：

节点名称：自定义输入来源节点名称信息，只允许由数字、字母、下划线、-和.组成；且长度不能超过10。
数据字段：通过自动添加、手动添加等方式添加数据来源字段信息。

配置完成后，单击确认按钮，完成来源节点配置。

数据转换

单击数据转换右侧添加按钮，选择 SQL 转换方式，配置转换信息和规则：

节点名称：自定义输入来源节点名称信息，只允许由数字、字母、下划线、-和.组成；且长度不能超过10。
SQL 脚本：输入 SQL 脚本转换规则，目前仅支持添加一个转换的 SQL 语句，且不能包括 “;”。

配置完成后，单击确认按钮，完成数据转换节点配置。SQL 脚本示例详见4.1.2 添加转换节点。

目标节点

配置目标节点 Sink 信息：

节点名称：自定义输入来源节点名称信息，只允许由数字、字母、下划线、-和.组成；且长度不能超过10。
数据字段：通过自动添加、手动添加等方式添加数据目标字段信息。

配置完成后，单击确认按钮，完成目标节点配置。

基础模式：
您可通过以下三种方式操作字段映射关系：
- 自动添加：单击自动添加按钮，根据两端数据表信息，可以自动填充来源和目标的字段信息。
- 手动添加：单击手动添加按钮，可以手动编辑来源和目标的字段信息，可以逐个添加。
- 移动\删除字段：您也可以根据需要移动字段映射顺序或删除字段。

5.4 DSL 配置说明

LarkSheet 数据源支持使用脚本模式（DSL）的方式进行配置。
在某些复杂场景下，您可通过任务脚本的方式，按照统一的 Json 格式，编写 LarkSheet Reader 参数脚本代码，来运行数据集成任务。

5.4.1 进入 DSL 模式

进入 DSL 模式操作流程，可详见 MySQL 数据源-4.4.1 进入DSL 模式。

5.4.2 LarkSheet Reader

进入 DSL 模式编辑界面后，您可根据实际情况替换相应参数，LarkSheet Reader 脚本示例如下

{
    // [required] dsl version, suggest to use latest version
    "version": "0.2",
    // [required] execution mode, supoort streaming / batch now
    "type": "batch",
    // reader config
    "reader": {
        // [required] datasource type
        "type": "larksheet",
        // [optional] datasource id, set it if you have registered datasource
        "datasource_id": 123,
        // [required] user parameter
        "parameter": {
            // ********** please write here **********
            // "key" : value
            "columns": [{
                    "type": "string",
                    "name": "jj"
                }, {
                    "type": "string",
                    "name": "ii"
                }, {
                    "type": "string",
                    "name": "hh"
                }, {
                    "type": "string",
                    "name": "gg"
                }, {
                    "type": "string",
                    "name": "ff"
                }, {
                    "type": "string",
                    "name": "ee"
                }, {
                    "type": "string",
                    "name": "dd"
                }, {
                    "type": "string",
                    "name": "cc-主管"
                }, {
                    "type": "string",
                    "name": "vv"
                }, {
                    "type": "string",
                    "name": "aa"
                }],
                "class":"com.bytedance.dts.batch.lark.bitable.LarkBitableInputFormat",
                "bitable_url": "https://dx49vxrxjmx.feishu.cn/base/VOvUbNLqUa8z9Dso5DCcCBe7nKb?table=tblsUjtRQvsjuQZr"
        }
    },
    // writer config
    "writer": {
        // [required] datasource type
        "type": "las",
        // [optional] datasource id, set it if you have registered datasource
        "datasource_id": 123,
        // [required] user parameter
        "parameter": {
            // ********** please write here **********
            // "key" : value
            "service_region": "cn-beijing",
            "partition": "`date`=20240624",
            "db_name": "bigdata_demo",
            "columns": 
                [{
                    "type": "string",
                    "name": "col1",
                    "description": "1"
                }, {
                    "type": "string",
                    "name": "col2",
                    "description": "1"
                }, {
                    "type": "string",
                    "name": "col3",
                    "description": "1"
                }, {
                    "type": "string",
                    "name": "col4",
                    "description": "1"
                }, {
                    "type": "string",
                    "name": "col5",
                    "description": "1"
                }, {
                    "type": "string",
                    "name": "col6",
                    "description": "1"
                }, {
                    "type": "string",
                    "name": "col7",
                    "description": "1"
                }, {
                    "type": "string",
                    "name": "col8",
                    "description": "1"
                }, {
                    "type": "string",
                    "name": "col9",
                    "description": "1"
                }, {
                    "type": "string",
                    "name": "col10",
                    "description": "1"
                }],
            "class": "com.bytedance.dts.las.LasOutputFormat",
            "table_name": "lark_demo"
        }
    },
    // common config
    "common": {
        // [required] user parameter
        "parameter": {
            // ********** please write here **********
            // "key" : value
        }
    }
}

Reader 参数说明，其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数：

参数名称	参数含义
*type	Reader type，默认固定值 larksheet
*datasource_id	注册的 LarkSheet 数据源 ID。可以在项目控制台 > 数据源管理界面中查找。
*class	LarkSheet reader connector type，不同表格类型，其默认固定值不同：多维表格：com.bytedance.dts.batch.lark.bitable.LarkBitableInputFormat 飞书表格：com.bytedance.dts.batch.lark.LarkSheetInputFormat
*bitable_url	需要读取的 LarkSheet 飞书表格 URL 链接信息，如：https://bytedance.larkoffice.com/sheets/G2xxxxxxxxxxxxb
*columns	所配置的飞书表格中，需要同步的列名集合，使用 JSON 的数组描述字段信息。支持列裁剪：列可以挑选部分列进行导出。支持列换序：列可以不按照表 Schema 信息顺序进行导出。 column 必须显示指定同步的列集合，不允许为空。

5.5 可选高级参数

LarkSheet 离线读时，您可在任务运行参数 > 自定义参数设置中填写任务执行时所需的高级参数，如图所示：

常见高级参数如下：

参数	描述	默认值
job.reader.batch_size	从飞书 OpenApi 单次请求获取的行数，当表格中有复杂公式导致作业失败时，建议调低该参数。	2000
job.reader.skip_nums	配置方式为一个数组，比如： [10, 20]。该设置方法表示针对第一张 sheet，会跳过前10行（从表头行之后算起）；第二张 sheet 会跳过前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 时，单击取消链接按钮，如下图所示：

6.7 如何同步多维表格时间字段类型数据到 ByteHouse 企业版？

问题描述：
多维表格中的日期字段数据，如：2024/01/30 14:00，同步到 ByteHouse 企业版数据库后，时间数据错乱。
解决方案：
DataSail 直接读取多维表格的数据，读取出来的时间是毫秒级 utc 字符串，原样传给 ByteHouse 企业版数据库后，需要把 ByteHouse 数据库中对应字段的数据类型自定义为 DateTime64(3, 'Asia/Shanghai')，方能正常接收。

最近更新时间：2026.01.22 15:08:06

这个页面对您有帮助吗？

有用

无用

大数据研发治理套件

1 支持的版本 #

2 使用限制 #

3 使用前提 #

4 支持的字段类型 #

5 数据同步任务开发 #

5.1 创建数据源 #

5.2 新建离线任务 #

5.3 可视化配置说明 #

5.3.1 配置 LarkSheet 离线读

5.3.2 配置 LarkSheet 离线写

5.3.3 字段映射

5.4 DSL 配置说明 #

5.4.1 进入 DSL 模式

5.4.2 LarkSheet Reader

5.5 可选高级参数 #

6 常见问题 #

6.1 导入目标数据源的数据不是普通文本内容，是 json 串 #

6.2 点击字段映射中的“自动添加”按钮时报错：请将文档正确分享给云文档应用 #

6.3 任务执行失败，执行日志中报错如下图： #

6.4 飞书表头字段有啥特殊限制吗？ #

6.5 支持公式或者计算列的导入吗？ #

6.6 如何导入飞书文档链接 & url #

6.7 如何同步多维表格时间字段类型数据到 ByteHouse 企业版？ #