find

Содержание

find#

Модуль ansible.builtin.find возвращает список файлов, соответствующих заданным условиям. Условия объединяются логическим AND – то есть возвращаются только файлы, удовлетворяющие всем условиям одновременно.

Особенности работы#

Модуль ansible.builtin.find имеет следующие особенности:

Модуль является аналогом утилиты find, но реализован средствами Python внутри Ansible и не использует системную команду find, поэтому работает медленнее и имеет меньшие возможности. Если вам нужны возможности утилиты find, используйте ее напрямую.
Для работы с узлами под управлением ОС Windows используйте модуль ansible.windows.win_find.

Параметры#

Модуль принимает следующие параметры:

age#

Возраст файла. Возвращает файлы, возраст которых равен или превышает указанное время.

Используйте отрицательное значение возраста, чтобы найти файлы, возраст которых равен или меньше указанного времени.

Для поиска можно использовать секунды, минуты, часы, дни или недели, указав первую букву любого из этих слов на английском языке, например, 1w.

age_stamp#

Свойство файла, по которому будет проверяться возраст.

Возможные значения:

atime – время последнего доступа;
ctime – время последнего изменения метаданных;
mtime – время последнего изменения содержимого.

Значение по умолчанию: mtime.

contains#

Регулярное выражение, которое должно присутствовать в содержимом файла.

Если параметр read_whole_file=true, поиск выполняется в начале строки (используется re.match()). Если параметр read_whole_file=false, поиск выполняется в любом месте (используется re.search()).

Параметр работает только при file_type=file.

depth#

Максимальное количество уровней для поиска.

Параметр работает только при recurse=true. При recurse=false значение depth всегда равно 1.

По умолчанию глубина поиска не ограничена.

excludes, exclude#

Список шаблонов названий файлов, которые следует исключить из результатов поиска. Тип шаблонов определяется параметром use_regex.

Каждый шаблон сопоставляется только с названием файла без пути (basename).

file_type#

Тип объекта файловой системы, который необходимо найти.

Возможные значения:

any – все типы;
directory – каталог;
file – файл;
link – символическая ссылка.

Значение по умолчанию: file.

follow#

Порядок обработки символических ссылок.

Возможные значения:

false – не переходить по ссылке при поиске;
true – переходить по ссылке и продолжать поиск в файле или каталоге, на который она указывает.

Значение по умолчанию: false.

Важно

Для работы параметра на управляемом узле должен быть установлен Python версии 2.6 или выше.

get_checksum#

Вычисление контрольной суммы SHA1 найденного файла.

Возможные значения:

false – не вычислять контрольную сумму;
true – вычислять контрольную сумму.

Значение по умолчанию: false.

hidden#

Учет скрытых файлов при поиске.

Возможные значения:

false – не учитывать скрытые файлы;
true – учитывать скрытые файлы.

Значение по умолчанию: false.

paths, name, path#

Обязательный параметр.

Список путей к каталогам для поиска. Все пути должны быть полными.

patterns, pattern#

Список шаблонов названий файлов, которые должны быть включены в результаты поиска. Тип шаблонов определяется параметром use_regex.

Значение задается в виде списка в формате YAML в полной или сокращенной форме. При использовании шаблонов, содержащих запятые, необходимо использовать явный список YAML, чтобы избежать нежелательного разбиения строки.

Каждый шаблон сопоставляется только с названием файла без пути (basename).

Если включен режим regexen (use_regex=true), шаблон должен быть полноценным регулярным выражением, и совпадение должно охватывать всю строку (эквивалентно ^pattern$). Например, чтобы найти файлы, заканчивающиеся на .default, нужно указать .*\.default, а не просто \.default.

Значение по умолчанию: [] (внутренне интерпретируется как * при use_regex=false или .* при use_regex=true).

read_whole_file#

Способ поиска регулярного выражения (contains) в файлах.

Возможные значения:

false – обрабатывать файл построчно, используя функцию re.match.
true – загрузить файл в память целиком и найти совпадения с помощью функции re.search. Может повлиять на производительность при работе с большими файлами.

Значение по умолчанию: false.

recurse#

Рекурсивный поиск в каталогах.

Возможные значения:

false – искать только в указанном каталоге;
true – искать в указанном каталоге и его подкаталогах.

Значение по умолчанию: false.

size#

Размер файла.

Возвращает файлы, размер которых равен или превышает указанный размер.

Используйте отрицательное значение для поиска файлов, размер которых равен или меньше указанного.

Значение может быть задано как целое число (в байтах) или с использованием приставки единицы измерения:

b – байт;
k – килобайт;
m – мегабайт;
g – гигабайт;
t – терабайт.

Размер каталогов не учитывается.

use_regex#

Способ интерпретации шаблонов, указанных в параметрах excludes и patterns.

Возможные значения:

false – шаблоны обрабатываются как маски оболочки (shell-style patterns или glob patterns), например, *.log, file_*.txt, backup-??.tar.gz.
true – шаблоны считаются регулярными выражениями Python и интерпретируются с использованием модуля re. В этом режиме шаблон должен полностью соответствовать названию файла.

Значение по умолчанию: false.

Возвращаемые значения#

В этом списке указаны только возвращаемые значения, специфичные для модуля ansible.builtin.find.

examined – количество проверенных объектов файловой системы.

Условия: при успешном выполнении.
files – список совпадений, найденных по заданным условиям. Каждый элемент списка – словарь со сведениями о найденном объекте, аналогично модулю ansible.builtin.stat.

Условия: при успешном выполнении.
matched – количество совпадений.

Условия: при успешном выполнении.
skipped_paths – словарь, в котором ключи – пропущенные пути, а значения – причины пропуска. Условия: при успешном выполнении.

Атрибуты#

Атрибуты определяют функции Ansible, которые может использовать модуль.

Атрибут	Описание
`check_mode`	Модуль работает в режиме проверки (`check_mode`) в полном объеме.
`diff_mode`	Модуль не поддерживает режим сравнения.
`platform`	Модуль поддерживает только POSIX-совместимые ОС.

Примеры#

Для изучения возможностей модуля ознакомьтесь с приведенными ниже примерами.

Поиск файла по возрасту#

Следующий пример демонстрирует рекурсивный поиск файла старше двух дней в каталоге /tmp/:

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

Поиск файлов по размеру и расширению#

Следующий пример демонстрирует поиск файлов .old и .log.gz размером более 10 МБ:

---
# ...
  tasks:
    - 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

Поиск по регулярному выражению#

Следующий пример демонстрирует поиск файла по регулярному выражению:

---
# ...
  tasks:
    - 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: true

Поиск по содержимому#

Следующий пример демонстрирует рекурсивный поиск файла по наличию в нем слова astra:

---
# ...
  tasks:
    - name: Find /var/log files containing the word astra
      ansible.builtin.find:
        paths: /var/log
        file_type: file
        contains: astra
        read_whole_file: true
        patterns: '^.*\.log$'
        use_regex: true
        recurse: true