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/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 协议配置的端口号：
	* SFTP 默认使用 22 端口传输；
	* FTP 默认使用 21 端口传输。
*用户名	访问 FTP/SFTP 协议时的登录用户名信息。
*密码	访问 FTP/SFTP 协议时的密码信息。
*协议类型	目前支持 FTP、SFTP 协议。
*连接模式	当选择 FTP 协议时，需选择连接模式，支持选择 pasv、port 两种连接模式。
	不同网络要求，可选择不同的连接模式，限制要求详见“2 使用限制”。

4.2 新建离线任务

FTP/SFTP 数据源测试连通性成功后，进入到数据开发界面，开始新建 FTP/SFTP 相关通道任务。新建任务方式详见离线数据同步。
任务创建成功后，您可根据实际场景，配置 FTP/SFTP 离线读通道任务。

4.3 可视化配置 FTP/SFTP 离线读

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

| | | \

参数	说明
*数据源类型	下拉选择 FTP/SFTP 数据源类型。
*数据源名称	已在数据源管理中注册成功的 FTP/SFTP 数据源，下拉可选。
	若还未建立相应数据源，可单击数据源管理按钮，前往创建 FTP/SFTP 数据源。
*文件路径	填写需要采集的 FTP/SFTP 数据文件所在路径：
	* 支持填写多个文件，以英文逗号分隔，例如 /csv/data1.txt,/csv/data2.txt
	* 支持填写正则匹配方式，例如 /csv/${date}*.txt
	* 支持读取目录（会读取目录下的所有文件），例如 /csv/
*数据类型	支持选择 csv、json、txt 几种数据格式:
	* csv、txt 数据类型：数据类型选择 csv、txt 时，需填写分隔符、原始字符集、导入起始行。
	* 分隔符：需选择文件内的分隔符，下拉可选。
	* 原始字符集：需选择原始文件的字符集，支持选择 UTF-8、GBK 格式。
	* 导入起始行：选择起始行从哪一行开始导入，若起始行为 1，则从文件第一行开始读取数据，因此如果要跳过前 N 行数据，将此参数置为 N+1 即可。
	* Json 数据类型：数据类型选择 json 时，需填写示例数据用于自动生成 Schema 配置。
	* 示例数据：以 json 字符串形式描述 Schema，需填写完整的数据，例如：{"uid":123, "ut":12, "user_name": "xxx"}。若没有示例数据，则 Schema 信息不准确，您需手动添加 Schema 字段映射配置。
*Success 标签检测	根据实际情况，选择是否开启 Success 标签检测。
	若开启检测 Success 标签后，success_file_path 下必须有 _success 文件存在才会执行任务，若 _success 文件不存在会抛 runtime 异常，终止执行程序。且开启后，需配置以下信息：
	1. Success 标签路径：支持自定义标签文件路径，如：/var/ftp/test001/_success.csv
	2. 超时时间：客户端单次请求超时时间，单位ms。
	3. 重试次数：检查 success 标签重试次数，默认 60次，每次间隔 1分钟，最大值为 1440 即 24小时。

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=true	false