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

Примечание

Этот модуль входит в коллекцию community.routeros (версия 2.19.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` равно 0 или больше. Варианты: `false` `true`
ca_path path добавлено в community.routeros 1.2.0	Файл в формате PEM, содержащий сертификат CA, используемый для проверки сертификатов. См. также `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`. Примечание: это принудительно использует анонимные шифры Diffie-Hellman (ADH). Протокол уязвим для атак «человек посередине», так как ключи, используемые в обмене, не аутентифицированы. Вместо простого подключения без сертификата для «работы» ознакомьтесь с `validate_certs` и `ca_path`. Варианты: `false` ← (по умолчанию) `true`
hostname string / обязательно	Имя хоста RouterOS API.
password string / обязательно	Пароль пользователя RouterOS.
path string / обязательно	Путь для запроса. Пример значения `ip address`. Эквивалентно выполнению `/ip address` в консоли RouterOS.
port integer	Порт RouterOS API. Если `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	Если задано, для подключения к RouterOS API будет использован 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 и использования его для подписания сертификатов, используемых для вашего маршрутизатора. Вы можете сообщить модулю о вашем сертификате CA с помощью параметра `ca_path`. Варианты: `false` `true` ← (по умолчанию)

values

словарь / обязательный

Во всех записях, соответствующих условиям в find, задайте ключи этого параметра указанными здесь значениями.

Используйте YAML ~, или добавьте префикс к ключам !, чтобы указать на удаление значения.

Атрибуты

Атрибут	Поддержка	Описание
action_group	Группа действий: community.routeros.api	Используйте `group/community.routeros.api` в `module_defaults` для установки значений по умолчанию для данного модуля.
check_mode	Поддержка: полная	Может работать в `check_mode` и возвращать прогноз о внесенных изменениях, не изменяя целевой объект.
diff_mode	Поддержка: полная	При работе в режиме diff, вернёт детали о том, что изменилось (или, возможно, нуждается в изменении в `check_mode`).
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

- 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

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

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

Ключ	Описание
match_count целое число	Количество записей, соответствующих критериям в `find`. Возвращается: успех Пример: `1`
modify__count целое число	Количество изменённых записей. Возвращается: успех Пример: `1`
new_data список / элементы=словарь	Список всех элементов для текущего пути после внесения изменений. Возвращается: успех Пример: `[{".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 список / элементы=словарь	Список всех элементов для текущего пути до внесения изменений. Возвращается: успех Пример: `[{".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–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/routeros/api_find_and_modify_module.html