community.routeros.api_find_and_modify 模块 – 使用 API 查找和修改信息

注意

此模块是 community.routeros 集合（版本 3.1.0）的一部分。

如果您正在使用 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.routeros。您需要其他要求才能使用此模块，有关详细信息，请参阅 要求。

要在 Playbook 中使用它，请指定：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 布尔值	是否允许未找到任何匹配项。 如果未指定，则此值由 require_matches_min 是否为 0 或更大值推断得出。 选择 false true
ca_path 路径 在 community.routeros 1.2.0 中添加	PEM 格式的文件，其中包含用于证书验证的 CA 证书。 另请参阅 validate_cert_hostname。仅当 tls=true 和 validate_certs=true 时使用。
encoding 字符串 在 community.routeros 2.1.0 中添加	在与 RouterOS 设备通信时使用指定的编码。 默认为 ASCII。请注意，UTF-8 需要 librouteros 3.2.1 或更高版本。 默认值： "ASCII"
find 字典 / 必需	要搜索的字段。 该模块将只考虑给定的 path 中与此处提供的所有字段匹配的条目。 使用 YAML ~，或在键前加上 !，以指定未设置的值。 请注意，如果此处指定的字典为空，则将匹配路径中的每个条目。
force_no_cert 布尔值 在 community.routeros 2.4.0 中添加	当 tls=true 时，设置为 true 以在没有证书的情况下连接。 另请参阅 validate_certs。 注意：这会强制使用匿名 Diffie-Hellman (ADH) 密码。该协议容易受到中间人攻击，因为交换中使用的密钥未经过身份验证。不要只是在没有证书的情况下连接以“使事情正常工作”，请查看 validate_certs 和 ca_path。 选择 false ← (默认) true
hostname 字符串 / 必需	RouterOS 主机名 API。
password 字符串 / 必需	RouterOS 用户密码。
路径 字符串 / 必需	要查询的路径。 一个示例值是 ip address。这等效于在 RouterOS CLI 中运行 /ip address。
port 整数	RouterOS API 端口。如果设置了 tls，则端口将应用于 TLS/SSL 连接。 HTTP API 的默认值为 8728，HTTPS API 的默认值为 8729。
require_matches_max 整数	确保匹配的数量不超过此数字。 如果匹配的数量超出此数字，则会失败，不会修改任何内容。 如果未指定，则没有上限。
require_matches_min 整数	确保匹配的数量不少于此数字。 如果匹配的数量少于此数字，则会失败，不会修改任何内容。 默认值： 0
timeout 整数 在 community.routeros 2.3.0 中添加	请求的超时时间。 默认值： 10
tls 别名：ssl 布尔值	如果设置，将使用 TLS 进行 RouterOS API 连接。 选择 false ← (默认) true
username 字符串 / 必需	RouterOS 登录用户。
validate_cert_hostname 布尔值 在 community.routeros 1.2.0 中添加	设置为 true 以验证证书中的主机名。 另请参阅 validate_certs。仅当 tls=true 和 validate_certs=true 时使用。 选择 false ← (默认) true
validate_certs 布尔值 在 community.routeros 1.2.0 中添加	设置为 false 以跳过 TLS 证书的验证。 另请参阅 validate_cert_hostname。仅当 tls=true 时使用。 注意：与其简单地禁用证书验证以“使事情正常工作”，请考虑创建您自己的 CA 证书并使用它来签署用于您的路由器的证书。您可以使用 ca_path 选项告诉模块您的 CA 证书。 选择 false true ← (默认)
values 字典 / 必需	在所有匹配 find 中条件的条目上，将此选项的键设置为此处指定的值。 使用 YAML ~，或在键前面加上 !，以指定取消设置值。

属性

属性	支持	描述
action_group	操作组： community.routeros.api	在 module_defaults 中使用 group/community.routeros.api 为此模块设置默认值。
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

用于 RouterOS API 的 Ansible 模块。

community.routeros.api_facts

使用 API 从运行 MikroTik RouterOS 的远程设备收集事实。

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)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 寻求帮助 (RouterOS)
• 提交错误报告
• 请求功能
• 通信