作者：终古

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 字段类型映射

使用数据集成支持的数据类型

5 特别注意

5.1 读取数据一致性约束

• • 任务在执行开始时扫描待读取的文件，任务执行期间将不再实时扫描是否由新增文件
  • 如果在任务执行期间，扫描到的文件被删除则会报错

5.2 数据库编码

支持指定编码读取ftp文件，确保与写入时的编码一致，否则会乱码

6 最佳实践

csvReader

1. 准备数据

可以看下数据特征：

• 第一行第二列两边存在双引号，要求去掉双引号
• 第二行第二列前面有空白符，要求去掉

1. 使用csvReader加上高级配置即可：

注意：csvReaderConfig默认useTextQualifier为true，textQualifier为双引号",trimWhitespace为true因此可以不配置，因此上面两个配置效果等价。

1. 预览结果

第一列第二行双引号已去除，第二行第二列前面空白符去除。

textReader

1. 准备数据

查看数据特征：

• 第一行第二列是个json字符串，要求能正常读取
• 第二行第二列前面有空格，要求去掉，
• 列分隔符是@，注意，对于文本数据，列内容不能存在与列分隔符相同的字符。

1. 使用textReader

1. 数据预览

可以看到，符合预期。

PS：如果你的json数据中不存在与列分隔符相同的字符，那一般情况下，也是可以直接使用csvReader的

textReader & csvReader

1. 准备数据

数据特征：

1. 第一行第二列存在单个双引号，是数据内容，需要保留，由于csvReader默认的限定符是双引号，所以默认情况下，使用csvReader一定会报错。
2. 第二行第二列前面存在空白符
3. 使用textReader

1. csvReader

对于这种情况，说明列内容可能会存在不确定的其他字符，可能会与默认的限定符冲突，因此需要关闭csvReader的限定符开关。

1. 数据预览