ansible.builtin.find 模块 – 根据特定条件返回文件列表

注意

此模块是 ansible-core 的一部分，并包含在所有 Ansible 安装中。在大多数情况下，即使不指定collections 关键字，您也可以使用短模块名称 find。但是，我们建议您使用完全限定集合名称 (FQCN) ansible.builtin.find，以便轻松链接到模块文档并避免与其他可能具有相同模块名称的集合冲突。

概要

  • 根据特定条件返回文件列表。多个条件之间是“与”关系。

  • 对于 Windows 目标，请改用ansible.windows.win_find 模块。

  • 此模块不使用 find 命令，它是一个更简单且速度较慢的 Python 实现。它适用于小型和简单的用途。那些需要额外功能或速度并且具有 UNIX 命令专业知识的人，应该直接使用它。

参数

参数

注释

age

字符串

选择年龄等于或大于指定时间的文件。

使用负年龄查找等于或小于指定时间的文件。

您可以通过指定任何这些单词的第一个字母（例如，“1w”），来选择秒、分钟、小时、天或周。

age_stamp

字符串

选择与我们比较年龄的文件属性。

选项

  • "atime"

  • "ctime"

  • "mtime" ← (默认)

checksum_algorithm

别名: checksum, checksum_algo

字符串

在 ansible-core 2.19 中添加

确定文件校验和的算法。

如果主机无法使用指定的算法，将抛出错误。

远程主机必须支持指定的哈希方法，如果主机符合 FIPS-140 标准，则 md5 可能不可用。

可用性可能受目标系统的限制，例如 FIPS 系统不允许使用 md5

选项

  • "md5"

  • "sha1" ← (默认)

  • "sha224"

  • "sha256"

  • "sha384"

  • "sha512"

contains

字符串

应与文件内容匹配的正则表达式或模式。

如果 read_whole_file=false，则与行首匹配（使用 re.match()）。如果 read_whole_file=true，则在任何地方搜索该模式（使用 re.search()）。

仅当 file_type 为 file 时有效。

depth

整数

设置要下降的最大级别数。

设置 recurse=false 将覆盖此值，它实际上是深度 1。

默认是无限深度。

encoding

字符串

在 ansible-core 2.17 中添加

在执行 contains 搜索时，确定要搜索的文件的编码。

exact_mode

布尔值

在 ansible-core 2.16 中添加

将模式匹配限制为仅精确匹配，而不是作为要匹配的最小权限集。

选项

  • false

  • true ← (默认)

excludes

别名: exclude

列表 / 元素=字符串

一个或多个（shell 或 regex）模式，其类型由 use_regex 选项控制。

基本名称与 excludes 模式匹配的项将从 patterns 匹配中剔除。可以使用列表指定多个模式。

file_type

字符串

要选择的文件类型。

link 和 any 选项在 Ansible 2.3 中添加。

选项

  • "any"

  • "directory"

  • "file" ← (默认)

  • "link"

follow

布尔值

将此设置为 true 以在具有 python 2.6+ 的系统中跟踪路径中的符号链接。

选项

  • false ← (默认)

  • true

get_checksum

布尔值

是否返回文件的校验和。

选项

  • false ← (默认)

  • true

hidden

布尔值

将此设置为 true 以包含隐藏文件，否则将忽略它们。

选项

  • false ← (默认)

  • true

limit

整数

在 ansible-core 2.18 中添加

限制返回的最大匹配路径数。找到这么多路径后，find 操作将停止查找。

匹配是从上到下进行的（即，首先是最浅的目录）。

如果未设置或设置为 v(null)，则将进行无限匹配。

默认是无限匹配。

mode

any

在 ansible-core 2.16 中添加

选择与指定权限匹配的对象。此值限制为可以使用 python os.chmod 函数应用的模式。

该模式可以以八进制形式（例如 "0644"）或符号形式（例如 u=rw,g=r,o=r）提供。

paths

别名: name, path

列表 / 元素=路径 / 必需

要搜索的目录路径列表。所有路径必须是完全限定的。

从 ansible-core 2.18 版本开始，数据类型已从 str 更改为 path。

patterns

别名: pattern

列表 / 元素=字符串

一个或多个（shell 或 regex）模式，其类型由 use_regex 选项控制。

该模式限制返回的文件列表，只返回那些基本名称与至少一个指定模式匹配的文件。可以使用列表指定多个模式。

该模式与文件基本名称（不包括目录）进行匹配。

当使用正则表达式时，该模式必须匹配整个文件名，而不仅仅是部分文件名。因此，如果您想匹配所有以 .default 结尾的文件，则需要使用 .*\.default 作为正则表达式，而不仅仅是 \.default。

