You need to enable JavaScript to run this app.
文档中心
大数据研发治理套件

大数据研发治理套件

请输入
  • 文档首页
    • 大数据研发治理套件用户指南数据集成数据源列表TOS配置 TOS 任务
复制全文
下载 pdf
我的收藏
TOS
配置 TOS 任务
复制全文
下载 pdf
我的收藏
配置 TOS 任务

DataSail 中 TOS 数据源为您提供读取和写入 TOS 数据的双向通道能力，实现不同数据源与 TOS 进行数据传输。本文介绍在 DataSail 中创建 TOS 离线读取、离线写入和实时写入任务的方法。

1 使用前提

  • 已完成 TOS 数据源配置操作，详见配置 TOS 数据源。
  • 运行任务的资源组能够访问 TOS Endpoint。
  • 访问凭证具备读取、写入或删除对象所需的最小权限。
  • 已确认文件格式、字段分隔符、压缩方式和目标路径符合业务要求。

2 新建任务

TOS 数据源测试连通性成功后，进入数据开发界面，开始新建 TOS 相关通道任务。新建任务方式详见离线数据同步、流式数据同步。
任务创建成功后，即可根据实际场景，配置 TOS 离线读、TOS 离线写或 TOS 流式写等通道任务。

3 配置离线集成任务

3.1 可视化配置 TOS 离线读

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

参数

说明

*数据源类型

下拉选择 TOS 数据源类型。

*数据源名称

已在数据源管理中注册成功的 TOS 数据源，下拉可选。
若还未建立相应数据源，可单击数据源管理按钮，前往创建 TOS 数据源。

*文件路径

填写需要采集的 TOS 数据文件所在路径，可在 TOS 中查看。

