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 中新增	包含用于证书验证的 CA 证书的 PEM 格式文件。另请参见 `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 中新增	设置为 `true` 以在 `tls=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`
用户名字符串 / 必需	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	支持：完全支持	在差异模式下，将返回关于已更改内容（或在 `check_mode` 中可能需要更改的内容）的详细信息。
平台	平台： 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)

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

作者

集合链接