此参数期望一个列表，可以是逗号分隔的或 YAML 格式的。如果任何模式包含逗号，请确保将它们放在列表中，以避免以不需要的方式拆分模式。

当 use_regex=False 时，默认为 *；当 use_regex=True 时，默认为 .*。

默认值： []

read_whole_file

布尔值

在 ansible-core 2.11 中添加

当执行 contains 搜索时，确定是否应将整个文件读入内存，或者是否应将正则表达式逐行应用于文件。

将此设置为 true 可能会对大文件产生性能和内存影响。

这里使用 re.search() 而不是 re.match()。

选项

  • false ← (默认)

  • true

recurse

布尔值

如果目标是一个目录，则递归地进入该目录以查找文件。

选项

  • false ← (默认)

  • true

size

字符串

选择大小等于或大于指定大小的文件。

使用负数大小查找大小等于或小于指定大小的文件。

未限定的值以字节为单位，但可以附加 b、k、m、g 和 t 分别指定字节、千字节、兆字节、千兆字节和太字节。

大小不针对目录进行评估。

use_regex

布尔值

如果为 false，则模式是文件通配符（shell）。

如果为 true，则模式是 python 正则表达式。

选项

  • false ← (默认)

  • true

属性

属性

支持

描述

check_mode

支持： 完整

由于此操作不会修改目标，因此它在检查模式下正常执行

可以在检查模式下运行并返回已更改的状态预测，而无需修改目标。如果不支持，则将跳过该操作。

diff_mode

支持： 无

当处于差异模式时，将返回有关已更改（或可能需要在检查模式下更改）的详细信息

platform

平台： posix

可以操作的目标操作系统/系列

另请参阅

另请参阅

ansible.windows.win_find

有关 ansible.windows.win_find 模块的官方文档。

示例

- name: Recursively find /tmp files older than 2 days
  ansible.builtin.find:
    paths: /tmp
    age: 2d
    recurse: yes

- name: Recursively find /tmp files older than 4 weeks and equal or greater than 1 megabyte
  ansible.builtin.find:
    paths: /tmp
    age: 4w
    size: 1m
    recurse: yes

- name: Recursively find /var/tmp files with last access time greater than 3600 seconds
  ansible.builtin.find:
    paths: /var/tmp
    age: 3600
    age_stamp: atime
    recurse: yes

- name: Find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz
  ansible.builtin.find:
    paths: /var/log
    patterns: '*.old,*.log.gz'
    size: 10m

# Note that YAML double quotes require escaping backslashes but yaml single quotes do not.
- name: Find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz via regex
  ansible.builtin.find:
    paths: /var/log
    patterns: "^.*?\\.(?:old|log\\.gz)$"
    size: 10m
    use_regex: yes

- name: Find /var/log all directories, exclude nginx and mysql
  ansible.builtin.find:
    paths: /var/log
    recurse: no
    file_type: directory
    excludes: 'nginx,mysql'

# When using patterns that contain a comma, make sure they are formatted as lists to avoid splitting the pattern
- name: Use a single pattern that contains a comma formatted as a list
  ansible.builtin.find:
    paths: /var/log
    file_type: file
    use_regex: yes
    patterns: ['^_[0-9]{2,4}_.*.log$']

- name: Use multiple patterns that contain a comma formatted as a YAML list
  ansible.builtin.find:
    paths: /var/log
    file_type: file
    use_regex: yes
    patterns:
      - '^_[0-9]{2,4}_.*.log$'
      - '^[a-z]{1,5}_.*log$'

- name: Find file containing "wally" without necessarily reading all files
  ansible.builtin.find:
    paths: /var/log
    file_type: file
    contains: wally
    read_whole_file: true
    patterns: "^.*\\.log$"
    use_regex: true
    recurse: true
    limit: 1

返回值

通用返回值记录在这里，以下是此模块特有的字段

键

描述

examined

整数

查看的文件系统对象数量

返回： 成功

示例： 34

files

列表 / 元素=字符串

使用指定条件找到的所有匹配项（有关每个字典的完整输出，请参阅 stat 模块）

返回： 成功

示例： [{"...": "...", "checksum": "16fac7be61a6e4591a33ef4b729c5c3302307523", "mode": "0644", "path": "/var/tmp/test1"}, {"...": "...", "path": "/var/tmp/test2"}]

matched

整数

匹配项的数量

返回： 成功

示例： 14

skipped_paths

字典

在 ansible-core 2.12 中添加

跳过的路径以及跳过它们的原因

返回： 成功

示例： {"/laskdfj": "'/laskdfj' is not a directory"}

作者

  • Brian Coca (@bcoca)