ansible.builtin.find 模块 - 基于特定条件返回文件列表

注意

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

概要

  • 基于特定条件返回文件列表。多个条件被 AND 运算符连接在一起。

  • 对于 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 或正则表达式）模式，其类型由 use_regex 选项控制。

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

file_type

字符串

要选择的文件类型。

link 和 any 选择是在 Ansible 2.3 中添加的。

选择

  • "any"

  • "directory"

  • "file" ← (默认)

  • "link"

follow

布尔值

对于具有 python 2.6+ 的系统，将其设置为 true 以在路径中跟随符号链接。

选择

  • false ← (默认)

  • true

get_checksum

布尔值

是否返回文件的校验和。

选择

  • false ← (默认)

  • true

hidden

布尔值

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

选择

  • false ← (默认)

  • true

limit

整数

在 ansible-core 2.18 中添加

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

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

如果没有设置，或者设置为 v(null)，它将进行无限匹配。

默认值为无限匹配。

mode

任何

在 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 或正则表达式）模式，其类型由 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

支持：完全支持

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

可以在 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)