SFTP 出站网关

SFTP 出站网关提供了一组有限的命令，允许您与远程 SFTP 服务器交互

  • ls (列出文件)

  • nlst (列出文件名)

  • get (检索文件)

  • mget (检索多个文件)

  • rm (删除文件)

  • mv (移动和重命名文件)

  • put (发送文件)

  • mput (发送多个文件)

使用 ls 命令

ls 命令列出远程文件并支持以下选项

  • -1: 检索文件名列表。默认是检索 FileInfo 对象列表

  • -a: 包含所有文件（包括以 '.' 开头的文件）

  • -f: 不对列表进行排序

  • -dirs: 包含目录（默认排除）

  • -links: 包含符号链接（默认排除）

  • -R: 递归列出远程目录

此外，还提供了与 inbound-channel-adapter 类似的文件名过滤功能。

ls 操作产生的消息有效载荷是文件名列表或 FileInfo 对象列表（取决于您是否使用 -1 选项）。这些对象提供修改时间、权限等信息。

ls 命令操作的远程目录会放在 file_remoteDirectory 头部。

使用递归选项 (-R) 时，fileName 会包含任何子目录元素，并表示文件的相对路径（相对于远程目录）。如果您使用 -dirs 选项，每个递归目录也会作为列表中的一个元素返回。在这种情况下，我们建议您不要使用 -1 选项，因为那样您将无法区分文件和目录，而使用 FileInfo 对象时可以做到这一点。

如果列出的远程路径以 / 符号开头，SFTP 会将其视为绝对路径；否则，将其视为当前用户主目录中的相对路径。

使用 nlst 命令

版本 5 引入了对 nlst 命令的支持。

nlst 列出远程文件名并仅支持一个选项

  • -f: 不对列表进行排序

nlst 操作产生的消息有效载荷是文件名列表。

file_remoteDirectory 头部保存了 nlst 命令操作的远程目录。

SFTP 协议本身不提供列出名称的功能。此命令等同于带有 -1 选项的 ls 命令，此处添加是为了方便。

使用 get 命令

get 检索远程文件并支持以下选项

  • -P: 保留远程文件的时间戳。

  • -stream: 将远程文件检索为流。

  • -D: 传输成功后删除远程文件。如果传输被忽略，则不删除远程文件，因为 FileExistsMode 为 IGNORE 且本地文件已存在。

file_remoteDirectory 头部保存远程目录，file_remoteFile 头部保存文件名。

get 操作产生的消息有效载荷是一个表示已检索文件的 File 对象。如果您使用 -stream 选项，有效载荷将是 InputStream 而不是 File。对于文本文件，一个常见的使用场景是将此操作与文件拆分器或流转换器结合使用。将远程文件作为流消费时，您有责任在流消费后关闭 Session。为了方便，Session 会提供在 closeableResource 头部，并且 IntegrationMessageHeaderAccessor 提供了便捷方法

Closeable closeable = new IntegrationMessageHeaderAccessor(message).getCloseableResource();
if (closeable != null) {
    closeable.close();
}

框架组件，例如文件拆分器和流转换器，在数据传输后会自动关闭会话。

以下示例展示了如何将文件作为流进行消费

<int-sftp:outbound-gateway session-factory="ftpSessionFactory"
                            request-channel="inboundGetStream"
                            command="get"
                            command-options="-stream"
                            expression="payload"
                            remote-directory="ftpTarget"
                            reply-channel="stream" />

<int-file:splitter input-channel="stream" output-channel="lines" />
如果您在自定义组件中消费输入流，则必须关闭 Session。您可以在自定义代码中执行此操作，或者将消息的副本路由到 service-activator 并使用 SpEL，如下例所示 
<int:service-activator input-channel="closeSession"
    expression="headers['closeableResource'].close()" />

使用 mget 命令

