文档反馈
问问助手FTP（File Transfer Protocol）是用于网络文件传输的一套标准协议，使用 TCP 进行传输。
SFTP（SSH File Transfer Protocol）与 FTP 有着几乎一样的语法和功能，但其通过 SSH 协议在客户端与服务端之间建立连接加密传输认证信息和数据，在安全性方面比FTP更强。
FTP/SFTP 数据源为您提供读取 FTP/SFTP 数据的单向通道能力，实现从 FTP/SFTP 读取数据，写入到不同目标数据源中，进行数据传输。
本文将为您介绍 DataSail 中 FTP/SFTP 数据源的数据同步能力支持情况。
1 前置知识
FTP 协议支持以下两种连接模式：
- pasv 模式：FTP 客户端首先和服务器的 TCP 21 端口建立连接，用来发送命令。建立连接后发送 PASV 命令。服务器收到 PASV 命令后，打开一个临时端口（端口号大于 1023 小于 65535），并且通知客户端在这个端口上传送数据的请求，客户端连接 FTP 服务器此端口，然后 FTP 服务器将通过这个端口传送数据。
- port 模式：FTP 客户端首先和服务器的 TCP 21 端口建立连接，用来发送命令。客户端需要接收数据的时候在这个通道上发送 PORT 命令。PORT 命令包含了客户端用什么端口接收数据。在传送数据的时候，服务器端通过自己的 TCP 20 端口连接至客户端的指定端口发送数据。FTP server 必须和客户端建立一个新的连接用来传送数据。
2 使用限制
- 确保同步任务使用的独享集成资源组具有 FTP/SFTP 数据源服务器的网络访问能力：
- FTP 网络要求：
- 确保 FTP 端口（默认 21）在 FTP 服务器的防火墙中已开放；
- 所有 FTP 服务都支持 PORT 连接方式。若使用 PASV 连接，需提前确认 FTP 服务是否支持；
- 为了 PASV 连接能够正常工作，需提前确认 FTP 服务器上 PASV 指定的端口范围在防火墙中已开放。
- 如果独享集成资源组未开通公网，FTP 服务器无法向资源组主动建立连接，所以这种情况下只能选择 PASV 模式。
- 如果独享集成资源组开启了公网，并且使用 PORT 方式连接时，需确保资源组所在网络安全组打开了 1024 以上端口的访问，因为 PORT 模式建立数据链路时是由 FTP 服务器向资源组发送连接请求。
- FTP 网络要求：
- FTP/SFTP Reader 支持读取 CSV、TXT 和 JSON 几种格式的远程文件。
- Json：要求文件内每行为一个Json数据，key字段大小写敏感
- CSV：单条记录按行分隔，单条记录内部默认按英文逗号分隔（可更改行内分隔符）
- TXT：文本文件，单条记录按行分隔，单条记录内部可配置常用分隔符(如逗号、空格等)或自定义分隔符，支持 GBK 和 UTF-8 字符集。
- 多个文件支持并发读取，单个文件只能单并发读取。
3 支持的字段类型
FTP/SFTP 离线读支持的字段数据类型如下：
类型分类 | 数据集成 column 配置类型 |
|---|---|
整数类 | tinyint、int、bigint |
浮点类 | float、double、decimal |
字符串类 | string |
时间类 | date、timestamp |
布尔类 | boolean |
数组类 | array |
字典类 | map |
二进制类型 | binary |
4 数据同步任务开发
4.1 数据源注册
新建数据源操作详见配置数据源，以下为您介绍连接串方式配置的 FTP/SFTP 数据源相关信息：
其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数。
参数 | 说明 |
|---|---|
基本配置 | |
*数据源类型 | FTP/SFTP |
*接入方式 | 连接串 |
*数据源名称 | 数据源的名称，可自行设置，仅支持中文，英文，数字，“_”，100个字符以内。 |
参数配置 | |
*Host | 连接 FTP/SFTP 时，使用的主机名或IP地址。 |
*Port | FTP/SFTP 协议配置的端口号：
|
*用户名 | 访问 FTP/SFTP 协议时的登录用户名信息。 |
*密码 | 访问 FTP/SFTP 协议时的密码信息。 |
*协议类型 | 目前支持 FTP、SFTP 协议。 |
*连接模式 | 当选择 FTP 协议时，需选择连接模式，支持选择 pasv、port 两种连接模式。 |
4.2 新建离线任务
FTP/SFTP 数据源测试连通性成功后，进入到数据开发界面，开始新建 FTP/SFTP 相关通道任务。新建任务方式详见离线数据同步。
任务创建成功后，您可根据实际场景，配置 FTP/SFTP 离线读通道任务。
4.3 可视化配置 FTP/SFTP 离线读
数据来源选择 FTP/SFTP，并完成以下相关参数配置：
其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数。
参数 | 说明 |
|---|---|
*数据源类型 | 下拉选择 FTP/SFTP 数据源类型。 |
*数据源名称 | 已在数据源管理中注册成功的 FTP/SFTP 数据源，下拉可选。 |
*文件路径 | 填写需要采集的 FTP/SFTP 数据文件所在路径：
|
*数据类型 | 支持选择 csv、json、txt 几种数据格式:
|
*Success 标签检测 | 根据实际情况，选择是否开启 Success 标签检测。
|
4.4 字段映射
可视化离线读 FTP/SFTP，数据来源和目标端配置完成后，需要指定来源和目标端的字段映射关系，根据字段映射关系，数据集成任务将源端字段中的数据，写入到目标端对应字段中。
您可通过以下三种方式操作字段映射关系：
- 同名映射：您可在配置完目标端字段信息后，单击源端字段映射中的同名映射按钮，进行同名字段映射配置。
- 自动添加：单击自动添加按钮，根据两端数据表信息，可以自动填充来源和目标的字段信息。
- 手动添加：单击手动添加按钮，可以手动编辑来源和目标的字段信息，可以逐个添加。
- 移动\删除字段：您也可以根据需要移动字段映射顺序或删除字段。
4.5 DSL 任务模板配置
目前暂时不支持 FTP/SFTP 数据源，通过脚本模式（DSL）模式配置任务。
5 可选高级参数
5.1 FTP/SFTP 离线读
对于可视化通道任务，高级参数可在任务开发界面：任务运行参数 > 自定义参数设置中填写，读参数需要加上 job.common.:
JSON 数据格式相关参数：
参数
描述
默认值
job.common.case_insensitive
JSON 内容解析时是否对字段 Key 大小写敏感。
true
job.common.support_json_path
是否支持带
.的字段名。true 为支持，false 为不支持。false
job.common.json_serializer_features
Datasail 使用 fastjson 解析 JSON 内容，用户可以通过此参数设置 JSON 解析的 features，详情参考 SerializerFeature - fastjson 1.2.83 javadoc。多个 SerializerFeature 使用逗号分隔。
无
job.common.convert_error_column_as_null
是否将类型转化失败的字段默认置为 null。
false
CSV、TXT 数据格式相关参数：
参数
描述
默认值
job.common.csv_escape
CSV 的 escape 字符
无
job.common.csv_quote
CSV 的 quote 字符
无
job.common.csv_with_null_string
将 CSV 中的这个字段值视为 null
无
其余参数：
参数
描述
默认值
job.reader.skip_if_path_not_exists
当 FTP/SFTP 上读取的文件不存在时，是否跳过该文件。默认不跳过，任务失败。
您可根据实际场景设置该参数为 true，则会跳过该文件，任务仍能够执行成功。设置格式如下：job.reader.skip_if_path_not_exists=truefalse