FTP 出站网关 (FTP Outbound Gateway) _ Spring Integration6.4.0-M3中文文档(官方文档中文翻译)|Spring 教程 —

此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Integration 6.3.4！spring-doc.cn

FTP 出站网关提供一组有限的命令来与远程 FTP 或 FTPS 服务器进行交互。支持的命令包括：spring-doc.cn

ls（列出文件）spring-doc.cn
nlst（列出文件名）spring-doc.cn
get（检索文件）spring-doc.cn
mget（检索文件）spring-doc.cn
rm（删除文件）spring-doc.cn
mv（移动/重命名文件）spring-doc.cn
put（发送文件）spring-doc.cn
mput（发送多个文件）spring-doc.cn

使用命令`ls`

ls列出远程文件并支持以下选项：spring-doc.cn

-1：检索文件名列表。默认为检索对象列表。FileInfospring-doc.cn
-a：包括所有文件（包括以“.”开头的文件）spring-doc.cn
-f：不对列表进行排序spring-doc.cn
-dirs：包括目录（默认情况下排除它们）spring-doc.cn
-links：包括符号链接（默认情况下，它们被排除在外）spring-doc.cn
-R：递归列出远程目录spring-doc.cn

此外，还提供文件名筛选，其方式与 . 请参阅 FTP 入站通道适配器。inbound-channel-adapterspring-doc.cn

操作生成的消息有效负载是文件名列表或对象列表。这些对象提供修改时间、权限和其他详细信息等信息。lsFileInfospring-doc.cn

标头中提供了命令操作的远程目录。lsfile_remoteDirectoryspring-doc.cn

使用递归选项（）时，包括任何子目录元素，这些元素表示文件的相对路径（相对于远程目录）。如果包含该选项，则每个递归目录也将作为列表中的一个元素返回。在这种情况下，建议您不要使用该选项，因为您将无法区分文件和目录，而您可以对对象进行区分。-RfileName-dirs-1FileInfospring-doc.cn

从版本 4.3 开始，对 and 方法的支持。因此，您可以省略该属性。为方便起见，Java 配置有两个没有参数的构造函数。或、、和命令被视为客户端工作目录，根据 FTP 协议。所有其他命令都必须随一起提供，以便根据请求消息评估远程路径。您可以在扩展和实现回调时使用函数设置工作目录。FtpSessionnulllist()listNames()expressionexpressionLSNLSTPUTMPUTnullexpressionFTPClient.changeWorkingDirectory()DefaultFtpSessionFactorypostProcessClientAfterConnect()spring-doc.cn

使用命令`nlst`

版本 5 引入了对该命令的支持。nlstspring-doc.cn

nlst列出远程文件名，并且仅支持一个选项：spring-doc.cn

-f：不对列表进行排序spring-doc.cn

操作生成的消息有效负载是文件名列表。nlstspring-doc.cn

标头中提供了命令操作的远程目录。nlstfile_remoteDirectoryspring-doc.cn

与使用该命令的 ls 命令的选项不同，该命令将命令发送到目标 FTP 服务器。当服务器不支持时（例如，由于安全限制），此命令很有用。操作的结果是没有其他详细信息的名称。因此，框架无法确定实体是否为目录，例如，无法执行筛选或递归列表。-1LISTnlstNLSTLISTnlstspring-doc.cn

使用命令`get`

get检索远程文件。它支持以下选项：spring-doc.cn

-P：保留远程文件的时间戳。spring-doc.cn
-stream：将远程文件作为流检索。spring-doc.cn
-D：传输成功后删除远程文件。如果忽略传输，则不会删除远程文件，因为 is 和本地文件已存在。FileExistsModeIGNOREspring-doc.cn

标头提供远程目录名称，标头提供文件名。file_remoteDirectoryfile_remoteFilespring-doc.cn

操作生成的消息有效负载是表示检索到的文件的对象，或者当您使用该选项时。该选项允许将文件作为流检索。对于文本文件，一个常见的用例是将此操作与文件拆分器或流转换器结合使用。将远程文件作为流使用时，您负责在使用流后关闭。为方便起见，标头中提供了 the，您可以使用便利方法访问以下示例显示了如何使用便利方法：getFileInputStream-stream-streamSessionSessioncloseableResourceIntegrationMessageHeaderAccessorspring-doc.cn

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

