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.0 版本引入了对 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) 时的注意事项：将忽略模式并假定为 如果过滤子目录，则不会执行该子目录的额外遍历。 不允许使用 通常，您会在 |
持久性文件列表过滤器现在具有一个布尔属性 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 属性提供其中一个过滤器。
使用 put 命令
put 将文件发送到远程服务器。消息的有效负载可以是 java.io.File、byte[] 或 String。remote-filename-generator（或表达式）用于命名远程文件。其他可用属性包括 remote-directory、temporary-remote-directory 及其 *-expression 等效项：use-temporary-file-name 和 auto-create-directory。有关更多信息，请参阅架构文档。
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>对象（即传输生成的远程文件路径列表）。
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 版本开始，为了方便起见，可以在mv命令中使用remoteDirectoryExpression。如果“源”文件不是完整的 文件路径，则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。
