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

注意

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

概要

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

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

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

参数

参数	注释
age 字符串	选择年龄等于或大于指定时间的文件。 使用负年龄查找等于或小于指定时间的文件。 您可以通过指定这些单词的首字母来选择秒、分钟、小时、天或周（例如，“1w”）。
age_stamp 字符串	选择用于比较年龄的文件属性。 选项 "atime" "ctime" "mtime" ← (默认)
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 或正则表达式）模式，其类型由 use_regex 选项控制。 基本名称与 excludes 模式匹配的项目将从 patterns 匹配项中剔除。可以使用列表指定多个模式。
file_type 字符串	要选择的文件类型。 link 和 any 选项在 Ansible 2.3 中添加。 选项 "any" "directory" "file" ← (默认) "link"
follow 布尔值	设置为 true 以在路径中跟踪符号链接，适用于 Python 2.6+ 的系统。 选项 false ← (默认) true
get_checksum 布尔值	设置为 true 以检索文件的 SHA1 校验和。 选项 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 list / elements=path / required	要搜索的目录路径列表。所有路径都必须是完全限定的。 从 ansible-core 2.18 及更高版本开始，数据类型已从 str 更改为 path。
patterns 别名: pattern 列表 / 元素=字符串	一个或多个（shell 或正则表达式）模式，其类型由 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

根据特定条件返回文件列表。

示例

- 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' 不是一个目录"}

作者

• Brian Coca (@bcoca)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 通信