文件拆分器和流转换器等框架组件在传输数据后会自动关闭会话。spring-doc.cn

以下示例演示如何将文件作为流使用：spring-doc.cn

<int-ftp: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" />

如果您在自定义组件中使用输入流，则必须关闭 . 你可以在自定义代码中执行此操作，也可以通过将消息的副本路由到 a 并使用 SPEL 来实现，如下例所示：Sessionservice-activator

<int:service-activator input-channel="closeSession"
    expression="headers['closeableResource'].close()" />

使用命令`mget`

mget根据模式检索多个远程文件，并支持以下选项：spring-doc.cn

-P：保留远程文件的时间戳。spring-doc.cn
-R：递归检索整个目录树。spring-doc.cn
-x：如果没有与模式匹配的文件，则引发异常（否则返回空列表）。spring-doc.cn
-D：传输成功后删除每个远程文件。如果忽略传输，则不会删除远程文件，因为 is 和本地文件已存在。FileExistsModeIGNOREspring-doc.cn

操作生成的消息有效负载是一个对象（即一个对象，每个对象表示一个检索到的文件）。mgetList<File>ListFilespring-doc.cn

从版本 5.0 开始，如果 is ，则输出消息的有效负载不再包含由于文件已存在而未获取的文件。以前，该列表包含所有文件，包括已存在的文件。FileExistsModeIGNORE

用于确定远程路径的表达式应产生以 - 结尾的结果 - 例如 somedir/ 将获取下的完整树。somedirspring-doc.cn

从版本 5.0 开始，可以使用 recursive 与新模式相结合，定期在本地同步整个远程目录树。此模式将本地文件的上次修改时间戳替换为远程时间戳，而不管（preserve timestamp）选项如何。mgetFileExistsMode.REPLACE_IF_MODIFIED-Pspring-doc.cn

使用递归（-R)

该模式将被忽略，并被假定为。默认情况下，将检索整个远程树。但是，可以通过提供 . 树中的目录也可以通过这种方式进行筛选。 A 可以通过 reference、by 或 by 属性提供。例如，检索远程目录和子目录中以结尾的所有文件。但是，下一个示例显示了一个替代方法，即 5.0 版本可用。*FileListFilterFileListFilterfilename-patternfilename-regexfilename-regex="(subDir|.*1.txt)"1.txtsubDirspring-doc.cn

如果过滤了子目录，则不会对该子目录执行额外的遍历。spring-doc.cn

该选项是不允许的（递归使用递归来获取目录树，因此目录本身不能包含在列表中）。-dirsmgetlsspring-doc.cn

通常，您将在中使用该变量，以便在本地保留远程目录结构。#remoteDirectorylocal-directory-expressionspring-doc.cn

持久性文件列表过滤器现在具有 boolean 属性。将此属性设置为，还会设置，这意味着出站网关（和）上的递归操作现在每次都将始终遍历整个目录树。这是为了解决未检测到目录树深处更改的问题。此外，还会导致将文件的完整路径用作元数据存储键;这解决了以下问题：如果具有相同名称的文件在不同目录中多次出现，则过滤器无法正常工作。重要说明：这意味着对于顶级目录下的文件，将无法找到持久性元数据存储中的现有键。因此，默认情况下，该属性为;这可能会在未来版本中更改。forRecursiontruealwaysAcceptDirectorieslsmgetforRecursion=truefalsespring-doc.cn

从版本 5.0 开始，可以通过将属性设置为和来将 and 配置为始终传递目录。这样做允许对简单模式进行递归，如下例所示：FtpSimplePatternFileListFilterFtpRegexPatternFileListFilteralwaysAcceptDirectoriestruespring-doc.cn

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

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

定义筛选器（如前面示例中的筛选器）后，您可以通过在网关上设置属性来使用一个筛选器。filterspring-doc.cn

另请参阅出站网关部分成功（mget 和 mput）。spring-doc.cn

使用递归（-R)

如果过滤了子目录，则不会对该子目录执行额外的遍历。spring-doc.cn

该选项是不允许的（递归使用递归来获取目录树，因此目录本身不能包含在列表中）。-dirsmgetlsspring-doc.cn

通常，您将在中使用该变量，以便在本地保留远程目录结构。#remoteDirectorylocal-directory-expressionspring-doc.cn

使用命令`put`

