community.routeros.api 模块 – 用于 RouterOS API 的 Ansible 模块
注意
此模块是 community.routeros 集合（版本 3.1.0）的一部分。
如果您使用的是 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。
要安装它，请使用：ansible-galaxy collection install community.routeros。您需要其他要求才能使用此模块，请参阅 要求 了解详细信息。
要在 playbook 中使用它，请指定：community.routeros.api。
概要
用于 RouterOS API 的 Ansible 模块，使用 Python
librouteros库。此模块可以通过 API 在 RouterOS 中添加、删除、更新、查询和执行任意命令。
要求
执行此模块的主机需要满足以下要求。
librouteros
Python >= 3.6 (对于 librouteros)
参数
参数 |
注释 |
|---|---|
将选定路径中的选定参数添加到 RouterOS 配置中。 例如 相当于 RouterOS CLI 中的 |
|
包含用于证书验证的 CA 证书的 PEM 格式文件。 另请参阅 |
|
在选定路径中执行任何/任意命令，在命令后我们可以添加 例如，路径 例如，路径 |
|
与 RouterOS 设备通信时使用指定的编码。 默认为 默认值： |
|
为从 RouterOS API 中选定的查询属性提供给定路径的扩展查询。 扩展查询允许连词输入。如果没有匹配的条目，将返回一个空列表。 |
|
要返回的属性列表。 在 |
|
允许限制返回的对象。 此处的条件必须全部匹配。 |
|
用于匹配的运算符。 对于相等，请使用 使用 必须指定 选项
|
|
一个条件列表，其中至少有一个条件必须匹配。 必须指定 |
|
要匹配的属性。必须是 |
|
用于匹配的运算符。 对于相等，请使用 使用 选项
|
|
要比较的值。对于 |
|
当 另请参阅 注意： 这会强制使用匿名 Diffie-Hellman (ADH) 密码。该协议容易受到中间人攻击，因为交换中使用的密钥未经过身份验证。不要仅仅为了 “让事情工作” 而在没有证书的情况下连接，请查看 选项
|
|
RouterOS 主机名 API。 |
|
RouterOS 用户密码。 |
|
所有其他参数的主要路径。 如果未设置其他参数，则 api 将返回所选路径中的所有项目。 示例 |
|
RouterOS api 端口。如果设置了 HTTP API 的默认值为 |
|
从 RouterOS aip 中查询给定路径的所选查询属性。 WHERE 是扩展查询的关键字。WHERE 格式是“键 操作符 值” - 用空格分隔。 WHERE 有效的操作符包括 示例路径 示例路径 示例路径 在 RouterOS CLI 中等效于 |
|
通过 ‘.id’ 从 RouterOS 中删除配置/值。 示例 在 RouterOS CLI 中等效于 请注意，RouterOS CLI 中的 |
|
请求的超时时间。 默认值： |
|
如果设置，TLS 将用于 RouterOS API 连接。 选项
|
|
通过所选路径中的 ‘.id’ 在 RouterOS 中更新配置/值。 示例 在 RouterOS CLI 中等效于 请注意，RouterOS CLI 中的 |
|
RouterOS 登录用户。 |
|
设置为 另请参阅 选项
|
|
设置为 另请参阅 注意： 不要仅仅为了 “让事情工作” 而停用证书验证，请考虑创建您自己的 CA 证书，并用它来签署用于您的路由器的证书。您可以使用 选项
|
属性
属性 |
支持 |
描述 |
|---|---|---|
操作组： community.routeros.api 在 community.routeros 2.1.0 中添加 |
在 |
|
支持：无 |
可以在 |
|
支持：无 |
在 diff 模式下，将返回有关已更改内容（或在 |
|
平台： RouterOS |
可以对其进行操作的目标操作系统/系列。 |
说明
注意
使用 community.routeros.api_modify 和 community.routeros.api_find_and_modify 模块进行更具体的修改，以及 community.routeros.api_info 模块，以更受控制的方式返回路径的所有条目。
另请参阅
另请参阅
- 如何引用和取消引用命令和参数
如何引用和取消引用命令和参数
- community.routeros.api_facts
使用 API 从运行 MikroTik RouterOS 的远程设备收集事实。
- community.routeros.api_find_and_modify
使用 API 查找和修改信息。
- community.routeros.api_info
从 API 检索信息。
- community.routeros.api_modify
使用 API 修改路径中的数据。
- 如何使用 RouterOS API 连接到 RouterOS 设备
如何使用 RouterOS API 连接到 RouterOS 设备
示例
- name: Get example - ip address print
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "ip address"
register: ipaddrd_printout
- name: Dump "Get example" output
ansible.builtin.debug:
msg: '{{ ipaddrd_printout }}'
- name: Add example - ip address
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "ip address"
add: "address=192.168.255.10/24 interface=ether2"
- name: Query example - ".id, address" in "ip address WHERE address == 192.168.255.10/24"
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "ip address"
query: ".id address WHERE address == {{ ip2 }}"
register: queryout
- name: Dump "Query example" output
ansible.builtin.debug:
msg: '{{ queryout }}'
- name: Extended query example - ".id,address,network" where address is not 192.168.255.10/24 or is 10.20.36.20/24
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "ip address"
extended_query:
attributes:
- network
- address
- .id
where:
- attribute: "network"
is: "=="
value: "192.168.255.0"
- or:
- attribute: "address"
is: "!="
value: "192.168.255.10/24"
- attribute: "address"
is: "eq"
value: "10.20.36.20/24"
- attribute: "network"
is: "in"
value:
- "10.20.36.0"
- "192.168.255.0"
register: extended_queryout
- name: Dump "Extended query example" output
ansible.builtin.debug:
msg: '{{ extended_queryout }}'
- name: Update example - ether2 ip address with ".id = *14"
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "ip address"
update: >-
.id=*14
address=192.168.255.20/24
comment={{ 'Update 192.168.255.10/24 to 192.168.255.20/24 on ether2' | community.routeros.quote_argument_value }}
- name: Remove example - ether2 ip 192.168.255.20/24 with ".id = *14"
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "ip address"
remove: "*14"
- name: Arbitrary command example "/system identity print"
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "system identity"
cmd: "print"
register: arbitraryout
- name: Dump "Arbitrary command example" output
ansible.builtin.debug:
msg: '{{ arbitraryout }}'
返回值
通用返回值已在此处记录 这里，以下是此模块独有的字段
键 |
描述 |
|---|---|
所有输出都以列表形式返回，列表中的元素为从 RouterOS API 返回的字典。 返回： 总是 示例： |