You need to enable JavaScript to run this app.
导航
配置 FTP/SFTP 数据源
最近更新时间:2023.11.03 17:48:31首次发布时间:2023.11.03 17:48:31

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/

*数据类型

支持选择 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_insensitiveJSON 内容解析时是否对字段 Key 大小写敏感。true
    job.common.support_json_path是否支持带 . 的字段名。true 为支持,false 为不支持。false
    job.common.json_serializer_featuresDatasail 使用 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_escapeCSV 的 escape 字符
    job.common.csv_quoteCSV 的 quote 字符
    job.common.csv_with_null_string将 CSV 中的这个字段值视为 null