二、适用场景
·周期性接入业务伙伴上传到 FTP / SFTP / COS 的批量文件，落入数据湖仓供下游分析。
·接入第三方 SaaS 系统通过 REST API 提供的数据。
·增量同步对象存储中按日期分区的文件。
三、前提条件
在开始本操作前，请确保满足以下条件：
·已开通 DataBuddy 服务并完成空间初始化。
·当前账号在目标 Workspace 中拥有 数据接入相关角色 （详见 成员与权限管理）。
·已创建用于数据接入的计算资源（数据接入型）。
·已创建并测试通过来源端数据源连接（详见 添加数据源连接）。
·目标 Catalog 与 Schema 已规划好；如目标表不存在，可由本任务一键建表（需要建表权限）。
四、使用限制
| 限制项 | 说明 |
| 来源端类型 | 半结构化数据源（FTP / SFTP / COS / HDFS / REST API 等） |
| 目标端类型 | DataBuddy Catalog 下的表（Iceberg 原生表） |
| 读取方式 | 仅 解析数据 （解析后入表）；如需保留原始文件结构请使用 文件到 Volume 同步 |
| 文件路径 | 路径下无文件或仅有空文件时任务正常运行成功，但目标端无新增数据 |
| 字段映射 | 来源端不读取字段元数据，需要用户手动添加字段并指定类型 |
五、操作步骤
通用流程同 表到表同步。本节仅说明来源端 与字段映射 的差异。
六、步骤 1：进入任务创建页、填写基础信息
参见 表到表同步。
七、步骤 2：配置来源端
按所选数据源类型，来源端配置项略有差异。
八、通用字段（FTP / SFTP / COS / HDFS）
| 参数 | 说明 | 是否必填 |
| 数据源类型 | 选择来源数据源类型 | 是 |
| 源连接 | 选择已注册的数据源连接 | 是 |
| 文件路径 | 文件或文件夹路径；点击文件夹图标可弹出路径选择器逐层下钻；支持插入参数与正则； | 是 |
| 读取方式 | 解析数据 ：解析文件入表；原始文件 ：原样落 Volume（属于 文件到 Volume 同步） | 是 |
| 文件格式 | 数据同步模式下选择 Text/CSV/JSON/ORC/Parquet | 是 |
| 格式设置 | 按文件类型展示对应字段； | 视文件类型 |
| 高级设置 | 数据源专属扩展参数 | 否 |
九、REST API
| 参数 | 说明 | 是否必填 |
| 数据源类型 | REST API | 是 |
| 数据源连接 | 选择已注册的 API 数据源 | 是 |
| 读取方式 | 解析数据 ：解析结构化数据内容，按字段关系进行数据内容映射与同步; 原始文件 ：不做内容解析传输整个文件，可应用于非结构化数据同步 | 是 |
| 请求方式 | GET / POST | 是 |
| 数据路径 | 接口返回中数据所在 JSON 路径（如 data.list） | 否 |
| 返回结构 | 单条 JSON / 数组 JSON | 是 |
| 请求 Header | 自定义请求头 | 否 |
| 请求参数 | GET 查询参数或 POST 请求体参数 | 否 |
| 第一行作为字段 | 当返回为表格类结构时是否将首行作为字段名 | 否 |
| 高级设置 | 请求方式 ：单次请求 / 多次请求；参数 ：分页参数等 | 否 |
十、步骤 3：解析配置（按文件类型）
| 文件类型 | 关键配置 |
| Text | 列分隔符（自定义 / ; / | / Tab）、行分隔符（自定义 / 回车 / 断行）、第一行作为字段行、转义字符（默认 \\） |
| CSV | 列分隔符（自定义 / , / ; / Tab）、转义符（" / \\）、第一行作为字段名、行跨行 |
| JSON | 将时间文本转换为时间类型、允许使用单引号、过滤注释、行跨行当存在 JSON 嵌套时，嵌套的值会被解析为一个文本对象（不会自动展开为多列）。 |
| ORC / Parquet | 无需额外配置（自描述格式） |
十一、步骤 4：配置目标端
目标端配置项与 表到表同步 完全一致：
·目标 Catalog / Schema / Table。
·写入模式：append / overwrite / upsert。
十二、步骤 5：配置字段映射
| 链路 | 来源端字段映射 | 目标端字段映射 |
| 文件（解析） → 表 | 可设置（需手动添加字段） | 可设置 |
文件类型的来源端不读取字段元数据 ，需要用户手动添加字段：
1. 点击 添加字段 ，输入字段索引值，如输入 0，表示读取出来的第一个元素，注意是从 0 开始检索的。
2. 选择字段类型（支持 STRING / INT / BIGINT / FLOAT / DOUBLE / DECIMAL / DATE / TIMESTAMP / BOOLEAN 等）。
3. 与目标端字段建立映射。
操作支持：清除、置顶已映射、刷新字段。
十三、步骤 6：运行设置、调试、保存、发布
参见 表到表同步。
十四、验证结果
任务保存并调试运行后，你可以通过以下方式确认：
1. 在数据接入任务列表中可以看到刚创建的任务。
2. 调试运行成功后，目标 Catalog 下对应表已包含解析后的数据；可在 数据目录 或 SQL 探索中查询验证。
3. 如需更细粒度的字段类型校验，可在 SQL 探索中运行 DESCRIBE 或简单查询观察实际写入字段。
十六、Q：上传的 CSV 文件包含表头，但映射结果将表头当作了数据行？
A：来源端的 CSV / TXT 解析配置中需勾选 第一行作为字段名 。
十七、Q：JSON 文件含嵌套对象，如何展开为多列？
A：当前 JSON 嵌套字段会整体解析为文本对象，不自动展开。如需展开，建议在 SQL 任务中使用 get_json_object / from_json 等函数后处理。
十八、Q：XML 行标签自动推断错误，如何手动指定？
A：在解析设置中，行标签字段输入正确的行标签名即可。例如 <root><record>…</record></root> 中行标签应为 record。
十九、Q：路径下没有文件，任务还会运行吗？
A：会，任务运行成功但目标端无新增数据 。
20、相关文档
·表到表同步
·文件到 Volume 同步
·批量创建单表同步任务
·离线同步任务运维监控
·本地上传到表（一次性手动上传场景）