该命令将文件发送到远程服务器。消息的有效负载可以是、或。一个（或表达式）用于命名远程文件。其他可用属性包括、及其等效项：和。有关更多信息，请参阅 schema documentation.putjava.io.Filebyte[]Stringremote-filename-generatorremote-directorytemporary-remote-directory*-expressionuse-temporary-file-nameauto-create-directoryspring-doc.cn

操作生成的消息有效负载是 a，表示传输后文件在服务器上的完整路径。putStringspring-doc.cn

版本 5.2 引入了该属性，该属性在上传后更改远程文件权限。您可以使用传统的 Unix 八进制格式（例如，仅允许文件所有者进行读写操作）。使用 java 配置适配器时，可以使用 . 仅当您的 FTP 服务器支持该子命令时才适用。chmod600setChmod(0600)SITE CHMODspring-doc.cn

使用命令`mput`

将多个文件发送到服务器，并且仅支持一个选项：mputspring-doc.cn

-R：递归的。发送目录及其子目录中的所有文件（可能已过滤）。spring-doc.cn

消息有效负载必须是表示本地目录的（或）。从版本 5.1 开始，还支持 or 的集合。java.io.FileStringFileStringspring-doc.cn

此命令支持与 put 命令相同的属性。此外，可以使用、、或之一筛选本地目录中的文件。只要子目录本身通过过滤器，过滤器就可以使用递归。未通过过滤器的子目录不会递归。mput-patternmput-regexmput-filtermput-filter-expressionspring-doc.cn

操作生成的消息有效负载是一个对象（即传输产生的远程文件路径）。mputList<String>Listspring-doc.cn

另请参阅出站网关部分成功（mget 和 mput）。spring-doc.cn

版本 5.2 引入了该属性，该属性允许您在上传后更改远程文件权限。您可以使用传统的 Unix 八进制格式（例如，仅允许文件所有者进行读写操作）。使用 Java 配置适配器时，可以使用或。仅当您的 FTP 服务器支持该子命令时才适用。chmod600setChmodOctal("600")setChmod(0600)SITE CHMODspring-doc.cn

使用命令`rm`

该命令将删除文件。rmspring-doc.cn

该命令没有选项。rmspring-doc.cn

操作生成的消息有效负载是删除是否成功。标头提供远程目录，标头提供文件名。rmBoolean.TRUEBoolean.FALSEfile_remoteDirectoryfile_remoteFilespring-doc.cn

使用命令`mv`

该命令可移动文件。mvspring-doc.cn

该命令没有选项。mvspring-doc.cn

该属性定义 “from” 路径，该属性定义 “to” 路径。默认情况下，该是 . 此表达式的计算结果不得为 null 或空 . 如有必要，将创建任何必要的远程目录。结果消息的负载为 . header 提供原始远程目录，header 提供文件名。新路径位于标头中。expressionrename-expressionrename-expressionheaders['file_renameTo']StringBoolean.TRUEfile_remoteDirectoryfile_remoteFilefile_renameTospring-doc.cn

从版本 5.5.6 开始，为方便起见，可以在命令中使用。如果 “from” 文件不是完整的文件路径，则 result of 将用作远程目录。这同样适用于“to”文件，例如，如果任务只是重命名某个目录中的远程文件。remoteDirectoryExpressionmvremoteDirectoryExpressionspring-doc.cn

有关 FTP 出站网关命令的其他信息

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

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

对于所有命令，网关的 'expression' 属性提供命令操作的路径。对于该命令，表达式的计算结果可能为 ''，表示检索所有文件，或者为 'somedirectory/'，依此类推。mgetspring-doc.cn

以下示例显示了为命令配置的网关：lsspring-doc.cn

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

发送到通道的消息的有效负载是一个对象列表，每个对象都包含一个文件名。如果省略了该属性，则它包含对象。它使用以空格分隔的选项 — 例如 .toSplitterStringcommand-optionsFileInfocommand-options="-1 -dirs -links"spring-doc.cn

从版本 4.2 开始，，和命令支持属性（使用命名空间支持时）。这会影响本地文件存在（和）或远程文件存在（和）时的行为。支持的模式包括、、和。为了向后兼容，和 operations 的默认模式为 . 对于和 operations，默认值为 .GETMGETPUTMPUTFileExistsModemodeGETMGETPUTMPUTREPLACEAPPENDFAILIGNOREPUTMPUTREPLACEGETMGETFAILspring-doc.cn

