Модуль community.routeros.api_find_and_modify — поиск и изменение информации с помощью API

Примечание

Этот модуль входит в коллекцию community.routeros (версия 3.20.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Чтобы установить её, используйте: ansible-galaxy collection install community.routeros. Для работы с этим модулем могут потребоваться дополнительные компоненты; подробности см. в разделе Требования.

Чтобы использовать модуль в сценарии, укажите: community.routeros.api_find_and_modify.

Добавлено в community.routeros 2.1.0

Краткое описание
Требования
Параметры
Атрибуты
Примечания
См. также
Примеры
Возвращаемые значения

Краткое описание

Позволяет находить записи по пути, соответствующие заданным условиям, и изменять значения этих записей.
Используйте модуль community.routeros.api_find_and_modify, чтобы задать определённые значения для всех записей по пути или за один шаг изменить несколько записей разными способами.

Требования

На узле, выполняющем этот модуль, должны быть установлены следующие компоненты.

librouteros
Python >= 3.6 (для librouteros)

Параметры

Параметр	Комментарии
allow_no_matches boolean	Разрешить отсутствие совпадений. Если параметр не указан, его значение определяется тем, равно ли `require_matches_min` нулю или больше. Варианты: `false` `true`
ca_path path добавлено в community.routeros 1.2.0	Файл в формате PEM, содержащий сертификат УЦ для проверки сертификатов. См. также `validate_cert_hostname`. Используется только при `tls=true` и `validate_certs=true`.
encoding string добавлено в community.routeros 2.1.0	Использовать указанную кодировку при взаимодействии с устройством RouterOS. По умолчанию используется `ASCII`. Обратите внимание: для `UTF-8` требуется librouteros версии 3.2.1 или новее. По умолчанию: `"ASCII"`
find dictionary / обязательный	Поля для поиска. Модуль будет рассматривать только записи в указанном `path`, соответствующие всем заданным здесь полям. Чтобы указать неустановленное значение, используйте YAML `~` или добавьте `!` перед ключами. Обратите внимание: если указанный здесь словарь пуст, совпадением будет считаться каждая запись по этому пути.
force_no_cert boolean добавлено в community.routeros 2.4.0	Установите значение `true`, чтобы подключаться без сертификата при `tls=true`. См. также `validate_certs`. Примечание: это принудительно включает использование анонимных шифров Диффи — Хеллмана (ADH). Протокол уязвим для атак типа «человек посередине», поскольку ключи, используемые при обмене, не проходят аутентификацию. Вместо того чтобы просто подключаться без сертификата, чтобы «всё заработало», ознакомьтесь с `validate_certs` и `ca_path`. Варианты: `false` ← (по умолчанию) `true`
hostname string / обязательный	Имя узла RouterOS для API.
ignore_builtin boolean добавлено в community.routeros 3.7.0	Игнорировать встроенные записи. По умолчанию они учитываются (`false`). Если задать `true`, они учитываться не будут. Как правило, рекомендуется задавать `true`, если только вам действительно не нужно изменять встроенные записи. Обратите внимание: текущее значение по умолчанию (`false`) устарело и будет изменено на `true` в community.routeros 4.0.0. Варианты: `false` `true`
ignore_dynamic boolean добавлено в community.routeros 3.7.0	Игнорировать динамические записи. По умолчанию они учитываются (`false`). Если задать `true`, они учитываться не будут. Как правило, рекомендуется задавать `true`, если только вам действительно не нужно изменять динамические записи. Обратите внимание: текущее значение по умолчанию (`false`) устарело и будет изменено на `true` в community.routeros 4.0.0. Варианты: `false` `true`
password string / обязательный	Пароль пользователя RouterOS.
path string / обязательный	Путь для запроса. Пример значения: `ip address`. Это эквивалентно выполнению `/ip address` в интерфейсе командной строки RouterOS.
port integer	Порт API RouterOS. Если задано `tls`, порт будет использоваться для TLS/SSL-соединения. Порты по умолчанию: `8728` для HTTP API и `8729` для HTTPS API.
require_matches_max integer	Проверить, что количество совпадений не превышает это число. Если совпадений больше, завершить работу с ошибкой, не изменяя данные. Если параметр не указан, верхний предел не задаётся.
require_matches_min integer	Проверить, что количество совпадений не меньше этого числа. Если совпадений меньше, завершить работу с ошибкой, не изменяя данные. По умолчанию: `0`
timeout integer добавлено в community.routeros 2.3.0	Время ожидания ответа на запрос. По умолчанию: `10`
tls псевдонимы: ssl boolean	Если параметр установлен, для подключения к API RouterOS будет использоваться TLS. Варианты: `false` ← (по умолчанию) `true`
username string / обязательный	Имя пользователя для входа в RouterOS.
validate_cert_hostname boolean добавлено в community.routeros 1.2.0	Установите значение `true`, чтобы проверять имена узлов в сертификатах. См. также `validate_certs`. Используется только при `tls=true` и `validate_certs=true`. Варианты: `false` ← (по умолчанию) `true`
validate_certs boolean добавлено в community.routeros 1.2.0	Установите значение `false`, чтобы отключить проверку TLS-сертификатов. См. также `validate_cert_hostname`. Используется только при `tls=true`. Примечание: вместо простого отключения проверки сертификатов, чтобы «всё заработало», рассмотрите возможность создания собственного сертификата УЦ и подписания им сертификатов, используемых вашим маршрутизатором. Сообщить модулю о сертификате УЦ можно с помощью параметра `ca_path`. Варианты: `false` `true` ← (по умолчанию)
values dictionary / обязательный	Для всех записей, соответствующих условиям в `find`, установить ключи этого параметра в указанные здесь значения. Чтобы сбросить значение, используйте YAML `~` или добавьте `!` перед ключами.

Атрибуты

Атрибут	Поддержка	Описание
action_group	Группа действий: community.routeros.api	Используйте `group/community.routeros.api` в `module_defaults`, чтобы задать значения по умолчанию для этого модуля.
check_mode	Поддержка: полная	Модуль можно запускать в режиме `check_mode`; в этом случае он возвращает прогнозируемый статус изменений, не изменяя целевую систему.
diff_mode	Поддержка: полная	В режиме сравнения изменений модуль возвращает сведения о том, что изменилось (или, возможно, должно измениться в `check_mode`).
idempotent	Поддержка: полная	При повторном запуске подряд вне режима проверки с теми же аргументами второй запуск сообщает об отсутствии изменений. Предполагается, что система, которой управляет модуль или к которой он обращается, не изменилась существенным образом.
platform	Платформа: RouterOS	Целевая ОС или семейства ОС, с которыми можно работать.

Примечания

Примечание

Если нужно изменить значения на основе их прежних значений (например, заменить все комментарии «foo» на «bar») и убедиться, что таких значений не меньше N, используйте require_matches_min=N вместе с allow_no_matches=true. В этом случае модуль завершится с ошибкой, если таких записей меньше N, но не завершится с ошибкой при отсутствии совпадений. Последнее необходимо для идемпотентности задачи: после изменения значений совпадений больше быть не должно.

См. также

community.routeros.api: Модуль Ansible для API RouterOS.
community.routeros.api_facts: Сбор фактов с удалённых устройств под управлением MikroTik RouterOS с помощью API.
community.routeros.api_modify: Изменение данных по путям с помощью API.
community.routeros.api_info: Получение информации через API.
Подключение к устройствам RouterOS с помощью API RouterOS: Подключение к устройствам RouterOS с помощью API RouterOS.

Примеры

---
- name: Rename bridge from 'bridge' to 'my-bridge'
  community.routeros.api_find_and_modify:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: interface bridge
    find:
      name: bridge
    values:
      name: my-bridge
    # Always ignore dynamic and builtin entries
    # (not relevant for this path, but generally recommended)
    ignore_dynamic: true
    ignore_builtin: true

- name: Change IP address to 192.168.1.1 for interface bridge - assuming there is only one
  community.routeros.api_find_and_modify:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: ip address
    find:
      interface: bridge
    values:
      address: "192.168.1.1/24"
    # If there are zero entries, or more than one: fail! We expected that
    # exactly one is configured.
    require_matches_min: 1
    require_matches_max: 1
    # Always ignore dynamic and builtin entries
    # (not relevant for this path, but generally recommended)
    ignore_dynamic: true
    ignore_builtin: true

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

Общие возвращаемые значения описаны здесь; ниже перечислены поля, уникальные для этого модуля:

Ключ	Описание
match_count integer	Количество записей, соответствующих критериям в `find`. Возвращается: success Пример: `1`
modify__count integer	Количество изменённых записей. Возвращается: success Пример: `1`
new_data list / элементы=dictionary	Список всех элементов текущего пути после внесения изменений. Возвращается: success Пример: `[{".id": "*1", "actual-interface": "bridge", "address": "192.168.1.1/24", "comment": "awesome", "disabled": false, "dynamic": false, "interface": "bridge", "invalid": false, "network": "192.168.1.0"}]`
old_data list / элементы=dictionary	Список всех элементов текущего пути до внесения изменений. Возвращается: success Пример: `[{".id": "*1", "actual-interface": "bridge", "address": "192.168.88.1/24", "comment": "defconf", "disabled": false, "dynamic": false, "interface": "bridge", "invalid": false, "network": "192.168.88.0"}]`

Авторы

Felix Fontein (@felixfontein)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/routeros/api_find_and_modify_module.html