DataSail 支持将普通飞书表格或多维表格当做数据源，将表格中的数据同步至任意 DataSail 支持的批式 Writer 数据源中。
本文将为您介绍 LarkSheet 数据源的配置和离线任务可视化的配置能力。

1 支持的版本

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

2 使用限制

1. 子账号新建数据源时，需要有项目的管理员角色，方可以进行新建数据源操作。各角色对应权限说明，详见：管理成员

2. LarkSheet 数据源目前仅支持离线读。

3. 飞书电子表格没有表头的概念，但为了飞书电子表格导入任务具有更好的规范性，我们约定：
   表格中的第一行会作为表头 。表头需要是：从 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 授权“飞书云文档应用（又称飞书企业自建应用）”来进行数据抓取，因此需要:
  1. 提前在飞书开放平台创建“企业自建应用”，并授予企业自建应用关于电子表格的读取权限。详见企业自建应用的开发流程。
     
  2. 在飞书电子表格中，添加文档应用，添加已创建的“企业自建应用”，并授予相应阅读或编辑权限。
     

4 支持的字段类型

因飞书电子表格无强制的 Schema 约束，DataSail 会将表格中的每个单元格统一当做 string 来处理，目标 Writer 数据源中对应的字段最好也是 string 类型，否则会可能会出现数据格式转化出错导致的作业失败。

5 数据同步任务开发

5.1 创建数据源

新建数据源操作详见配置数据源，以下为您介绍 LarkSheet 数据源配置相关信息：

5.2 新建离线任务

LarkSheet 数据源测试连通性成功后，进入到数据开发界面，开始新建 LarkSheet 相关通道任务。
新建任务方式详见离线数据同步。

5.3 可视化配置说明

任务创建成功后，您可根据实际情况，配置 LarkSheet 批式读通道任务。

5.3.1 配置 LarkSheet 离线读

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

5.3.2 字段映射

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

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

  配置节点	说明
  来源节点	配置数据来源 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 参数说明，其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数：

5.5 可选高级参数

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

常见高级参数如下：

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 飞书表头字段有啥特殊限制吗？

前后不要出现空格、制表符等不可见字符，否则会引起任务失败。

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

目前多维表格中暂不支持列中包含公式或计算列。

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

表格内容若是“飞书云文档链接”，则一般会自动转为标题，此时导入目标数据源后，也会是标题形式。
若需要导入文档链接，需要在表格中进行以下操作：

1. 清空单元格。
2. 双击单元格，进入输入状态。
3. 粘贴文档链接，鼠标光标移至链接上，出现 hover 时，单击取消链接按钮，如下图所示：

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

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