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

布尔值

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

选项

  • false ← (默认)

  • true

get_checksum

布尔值

是否返回文件的校验和。

选项

  • false ← (默认)

  • true

hidden

布尔值

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

选项

  • false ← (默认)

  • true

limit

整数

添加到 ansible-core 2.18 中

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

匹配从上到下（即从最浅的目录开始）进行。

如果未设置，或设置为 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

支持: 完全支持

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

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

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)