说明

  • 路径中包括 ^ , * , ? , [ , ] , { , } , ( , ) , \ 等符号，则会被判定为正则形式的路径。
  • 文件路径填写说明：
    • 不需要包含 Bucket 名称，且不用 / 开头，直接填写 Bucket 名称后的文件路径。如文件所在的完整路径为：tos://bucket-test/data/csv/zip/data1.zip，则您在 TOS 集成任务配置时，文件路径只需要填写 data/csv/zip/data1.zip 即可。
    • 可配置目录，可配置具体的文件名称。
      • 若配置目录，仅读取当前目录下的子文件，但不递归子目录。例如 data/csv/，若该目录下有子目录 data1、data2、data3，则只读取 data/csv/ 目录下的子文件，不递归子目录。
      • 若配置具体的文件，不支持 “.” 或 “_” 开头的文件名。
    • 支持 “*” 通配符形式配置文件路径信息，如data/csv/*.csv。
    • 支持配置日期正则参数形式，如 bigdata/t_user/${date}。
  • 当前仅支持读取 FNS（Flat Namespace，扁平命名空间） 类型的 TOS 桶。
  • 支持通过 Proton 加速引擎读取 TOS 数据。目前该能力以白名单形式进行控制，您可通过提工单方式联系我们开通。

*数据类型

支持选择 json、pb、parquet、csv、txt 等几种数据类型：

  • Parquet / Orc 类型：字段 Schema，可通过同名映射的方式配置。
  • Json 类型：
    数据类型为 json 时，需添加示例数据，以 json 字符串形式描述 schema，需填写完整的数据。例如：{"uid":123, "ut":12, "user_name": "xxx"}。 若没有示例数据，则 Schema 信息不准确，您需手动添加 Schema 字段映射配置。
  • csv、txt 类型：需添加分隔符、原始字符集、导入起始行参数：
    • 分隔符：选择原始文件的分隔符，如“,”、“Tab”、“;”等，下拉可选，同时也支持自定义分隔符的方式指定。
    • 原始字符集：需选择原始文件的字符集，支持选择 GBK、UTF-8 格式。
    • 导入起始行：无表头请填0，有表头请填1。
  • PB 类型：需填写 Pb 类定义和 Pb 类名信息。

    • Pb 类定义：
      输入 Pb 类定义文件信息，只支持一个 Pb 类定义，填写示例如下：

      syntax = "proto2";
package abase_test;
message AbaseTest {
required int64 first_id = 1;
required int64 latest_id = 2;
}

    • Pb 类名：Pb 类名需填写为 message 名称，例如上方定义的 Pb 类，对应 PB Class 为 AbaseTest。

3.2 可视化配置 TOS 离线写

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

参数

说明

*目标类型

下拉选择 TOS 数据源类型。

*数据源名称

已在数据源管理中注册成功的 TOS 数据源，下拉可选。
若还未建立相应数据源，可单击数据源管理按钮，前往创建 TOS 数据源。

*文件路径

填写需要写入的 TOS 数据文件所在路径，支持填写日期变量形式，如 ${date}，具体路径可在 TOS 中查看。

说明

文件路径填写说明：

  • 不需要包含 Bucket 名称，且不用 / 开头；
  • 支持配置日期正则参数形式，如 bigdata/t_user/${date}
  • 支持写入以下两种 TOS 桶类型。写入时会自动识别目标桶类型，无需手动指定。
    • FNS 桶：传统扁平命名空间桶，为默认桶类型。
    • HNS（Hierarchical NameSpace）桶：分层命名空间桶，提供高性能的目录级操作（Rename、List 等），适合大数据、数据湖场景。关于 HNS 桶的详细说明，请参见分层命名空间介绍。
  • 支持通过 Proton 加速引擎写入 TOS 数据。目前该能力以白名单形式进行控制，您可通过提工单方式联系我们开通。

*文件名前缀

输入 TOS 目标文件名的前缀信息，如填写 tos_writer，则生成的文件名会以 tos_writer 开头。
文件名自动生成规则如下：
filePrefix_{jobId}{subTaskId}{file_count}_{generate_timestamp}.{fileFormat}.{compression_suffix}

  • filePrefix：即您在输入框中输入的前缀信息；
  • jobId：当前任务 ID，可在调度设置 > 基本信息中查看；
  • subTaskId：并发 Task 的序号；
  • file_count：当前该 Task 写的第几个文件；
  • generate_timestamp：文件创建时间；
  • fileFormat：文件格式，即文本类型中选择的 csv、json、parquet、orc 等类型；
  • compresion_suffix：文件压缩格式，如 .gz、.snappy 等格式，其中压缩格式为 None 时，文件名中显示为空。

*文件名称冲突

依据实际业务场景，下拉选择数据写入时，针对文件名称冲突状况下的任务处理形式，仅支持以下处理方式：

  • 覆盖（替换原有文件）: 默认为覆盖方式，先删除原有数据再写入新数据；
    • 适用场景：每次全量同步，目标路径下只保留最新数据。

    说明

    覆盖策略需要 DeleteObject 权限。

*文本类型

支持选择 json、parquet、csv、orc 等几种数据类型：

  • json、parquet、orc 类型：无需填写其他配置信息。
  • csv 类型：需填写是否配置表头、分隔符信息：
    • 是否配置表头：根据实际情况，选择产出文件是否需要配置表头，若选择是，则默认将字段映射的所有字段配置为表头。
    • 分隔符：选择原始文件的分隔符，如“,”、“Tab”、“;”等，下拉可选，同时也支持自定义分隔符的方式指定。

*压缩格式

选择写入 TOS 中数据文件的压缩格式，支持选择 None、Snappy、Lz4、Gzip、Zstd 等压缩格式。

3.3 字段映射

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

注意

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

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

    配置节点

    说明

    来源节点

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

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

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

    数据转换

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

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

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

    目标节点

    配置目标节点 Sink 信息：

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

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

  • 基础模式：

    基础模式您可通过以下四种方式操作字段映射关系：

    • 自动添加：源端 TOS 数据类型为 csv、txt、json、pb 时，单击自动添加按钮，源端字段信息可通过自动添加按钮操作。
    • 同名映射：源端 TOS 数据类型为 Parquet 时，您可在配置完目标端字段信息后，单击源端字段映射中的同名映射按钮，进行同名字段映射配置。
    • 手动添加：单击手动添加按钮，可以手动编辑来源和目标的字段信息，可以逐个添加。
    • 移动\删除字段：您也可以根据需要移动字段映射顺序或删除字段。

注意

  • 在字段映射区域确认来源字段与目标字段的名称、顺序和类型。对于结构化文件，目标字段顺序必须与输出格式一致。
  • 当上游为 BMQ、RocketMQ、Kafka 等消息队列且目标为 TOS 时，可根据消息解析方式配置业务字段。使用 Kafka 原始二进制模式时，业务字段只配置一个 Binary 类型的 value，并将其映射到目标端同名字段。详细说明请参见配置 Kafka 任务。

4 配置流式集成任务

4.1 可视化配置 TOS 实时写

Image
流式集成任务实时写入 TOS 数据源，数据目标类型选择 TOS，并完成以下相关参数配置：
其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数。

参数

说明

*目标类型

下拉选择 TOS 数据源类型。

*数据源名称

已在数据源管理中注册成功的 TOS 数据源，下拉可选。
若还未建立相应数据源，可单击数据源管理按钮，前往创建 TOS 数据源。

*TOS 保存地址

填写需要写入数据的 TOS 存储路径信息。

说明

文件路径填写说明：

  • 不需要包含 Bucket 名称，且不用 / 开头；
  • 支持配置日期正则参数形式，如 bigdata/t_user/${date}
  • 支持写入 FNS、HNS 两种桶类型。写入时会自动识别，无需手动指定。

5 高级参数说明

  • 对于可视化通道任务，读参数需加上 job.reader. 前缀，写参数需加上 job.writer. 前缀。
  • 对于 DSL 任务，读参数请配置到 reader.parameter 下，写参数请配置到 writer.parameter 下，直接输入参数名称和参数值。

5.1 TOS 离线读常用参数

TOS 数据源常用的离线读高级参数整理如下：

参数名

描述

默认值

job.reader.enable_success_file_check

若任务中需要检查前置 Success 文件是否就绪，可添加该高级参数。设置为 true 时，表示开启 Success 文件检查，当检查的文件存在时，任务才会执行成功。默认 false，不检查。

false

job.reader.success_file_path

设置检查的 Success 文件全路径信息。

无

job.reader.success_file_check_interval_ms

设置检查 Success 文件时间间隔，单位毫秒。

60000

job.reader.success_file_check_times

设置 Success 文件检查次数。

60

job.reader.csv_delimiter_ascii

当 TOS 文件中的分隔符是不可见的 ASCII 字符时，可使用该高级参数，并将其设置为对应字符的 ASCII 码，如 job.reader.csv_delimiter_ascii=1,表示文件分隔符为不可见的控制字符 SOH。
该参数优先级高于界面设置的分隔符。

无

job.reader.compress_codec

TOS 读取压缩文件时需要配置该参数，可选值为 zip。

无

job.reader.s3a_endpoint

覆盖默认的 TOS Endpoint，用于连接其他 S3 兼容对象存储。

无

job.reader.s3a_path_style_access

是否使用 Path-Style 访问模式（适用于部分自建 MinIO）。

false

5.2 TOS 离线写常用参数

TOS 数据源常用的离线写高级参数整理如下：

参数名

描述

默认值

job.writer.s3a_endpoint

覆盖默认的 TOS Endpoint，用于连接其他 S3 兼容对象存储。

无

job.writer.s3a_path_style_access

是否使用 Path-Style 访问模式。

false

job.writer.rolling.inactivity_interval

设置持续无写入时的文件滚动间隔，单位为毫秒。
例如，设置值为 1800000，表示持续 30 分钟无写入后滚动文件。

无

job.writer.rolling.max_part_size

设置单个 part 的最大大小，单位为字节。
例如，设置值为 536870912，表示单个 part 达到 512 MiB 后滚动。

无

6 最佳实践

6.1 文件格式选择建议

场景

推荐格式

压缩格式

原因

结构化大数据量（>1GB）

Parquet

Snappy

列式存储，读取效率高，压缩比好。

数据交换/人可读

CSV

Gzip

通用格式，兼容性最好。

嵌套/半结构化数据

JSON

Gzip

支持嵌套结构。

日志类数据写入

JSON / CSV

Lz4

写入快，Lz4 压缩速度最快。

存档/冷数据

Parquet / ORC

Zstd

最高压缩比。

6.2 大文件同步性能优化

优化项

建议

文件拆分

单个文件建议不超过 1GB，拆分为多个小文件可提升并发效率。

并发数

文件数量决定最大并发度，单文件不支持多线程，多文件场景可适当提高并发数。

压缩选择

读取时 Snappy/Lz4 解压最快；写入时 Gzip 压缩比最优。

Success 文件

上游 ETL 产出数据后放置 Success 标记文件，DataSail 侧开启 enable_success_file_check，确保数据就绪。

6.3 增量同步方案

TOS 为文件存储系统，不支持行级增量。推荐的增量方案：

  • 方式一：基于日期分区目录

    # 文件路径使用日期变量
data/orders/${date}/

# 每天只读取当天目录下的新文件

  • 方式二：Success 文件检查 + 目录约定

    # 高级参数配置
job.reader.enable_success_file_check = true
job.reader.success_file_path = data/orders/${date}/_SUCCESS

6.4 生产环境检查清单

  • AK/SK 遵循最小权限原则（只读场景不赋予写权限）。
  • 存储桶配置了合适的生命周期策略（避免历史文件无限增长）。
  • 大文件已拆分为合理大小（单文件 < 1GB）。
  • CSV/TXT 文件的分隔符在数据内容中不会出现。
  • 增量场景已配置日期变量或 Success 文件检查。
  • 跨云场景已验证 Endpoint 连通性和传输费用。
  • 已配置任务失败告警。

附录：常见问题 FAQ

Q1：TOS 读取时报"Access Denied"怎么办？
A：请按以下顺序排查：

  1. 确认 AK/SK 对应的 IAM 用户是否具备目标 Bucket 的 tos:GetObject 和 tos:ListBucket 权限。
  2. 确认 Bucket 策略（Bucket Policy）是否限制了特定 IP 或 VPC 的访问。
  3. 确认 AK/SK 是否已过期或被禁用。
  4. 如果是子用户，确认主账号是否已正确授权。

Q2：读取 CSV 文件时字段错位（数据串行）怎么办？
A：字段错位的常见原因：

  • 数据内容中包含了分隔符字符 → 修改分隔符为数据中不会出现的字符（如 \001），使用 job.reader.csv_delimiter_ascii=1 配置。
  • 数据内容中包含换行符 → 对源数据做预处理，去除字段内的换行符。
  • 编码格式不匹配 → 确认原始字符集选择正确（UTF-8 或 GBK）。

Q3：连接 S3/OSS/COS 时连通性测试通过但任务运行失败？
A：这是因为连接串方式的连通性测试验证的是火山引擎 TOS 的连通性，不会验证自定义的 s3a_endpoint。解决方案：

  1. 确认高级参数 job.reader.s3a_endpoint（或 job.writer.s3a_endpoint）配置正确。
  2. 确认独享集成资源组已开通公网访问能力。
  3. 确认目标云平台的 AK/SK 有效且权限充足。
  4. 如果是自建 MinIO，检查是否需要配置 s3a_path_style_access=true。

Q4：写入 TOS 后文件名很长且包含乱码怎么调整？
A：TOS Writer 的文件名由系统自动生成，格式为 {filePrefix}_{jobId}{subTaskId}{file_count}_{timestamp}.{format}.{compression}。建议：

  • 设置有业务含义的 文件名前缀（如 orders_daily）。
  • 文件名中的 jobId 和 timestamp 用于保证唯一性，无法去除。
  • 如果需要特定文件名，可在下游通过脚本重命名。

Q5：如何从 TOS 读取 ZIP 压缩文件？
A：需要在高级参数中配置 job.reader.compress_codec=zip。

注意

  • 压缩文件不支持多线程并发读取。
  • ZIP 包内的文件格式需要与配置的数据类型一致。

Q6：跨云传输（如 TOS → S3）的数据量很大，如何优化传输效率？
A：

  • 尽量使用高压缩比格式（Parquet + Snappy / Gzip），减少传输数据量。
  • 将大文件拆分为多个小文件，提高并发度。
  • 考虑在目标云的同 Region 部署中转节点，减少跨区域流量。
  • 评估公网带宽限制，必要时申请带宽扩容。
最近更新时间：2026.09.18 15:23:44
这个页面对您有帮助吗？
有用
有用
无用
无用