ListFile 2025.5.31.15¶

捆绑包¶

org.apache.nifi | nifi-standard-nar

描述¶

从输入目录检索文件列表。对于列出的每个文件，创建一个代表该文件的 FlowFile，以便可以将其与 FetchFile 一起提取。当“Input Directory Location”设置为“Remote”时，该处理器设计为仅在集群的主节点上运行。如果主节点发生变化，新的主节点将在不复制所有数据的情况下继续从前一个节点中断的地方继续。当“Input Directory Location”为“Local”时，“Execution”模式可以是任何模式，并且不会发生同步。与 GetFile 不同，该处理器不会从本地文件系统中删除任何数据。

标签¶

file、filesystem、get、ingest、list、source

输入要求¶

FORBIDDEN

支持敏感的动态属性¶

false

属性¶

属性	描述
文件筛选器	仅选取名称与给定正则表达式匹配的文件
忽略隐藏的文件	表示是否应忽略隐藏文件
包括核心属性	是否将文件的上次修改时间和所有者等信息作为 FlowFile 属性包括在内。根据所使用的文件系统的不同，收集这些信息的成本可能会很高，因此应禁用。远程文件共享尤其如此。
输入目录	要从中提取文件的输入目录
输出目录位置	指定输入目录的位置。这用于确定状态应存储在本地还是在整个集群中。
最长文件存在时间	文件提取的最大允许时间范围；（按照最后修改日期）晚于该时间的任何文件都将被忽略
最大文件大小	可提取的最大文件大小
最短文件存在时间	文件提取的最小允许时间范围；（按照最后修改日期）早于该时间的任何文件都将被忽略
最小文件大小	可提取的最小文件大小
路径筛选器	当“递归子目录”为 True 时，只会扫描路径与给定正则表达式匹配的子目录
递归子目录	指示是否列出目录子目录中的文件
et-initial-listing-target	指定应如何处理初始列表。由“跟踪实体”策略使用。
et-node-identifier	配置的值将追加到缓存键中，这样当跟踪状态的范围限定为 LOCAL 时，可以跟踪每个 NiFi 节点的列表状态，而不是整个集群的状态。由“跟踪实体”策略使用。
et-state-cache	列出的实体存储在指定的缓存存储器中，这样该处理器在 NiFi 重启后或主节点发生更改时可以恢复列出。“跟踪实体”策略要求在最后一个“跟踪时间窗口”内提供所有列出的实体的跟踪信息。为了支持大量实体，该策略使用 DistributedMapCache 而非托管状态。缓存键格式为“ListedEntities::{processorId}(::{nodeId})”。如果它跟踪每个节点列出的实体，则会添加可选的“::{nodeId}”部分以单独管理状态。例如，集群范围缓存键 =“ListedEntities::8dda2321-0164-1000-50fa-3042fe7d6a7b”，每节点缓存键 =“ListedEntities::8dda2321-0164-1000-50fa-3042fe7d6a7b::nifi-node3”存储的缓存内容是 Gzipped JSON 字符串。目标列表配置更改时，缓存键将被删除。由“跟踪实体”策略使用。
et-time-window	指定该处理器应跟踪已列出的实体多长时间。“跟踪实体”策略可以选择时间戳在指定时间窗口内的任何实体。例如，如果设置为“30 分钟”，则在该处理器运行时，任何具有最近 30 分钟时间戳的实体都将成为列表目标。如果满足以下条件之一，则列出实体被视为“新的/已更新的”，并发出 FlowFile：1. 不存在于已列出的实体中；2. 具有比缓存实体更新的时间戳；3. 与缓存实体的大小不同。如果缓存实体的时间戳早于指定的时间窗口，则该实体将从缓存的已列出实体中移除。由“跟踪实体”策略使用。
listing-strategy	指定如何确定新的/更新的实体。有关详细信息，请参阅每种策略的描述。
max-listing-time	列出任何单个目录预计所花费的最长时间。如果“输入目录”属性指定的目录列表或任何子目录的列表（如果“Recurse”设置为 True）花费的时间超过此时间，则将为超过此时间的每个目录列表生成警告公告。
max-operation-time	任何单个磁盘操作预计花费的最长时间。如果任何磁盘操作所花费的时间超过此时间，则将为超过此时间的每项操作生成警告公告。
max-performance-metrics	如果“跟踪性能”属性设置为“True”，则此属性表示应保留其性能指标的最大文件数。此属性的值越小，堆利用率越低，而值越大，可以更准确地了解磁盘访问操作的执行情况
record-writer	指定用于创建列表的记录写入器。如果未指定，则将为列出的每个实体创建一个 FlowFile。如果指定了记录写入器，则所有实体都将写入单个 FlowFile，而不是向单个 FlowFiles 添加属性。
target-system-timestamp-precision	指定目标系统的时间戳精度。由于该处理器使用实体的时间戳来决定应列出哪些实体，因此使用正确的时间戳精度至关重要。
track-performance	处理器是否应该跟踪磁盘访问操作的性能。如果为 True，则将记录对磁盘的所有访问，包括正在访问的文件、获得的信息以及所花费的时长。然后，定期在 DEBUG 级别记录此信息。虽然数据量将受到限制，但此选项仍可能使用大量的堆（由“要跟踪的最大文件数”属性控制），但如果性能不佳导致故障排除，它可能非常有用。

状态管理¶

范围	描述
CLUSTER	执行文件列表后，将存储最新文件的时间戳。这允许处理器在下次运行时，仅列出在此日期之后添加或修改的文件。状态是以本地作用域还是集群作用域存储取决于 <Input Directory Location> 属性的值。
LOCAL	执行文件列表后，将存储最新文件的时间戳。这允许处理器在下次运行时，仅列出在此日期之后添加或修改的文件。状态是以本地作用域还是集群作用域存储取决于 <Input Directory Location> 属性的值。

关系¶

名称	描述
success	所有收到的 FlowFiles 都将路由至“success”

写入属性¶

名称	描述
filename	从文件系统读取的文件的名称。
path	与“输入目录”属性相比，该路径设置为文件系统中文件目录的相对路径。例如，如果将输入目录设置为 /tmp，则从 /tmp 提取的文件路径属性将设置为“/”。如果“递归子目录”属性设置为 True 并且从 /tmp/abc/1/2/3 中选取了一个文件，则路径属性将设置为“abc/1/2/3/”。
absolute.path	absolute.path 设置为文件系统中文件目录的绝对路径。例如，如果“输入目录”属性设置为 /tmp，则从 /tmp 提取的文件路径属性将设置为“/tmp/”。如果“递归子目录”属性设置为 True 并且从 /tmp/abc/1/2/3 中选取了一个文件，则路径属性将设置为“/tmp/abc/1/2/3/”。
file.owner	拥有文件系统中文件的用户
file.group	拥有文件系统中文件的群组
file.size	文件系统中文件的字节数
file.permissions	文件系统中文件的权限。对于所有者，其格式为 3 个字符，群组为 3 个字符，对于其他用户，则为 3 个字符。例如 rw-rw-r--
file.lastModifiedTime	文件系统中文件最后一次修改的时间戳，格式为“yyyy-MM-dd'T'HH:mm:ssZ”
file.lastAccessTime	文件系统中文件最后一次访问的时间戳，格式为“yyyy-MM-dd'T'HH:mm:ssZ”
file.creationTime	文件系统中文件创建的时间戳，格式为“yyyy-MM-dd'T'HH:mm:ssZ”