从版本 5.0 开始，在（ in XML）上提供（ in XML）选项。它允许您在运行时更改客户端工作目录。根据请求消息计算表达式。每次网关操作后，都会恢复以前的工作目录。setWorkingDirExpression()working-dir-expressionFtpOutboundGateway<int-ftp:outbound-gateway>spring-doc.cn

使用 Java 配置进行配置

Spring 以下 Boot 应用程序显示了如何使用 Java 配置配置出站网关的示例：spring-doc.cn

@SpringBootApplication
public class FtpJavaApplication {

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

    @Bean
    public SessionFactory<FTPFile> ftpSessionFactory() {
        DefaultFtpSessionFactory sf = new DefaultFtpSessionFactory();
        sf.setHost("localhost");
        sf.setPort(port);
        sf.setUsername("foo");
        sf.setPassword("foo");
        sf.setTestSession(true);
        return new CachingSessionFactory<FTPFile>(sf);
    }

    @Bean
    @ServiceActivator(inputChannel = "ftpChannel")
    public MessageHandler handler() {
        FtpOutboundGateway ftpOutboundGateway =
                          new FtpOutboundGateway(ftpSessionFactory(), "ls", "'my_remote_dir/'");
        ftpOutboundGateway.setOutputChannelName("lsReplyChannel");
        return ftpOutboundGateway;
    }

}

使用 Java DSL 进行配置

Spring 下面的 Boot 应用程序显示了如何使用 Java DSL 配置出站网关的示例：spring-doc.cn

@SpringBootApplication
public class FtpJavaApplication {

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

    @Bean
    public SessionFactory<FTPFile> ftpSessionFactory() {
        DefaultFtpSessionFactory sf = new DefaultFtpSessionFactory();
        sf.setHost("localhost");
        sf.setPort(port);
        sf.setUsername("foo");
        sf.setPassword("foo");
        sf.setTestSession(true);
        return new CachingSessionFactory<FTPFile>(sf);
    }

    @Bean
    public FtpOutboundGatewaySpec ftpOutboundGateway() {
        return Ftp.outboundGateway(ftpSessionFactory(),
            AbstractRemoteFileOutboundGateway.Command.MGET, "payload")
            .options(AbstractRemoteFileOutboundGateway.Option.RECURSIVE)
            .regexFileNameFilter("(subFtpSource|.*1.txt)")
            .localDirectoryExpression("'localDirectory/' + #remoteDirectory")
            .localFilenameExpression("#remoteFileName.replaceFirst('ftpSource', 'localTarget')");
    }

    @Bean
    public IntegrationFlow ftpMGetFlow(AbstractRemoteFileOutboundGateway<FTPFile> ftpOutboundGateway) {
        return f -> f
            .handle(ftpOutboundGateway)
            .channel(c -> c.queue("remoteFileOutputChannel"));
    }

}

出站网关部分成功（和`mgetmput`)

当您对多个文件执行操作（通过使用和）时，在传输一个或多个文件后的一段时间内可能会发生异常。在这种情况下（从版本 4.2 开始），会抛出 a 。除了通常的属性（和），此异常还具有两个附加属性：mgetmputPartialSuccessExceptionMessagingExceptionfailedMessagecausespring-doc.cn

partialResults：传输成功的结果。spring-doc.cn
derivedInput：从请求消息生成的文件列表（例如，要传输的本地文件）。mputspring-doc.cn

这些属性允许您确定哪些文件已成功传输，哪些文件未成功传输。spring-doc.cn

在 recursive 的情况下，可能有嵌套的出现次数。mputPartialSuccessExceptionPartialSuccessExceptionspring-doc.cn

请考虑以下目录结构：spring-doc.cn

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

如果异常发生在，则网关引发的具有、和和的。它是另一个具有 of 和 and 的。file3.txtPartialSuccessExceptionderivedInputfile1.txtsubdirzoo.txtpartialResultsfile1.txtcausePartialSuccessExceptionderivedInputfile2.txtfile3.txtpartialResultsfile2.txtspring-doc.cn

使用命令ls

使用命令nlst

使用命令get

使用命令mget

使用命令put

使用命令mput

使用命令rm

使用命令mv