mget 根据模式检索多个远程文件，并支持以下选项

  • -P: 保留远程文件的时间戳。

  • -R: 递归检索整个目录树。

  • -x: 如果没有文件匹配模式，则抛出异常（否则返回空列表）。

  • -D: 传输成功后删除每个远程文件。如果传输被忽略，则不删除远程文件，因为 FileExistsMode 为 IGNORE 且本地文件已存在。

mget 操作产生的消息有效载荷是一个 List<File> 对象（即 File 对象的 List，每个对象代表一个已检索文件）。

从版本 5.0 开始，如果 FileExistsMode 是 IGNORE，输出消息的有效载荷将不再包含因文件已存在而未获取的文件。之前，数组包含所有文件，包括已存在的文件。

您用于确定远程路径的表达式应该产生一个以 * 结尾的结果，例如 myfiles/* 会获取 myfiles 下的完整树。

从版本 5.0 开始，您可以结合递归 MGET 和 FileExistsMode.REPLACE_IF_MODIFIED 模式，定期将整个远程目录树同步到本地。此模式会将本地文件的最后修改时间戳设置为远程文件的时间戳，而不管 -P（保留时间戳）选项如何。

使用递归 (-R) 时的注意事项

模式将被忽略，并假定为 *。默认情况下，检索整个远程树。但是，您可以通过提供 FileListFilter 来过滤树中的文件。您也可以通过这种方式过滤树中的目录。FileListFilter 可以通过引用或通过 filename-pattern 或 filename-regex 属性提供。例如，filename-regex="(subDir|.*1.txt)" 会检索远程目录和子目录 subDir 中所有以 1.txt 结尾的文件。但是，在本注释之后，我们将描述另一种可用的替代方法。

如果您过滤一个子目录，则不会对该子目录进行额外的遍历。

不允许使用 -dirs 选项（递归 mget 使用递归 ls 来获取目录树，且目录本身不能包含在列表中）。

通常，您会在 local-directory-expression 中使用 #remoteDirectory 变量，以便在本地保留远程目录结构。

持久化文件列表过滤器现在具有布尔属性 forRecursion。将此属性设置为 true，也会设置 alwaysAcceptDirectories，这意味着出站网关（ls 和 mget）上的递归操作现在每次都会始终遍历完整的目录树。这是为了解决未检测到目录树深层变化的问题。此外，forRecursion=true 会导致使用文件的完整路径作为元数据存储键；这解决了如果相同名称的文件出现在不同目录中多次时过滤器无法正常工作的问题。重要提示：这意味着对于顶级目录下的文件，持久化元数据存储中的现有键将无法找到。因此，该属性默认为 false；这可能会在未来版本中更改。

从版本 5.0 开始，您可以通过将 alwaysAcceptDirectorties 设置为 true 来配置 SftpSimplePatternFileListFilter 和 SftpRegexPatternFileListFilter 始终通过目录。这样做允许简单模式下的递归，如下例所示

<bean id="starDotTxtFilter"
            class="org.springframework.integration.sftp.filters.SftpSimplePatternFileListFilter">
    <constructor-arg value="*.txt" />
    <property name="alwaysAcceptDirectories" value="true" />
</bean>

<bean id="dotStarDotTxtFilter"
            class="org.springframework.integration.sftp.filters.SftpRegexPatternFileListFilter">
    <constructor-arg value="^.*\.txt$" />
    <property name="alwaysAcceptDirectories" value="true" />
</bean>

您可以通过在网关上使用 filter 属性来提供这些过滤器之一。

另请参见出站网关部分成功（mget 和 mput）。

使用 put 命令

put 将文件发送到远程服务器。消息的有效载荷可以是 java.io.File、byte[] 或 String。使用 remote-filename-generator（或表达式）来命名远程文件。其他可用属性包括 remote-directory、temporary-remote-directory 及其 *-expression 等价物：use-temporary-file-name 和 auto-create-directory。有关详细信息，请参见schema 文档。

put 操作产生的消息有效载荷是一个 String，其中包含传输后文件在服务器上的完整路径。

版本 4.3 引入了 chmod 属性，它在上传后更改远程文件权限。您可以使用传统的 Unix 八进制格式（例如，600 仅允许文件所有者读写）。使用 Java 配置适配器时，可以使用 setChmod(0600)。

使用 mput 命令

mput 将多个文件发送到服务器，并支持以下选项

  • -R: 递归 — 发送目录和子目录中所有文件（可能已过滤）

消息有效载荷必须是表示本地目录的 java.io.File（或 String）。从版本 5.1 开始，也支持 File 或 String 的集合。

支持与put 命令相同的属性。此外，您可以使用 mput-pattern、mput-regex、mput-filter 或 mput-filter-expression 之一过滤本地目录中的文件。只要子目录本身通过过滤器，过滤器就可以与递归一起使用。未通过过滤器的子目录不会被递归。

mput 操作产生的消息有效载荷是一个 List<String> 对象（即传输后生成的远程文件路径的 List）。

另请参见出站网关部分成功（mget 和 mput）。

版本 4.3 引入了 chmod 属性，它允许您在上传后更改远程文件权限。您可以使用传统的 Unix 八进制格式（例如，600 仅允许文件所有者读写）。使用 Java 配置适配器时，可以使用 setChmodOctal("600") 或 setChmod(0600)。

使用 rm 命令

rm 命令没有选项。

如果删除操作成功，结果消息有效载荷为 Boolean.TRUE。否则，消息有效载荷为 Boolean.FALSE。file_remoteDirectory 头部保存远程目录，file_remoteFile 头部保存文件名。

使用 mv 命令

mv 命令没有选项。

expression 属性定义“来源”路径，rename-expression 属性定义“目标”路径。默认情况下，rename-expression 是 headers['file_renameTo']。此表达式不得评估为 null 或空 String。如果需要，将创建所需的任何远程目录。结果消息的有效载荷是 Boolean.TRUE。file_remoteDirectory 头部保存原始远程目录，file_remoteFile 头部保存文件名。file_renameTo 头部保存新路径。

从版本 5.5.6 开始，remoteDirectoryExpression 可以方便地用于 mv 命令。如果“来源”文件不是完整的文件路径，则 remoteDirectoryExpression 的结果将用作远程目录。这同样适用于“目标”文件，例如，如果任务只是重命名某个目录中的远程文件。

附加命令信息

get 和 mget 命令支持 local-filename-generator-expression 属性。它定义了一个 SpEL 表达式，用于在传输过程中生成本地文件的名称。评估上下文的根对象是请求消息。remoteFileName 变量也可用。它对 mget 特别有用（例如：local-filename-generator-expression="#remoteFileName.toUpperCase() + headers.foo"）。

get 和 mget 命令支持 local-directory-expression 属性。它定义了一个 SpEL 表达式，用于在传输过程中生成本地目录的名称。评估上下文的根对象是请求消息。remoteDirectory 变量也可用。它对 mget 特别有用（例如：local-directory-expression="'/tmp/local/' + #remoteDirectory.toUpperCase() + headers.myheader"）。此属性与 local-directory 属性互斥。

对于所有命令，网关的 'expression' 属性保存命令操作的路径。对于 mget 命令，表达式可能评估为 *（表示检索所有文件）、somedirectory/* 以及其他以 * 结尾的值。

以下示例展示了为 ls 命令配置的网关

<int-ftp:outbound-gateway id="gateway1"
        session-factory="ftpSessionFactory"
        request-channel="inbound1"
        command="ls"
        command-options="-1"
        expression="payload"
        reply-channel="toSplitter"/>

发送到 toSplitter 通道的消息的有效载荷是一个 String 对象列表，每个对象包含一个文件名。如果您省略了 command-options="-1"，有效载荷将是 FileInfo 对象列表。您可以将选项作为空格分隔的列表提供（例如，command-options="-1 -dirs -links"）。

从版本 4.2 开始，GET、MGET、PUT 和 MPUT 命令支持 FileExistsMode 属性（使用命名空间支持时为 mode）。这会影响本地文件存在（GET 和 MGET）或远程文件存在（PUT 和 MPUT）时的行为。支持的模式有 REPLACE（替换）、APPEND（追加）、FAIL（失败）和 IGNORE（忽略）。为了向后兼容，PUT 和 MPUT 操作的默认模式是 REPLACE。对于 GET 和 MGET 操作，默认模式是 FAIL。

使用 Java 配置进行配置

以下 Spring Boot 应用展示了如何使用 Java 配置出站网关的示例

@SpringBootApplication
public class SftpJavaApplication {

    public static void main(String[] args) {
        new SpringApplicationBuilder(SftpJavaApplication.class)
            .web(false)
            .run(args);
    }

    @Bean
    @ServiceActivator(inputChannel = "sftpChannel")
    public MessageHandler handler() {
        return new SftpOutboundGateway(ftpSessionFactory(), "ls", "'my_remote_dir/'");
    }

}

使用 Java DSL 进行配置

以下 Spring Boot 应用展示了如何使用 Java DSL 配置出站网关的示例

@SpringBootApplication
public class SftpJavaApplication {

    public static void main(String[] args) {
        new SpringApplicationBuilder(SftpJavaApplication.class)
            .web(false)
            .run(args);
    }

    @Bean
    public SessionFactory<SftpClient.DirEntry> sftpSessionFactory() {
        DefaultSftpSessionFactory sf = new DefaultSftpSessionFactory();
        sf.setHost("localhost");
        sf.setPort(port);
        sf.setUsername("foo");
        sf.setPassword("foo");
        factory.setTestSession(true);
        return new CachingSessionFactory<>(sf);
    }

    @Bean
    public QueueChannelSpec remoteFileOutputChannel() {
        return MessageChannels.queue();
    }

    @Bean
    public IntegrationFlow sftpMGetFlow() {
        return IntegrationFlow.from("sftpMgetInputChannel")
            .handle(Sftp.outboundGateway(sftpSessionFactory(),
                            AbstractRemoteFileOutboundGateway.Command.MGET, "payload")
                    .options(AbstractRemoteFileOutboundGateway.Option.RECURSIVE)
                    .regexFileNameFilter("(subSftpSource|.*1.txt)")
                    .localDirectoryExpression("'myDir/' + #remoteDirectory")
                    .localFilenameExpression("#remoteFileName.replaceFirst('sftpSource', 'localTarget')"))
            .channel("remoteFileOutputChannel")
            .get();
    }

}

出站网关部分成功（mget 和 mput）

在使用 mget 和 mput 对多个文件执行操作时，在传输一个或多个文件后可能发生异常。在这种情况下（从版本 4.2 开始），会抛出 PartialSuccessException。除了常规的 MessagingException 属性（failedMessage 和 cause）之外，此异常还有两个附加属性

  • partialResults: 成功的传输结果。

  • derivedInput: 从请求消息生成的的文件列表（例如用于 mput 的本地待传输文件）。

这些属性可让您确定哪些文件成功传输，哪些文件未成功传输。

在递归 mput 的情况下，PartialSuccessException 可能包含嵌套的 PartialSuccessException 实例。

考虑以下目录结构

root/
|- file1.txt
|- subdir/
   | - file2.txt
   | - file3.txt
|- zoo.txt

如果在 file3.txt 上发生异常，由网关抛出的 PartialSuccessException 的 derivedInput 将包含 file1.txt、subdir 和 zoo.txt，并且 partialResults 包含 file1.txt。它的 cause 是另一个 PartialSuccessException，该异常的 derivedInput 包含 file2.txt 和 file3.txt，并且 partialResults 包含 file2.txt。