ListFile 2025.10.2.19¶

捆绑包¶

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	Specify how initial listing should be handled. Used by 'Tracking Entities'strategy.
et-node-identifier	The configured value will be appended to the cache key so that listing state can be tracked per NiFi node rather than cluster wide when tracking state is scoped to LOCAL. Used by 'Tracking Entities'strategy.
et-state-cache	Listed entities are stored in the specified cache storage so that this processor can resume listing across NiFi restart or in case of primary node change. 'Tracking Entities'strategy require tracking information of all listed entities within the last 'Tracking Time Window'. To support large number of entities, the strategy uses DistributedMapCache instead of managed state. Cache key format is 'ListedEntities::{processorId}(::{nodeId})'. If it tracks per node listed entities, then the optional '::{nodeId}' part is added to manage state separately. E.g. cluster wide cache key ='ListedEntities::8dda2321-0164-1000-50fa-3042fe7d6a7b', per node cache key ='ListedEntities::8dda2321-0164-1000-50fa-3042fe7d6a7b::nifi-node3' The stored cache content is Gzipped JSON string. The cache key will be deleted when target listing configuration is changed. Used by 'Tracking Entities'strategy.
et-time-window	Specify how long this processor should track already-listed entities. 'Tracking Entities'strategy can pick any entity whose timestamp is inside the specified time window. For example, if set to '30 minutes', any entity having timestamp in recent 30 minutes will be the listing target when this processor runs. A listed entity is considered 'new/updated' and a FlowFile is emitted if one of following condition meets: 1. does not exist in the already-listed entities, 2. has newer timestamp than the cached entity, 3. has different size than the cached entity. If a cached entity 's timestamp becomes older than specified time window, that entity will be removed from the cached already-listed entities. Used by'Tracking Entities'strategy.
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 级别记录此信息。虽然数据量将受到限制，但此选项仍可能使用大量的堆（由“要跟踪的最大文件数”属性控制），但如果性能不佳导致故障排除，它可能非常有用。

状态管理¶

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