community.routeros.api 模块 – Ansible RouterOS API 模块
注意
此模块是 community.routeros 集合 (版本 3.1.0) 的一部分。
如果您使用的是 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查是否已安装它，请运行 ansible-galaxy collection list。
要安装它，请使用：ansible-galaxy collection install community.routeros。您需要其他需求才能使用此模块，有关详细信息，请参阅 需求。
要在 playbook 中使用它，请指定：community.routeros.api。
概要
使用 Python
librouteros库的 RouterOS API Ansible 模块。此模块可以通过 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 中添加 |
在 |
|
支持：不支持 |
可以在 |
|
支持：不支持 |
在差异模式下，将返回有关更改内容（或在 |
|
平台： 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返回的字典元素的列表。 返回：始终 示例： |