作者：终古
1 组件说明
读取远程FTP文件系统数据。通过FTP、FTPS或者SFTP协议连接远程FTP文件系统，创建远程文件输入流进行数据拉取。
2 原理说明
远程FTP文件本身是无结构化数据存储，扫描远程FTP目录下的所有文件获取待读取的文件列表，根据不同的文件类型使用不同的读取方式，目前支持功能如下：
- 支持标准csv文件和纯文本文件
- 支持多种类型数据读取(使用String表示)，支持列裁剪
- 支持递归读取、支持文件名过滤。
- 支持文本压缩，现有压缩格式为zip、gzip、bzip2。
- 多个File可以支持并发读取。
读取文件方式有两种，一种是textReader，一种是csvReader。
- textReader
一种基于文件流的解析器，它的解析很简单，直接读取文件的每一行，然后使用配置的分隔符进行切分。它在切分过程支持几个特性（配置项）：
- skipEmptyRecords 是否跳过空行
- trimWhitespace 是否去除每列内容的前后空白符
- useTextQualifier 是否使用限定符
- textQualifier 配置限定符，读取后会去除限定符
- caseSensitive 限定符是否区分大小写
- 使用场景：
- 列内容是json的典型场景
- csvReader
一种开源的基于字符流的解析器，用于解析使用单字符分隔符分隔的字符流。因为是基于流的解析器，因此就存在很多规则，也就要求文件内容必须符合它的规则，否则会导致解析失败或者解析错误。但对于大部分普通的数据文件(即每列内容比较简单的文件，比如数字、日期以及没有特殊字符（与限定符冲突的字符，例如双引号""）的字符串),csvReader是比textReader性能快的，而且它支持指定行风格符。它在切分过程支持的几个特性：
- skipEmptyRecords 是否跳过空行
- trimWhitespace 是否去除每列内容的前后空白符
- useTextQualifier 是否使用限定符，默认使用
- textQualifier 配置限定符，读取后会去除限定符，但是要求限定符必须成对出现，如果只出现一个，那一定会导致读取错误，因此在文件中，若某列字符串存在不确定的限定符(默认双引号)，则不能使用csvReader模式，请使用textReader
- caseSensitive 限定符是否区分大小写
- recordDelimiter 行分隔符
- escapeMode 转义字符模式,一版都是推荐配置2，使用单斜杠表示转义
- 2: Use a backslash character before the text qualifier to represent an occurance of the text qualifier
- 1: Double up the text qualifier to represent an occurance of the text qualifier
- 使用场景：除了必须使用textReader的场景之外
那么，对于这两种读取方式，该如何配置来选择某种读取方式呢？在Dataphin的V297版本，我们新增了一个高级配置：
我们倾向于优先使用csvReader，因此只有如下配置时才会使用textReader，否则使用csvReader，即：
- 选择文件类型Text，且分隔符是多字符分隔符
- 选择文件类型Text，且配置了高级配置，且是textReaderConfig(不要求配置子项，配置一个空的textReaderConfig也可以，子项是根据自己的数据特征来配置的)
3 配置说明
- path
- 描述：远程FTP文件系统的路径信息，注意这里可以支持填写多个路径。
当指定单个远程FTP文件，FtpReader暂时只能使用单线程进行数据抽取。
当指定多个远程FTP文件，FtpReader支持使用多线程进行数据抽取。线程并发数通过通道数指定。
当指定通配符，FtpReader尝试遍历出多个文件信息。例如: 指定: /，代表读取/目录下所有的文件，指定：/bazhen/*，代表读取bazhen目录下游所有的文件。FtpReader目前只支持*作为文件通配符。
- 必选：是
- 默认值：无
- column
- 描述：读取字段列表，JSON对象数组
{ "index":0,// 该字段在文件中的第几列，基于0 "name":"字段名称", "type":"Long/Double/String/Date/Boolean/Bytes" }
- fieldDelimiter
- 描述：读取的字段分隔符
- 必选：是
- 默认值：,
- compress
- 描述：文本压缩类型，支持压缩类型为gzip、bzip2、zip等。
- 必选：否
- 默认值：没有压缩
- encoding
- 描述：读取文件的编码配置。
- 必选：否
- 默认值：utf-8
- fileFormat
- 描述：读取文件的格式，目前仅支持:csv/text
- 必选：是
- 默认值：无
- skipHeader
- 描述：类CSV格式和EXCEL文件可能存在表头为标题情况，需要跳过。默认不跳过，压缩文件模式下不支持skipHeader。
- 必选：否
- 默认值：false
- nullFormat
- 描述：文本文件中无法使用标准字符串定义null(空指针)，DataX提供nullFormat定义哪些字符串可以表示为null。例如如果用户配置: nullFormat:"\N"，那么如果源头数据是"\N"，将视作null字段。
- 必选：否
- 默认值：\N
- csvReaderConfig
- 描述：用于控制csv文件的读取
{ "recordDelimiter":"\u0000",// 配置行分格符，当文件内容不是以换行符换行时开启 "safetySwitch":false,// 是否限制行记录不大于10万字节 "skipEmptyRecords":true,//是否跳过空行，如果不跳过，则会产生一行每列都是空的记录 "trimWhitespace":true,// 是否去除每列前后的空白符 "useTextQualifier":true,//是否使用限定符,如果开启，默认双引号，则两个双引号内的任意内容视为一列，不管是否存在列分隔符 "textQualifier":"\"",// 配置限定符 "caseSensitive":true// 限定符是否区分大小写 }
- 必选：否
- 默认值：无
- textReaderConfig
- 描述：用于控制text文件的读取
{ "useTextQualifier":false,// 是否存在限定符 "textQualifier":"\"", "caseSensitive":true,//限定符是否区分大小写 "trimWhitespace":false//是否去除每列内容前后的空白符 }
- 必选：否
- 默认值：无
4 字段类型映射
使用数据集成支持的数据类型
数据集成 内部类型 |
Long |
Double |
String |
Date |
Boolean |
Bytes |
5 特别注意
5.1 读取数据一致性约束
- 任务在执行开始时扫描待读取的文件，任务执行期间将不再实时扫描是否由新增文件
- 如果在任务执行期间，扫描到的文件被删除则会报错
5.2 数据库编码
支持指定编码读取ftp文件，确保与写入时的编码一致，否则会乱码
6 最佳实践
csvReader
- 准备数据
可以看下数据特征：
- 第一行第二列两边存在双引号，要求去掉双引号
- 第二行第二列前面有空白符，要求去掉
- 使用csvReader加上高级配置即可：
注意：csvReaderConfig默认useTextQualifier为true，textQualifier为双引号",trimWhitespace为true因此可以不配置，因此上面两个配置效果等价。
- 预览结果
第一列第二行双引号已去除，第二行第二列前面空白符去除。
textReader
- 准备数据
查看数据特征：
- 第一行第二列是个json字符串，要求能正常读取
- 第二行第二列前面有空格，要求去掉，
- 列分隔符是@，注意，对于文本数据，列内容不能存在与列分隔符相同的字符。
- 使用textReader
- 数据预览
可以看到，符合预期。
PS：如果你的json数据中不存在与列分隔符相同的字符，那一般情况下，也是可以直接使用csvReader的
textReader & csvReader
- 准备数据
数据特征：
- 第一行第二列存在单个双引号，是数据内容，需要保留，由于csvReader默认的限定符是双引号，所以默认情况下，使用csvReader一定会报错。
- 第二行第二列前面存在空白符
- 使用textReader
- csvReader
对于这种情况，说明列内容可能会存在不确定的其他字符，可能会与默认的限定符冲突，因此需要关闭csvReader的限定符开关。
- 数据预览
