Ansible 社区文档

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

注意

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

概要 

基于特定条件返回文件列表。多个条件之间是 AND 关系。
对于 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 字符串	要选择的文件类型。 Ansible 2.3 中添加了“link”和“any”选择。选择 `"any"` `"directory"` `"file"` ← (默认) `"link"`
follow 布尔值	将此设置为 `true` 以在具有 python 2.6+ 的系统上跟踪路径中的符号链接。选择 `false` ← (默认) `true`
get_checksum 布尔值	将此设置为 `true` 以检索文件的 SHA1 校验和。选择 `false` ← (默认) `true`
hidden 布尔值	将此设置为 `true` 以包含隐藏文件，否则它们将被忽略。选择 `false` ← (默认) `true`
mode any 在 ansible-core 2.16 中添加	选择与指定权限匹配的对象。此值限制为可以使用 python `os.chmod` 函数应用的模式。该模式可以以八进制形式提供，例如 `"0644"` 或以符号形式提供，例如 `u=rw,g=r,o=r`
paths 别名：name, 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$'

返回值 

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

键	描述
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)

集合链接