总结

通过API (Application Programmable Interface)接口，用户可以创建自定义的软件解决方案，与RouterOS雷电竞app下载官方版苹果进行通信，实现信息收集、配置调整和路由器管理。l雷竞技API严格遵循命令行界面(CLI)的语法。它可以用来创建转换或自定义配置工具，以帮助使用RouterOS轻松运行和管理路由器。l雷竞技

在尝试建立API连接之前，必须启用API服务。默认情况下，API使用TCP:8728和TCP:8729(安全)。

API-ssl服务能够在两种模式下工作——带证书和不带证书。在这种情况下，没有使用证书/ ip服务那么匿名迪菲-赫尔曼密码必须用来建立连接。如果使用了证书，则可以建立TLS会话。

协议

与路由器的通信是通过发送句子和接收一个或多个句子来完成的。句子是一个以零长度单词结尾的单词序列。单词是句子的一部分，以某种方式编码——编码长度和数据。通信通过向路由器发送语句并接收对所发送语句的回复来实现。使用API发送到路由器的每个句子都应该包含一个命令，作为第一个单词，然后是没有特定顺序的单词，句子的结尾用一个零长度的单词标记。当路由器接收到一个完整的句子(命令词，没有或多个属性词，零长度词)时，它被计算并执行，然后形成并返回一个应答。

API的话

单词是句子的一部分。每个单词都必须以特定的方式编码——单词长度后跟单词内容。单词的长度应该以将要发送的字节数的形式给出。

单词的长度编码如下:

长度值 字节数 编码
0 <= len <= 0x7F 1 Len最低字节
0x80 <= len <= 0x3FFF 2 Len | 0x8000，低两个字节
0x4000 <= len <= 0x1FFFFF 3. len | 0xC00000，低三个字节
0x200000 <= len <= 0xFFFFFFF 4 len | 0xE0000000
Len >= 0x10000000 5 0xF0和len为4个字节


  • 每个字被编码为长度，后面跟着内容的字节数;
  • 单词被组合成句子。句尾以零长度的词结束;
  • 该方案允许的编码长度为0 x7fffffffff，只支持4字节长度;
  • len字节优先发送最高有效位(网络顺序);
  • 如果单词的第一个字节是> = 0 xf8，则它是一个保留的控制字节。在接收到未知的控制字节后，API客户端无法继续，因为它不知道如何解释下面的字节;
  • 当前，没有使用控制字节;

一般来说,单词可以这样描述<<编码字长><字内容> >。字内容可分为5部分:命令字，属性词，API属性字。查询词，和回复的话

命令字

句子中的第一个单词必须是命令，后跟属性词和零长度词或结束词。命令字的名称应该以“/”开头。命令的名称紧跟CLI，空格替换为'/'。有些命令是特定于API的;

命令字结构的严格顺序:

  • 编码长度
  • 内容的前缀/
  • CLI转换命令


API专用命令:

登录取消

命令字内容示例:

/登录
/ user /主动/听
/ / vlan /删除界面
/系统/重新启动

属性词

每一个命令字有自己的属性词取决于内容。

属性词结构按此顺序由5部分组成:

  • 编码长度
  • 内容前缀等于符号-=
  • 属性名称
  • 分隔等号-=
  • 属性值(如果有)。该属性可能没有值


值可以容纳多个平等的符号的价值属性词因为单词的编码方式。

Value可以为空。


没有编码长度前缀的示例:

=地址= 10.0.0.1
= = iu = c3Eeg名称
= disable-running-check =是的


属性词和API参数的顺序并不重要，也不应该依赖


API属性字

API属性字结构严格按顺序排列:

  • 编码长度
  • 内容前缀加上点。
  • 属性名称
  • 名称后加等号=标志
  • 属性值

目前，唯一这样的API属性是标签。

如果句子中包含API属性字标记后，路由器对该标记的句子的回复中返回的每个句子都将被标记为相同的标记。

查询词

句子可以具有限制其作用域的附加查询参数。详细的解释见查询部分。

使用查询词属性的句子示例:

/interface/print ?type=ether ?type=vlan ?#|!


  • 查询词以“?”开头。
  • 目前，只有打印命令处理查询词。

查询词的顺序很重要


回复的话

它仅由路由器作为对从客户端接收到的完整句子的响应而发送。

  • 回复的第一个词以“!”开头;
  • 发送的每个句子至少产生一个回复(如果连接没有被终止);
  • 每个句子的最后一个回复是包含第一个单词的回复完成!；
  • 错误和异常情况开始于陷阱!；
  • 数据回复以!再保险
  • 如果API连接关闭，RouterOS发送l雷竞技致命!用一个理由作为回复，然后关闭连接;

API的句子

API语句是使用API进行交流的主要对象。

  • 空句子会被忽略。
  • 在接收到零长度单词后处理一个句子。
  • 客户端在登录之前可以发送的句子的数量和大小是有限制的。
  • 定语的顺序不应该依赖。由于顺序和计数是可变的.proplist属性。
  • 句子结构如下:
    • 第一个单词应该包含a命令字；
    • 应该包含长度为零的词结束:结束句子;
    • 可以不包含还是包含多个属性词。定语在句子中没有特定的顺序，顺序并不重要属性词；
    • 可以不包含还是包含多个查询词。的顺序查询词在句子中是重要的。

长度为零的词结束句子。如果不提供，路由器将不会开始评估发送的单词，并将所有输入视为同一句子的一部分。

初始登录

注意:每个命令和响应都以一个空单词结尾。

v6.43之后的登录方法:

/登录
= name = admin
密码= =
完成!


  • 现在，客户机在第一条消息中发送用户名和密码。
  • 密码以明文形式发送。
  • 如果出现错误，则回复包含=message=错误消息。
  • 在成功登录的情况下，客户机可以开始发出命令。

标签

  • 可以同时运行多个命令，而不需要等待前一个命令完成。如果API客户机正在执行此操作，并且需要区分命令响应，则可以使用标签'命令句中的API参数。
  • 如果你把“标签参数，在命令句中使用非空值，然后使用'标签参数具有完全相同的值将包含在此命令生成的所有响应中。
  • 如果你不包括标签参数或其值为空，则此命令的所有响应都不具有'标签的参数。

命令的描述

  • /取消
    • 可选参数:=tag=要取消的命令的标记，如果没有它，将取消所有正在运行的命令
    • 不会自行取消
    • 所有被取消的命令都被中断，并且在通常情况下生成'!陷阱'和'!做过的反应
    • 请注意/cancel是单独的命令，可以有它自己唯一的'。Tag '参数，与该命令的'= Tag '参数无关
  • 听
    • 监听命令在控制台打印命令可用的地方可用，但它并不是在任何地方都有预期的效果(即可能无法工作)。
    • ”!再保险”句子是在特定条目列表中发生变化时生成的
    • 当条目被删除或以任何其他方式消失时，!再保险'句子包含值'=.dead=yes'
    • 此命令不终止。要终止它，使用/取消命令。
  • getall
    • getall命令在控制台打印命令可用的地方可用(getall的别名打印)．
    • 回复包含=.id=项目内部编号财产。
  • 打印
    • API打印命令与控制台打印命令的区别如下:
      • 论点不被支持的地方。可以使用查询词过滤项目(见下文)。
      • proplist参数是一个逗号分隔的属性名列表，返回的项应该包含这些属性名。
        • 返回的项目可能具有其他属性。
        • 未定义返回属性的顺序。
        • 如果列表包含重复项，则没有定义对这些项的处理。
        • 如果一个属性出现在.proplist”，但不在项目中，则该项目不具有此属性值(?Name将对该项求值为false)。
        • 如果“.proplist”则根据打印命令的要求包括所有属性，甚至包括那些访问时间较慢的属性(如文件内容和性能计数器)。因此使用.proplist是鼓励。的遗漏.proplist如果设置了"=detail="参数，可能会降低性能。

查询

的打印命令接受限制返回语句集的查询词。

  • 查询词以“?”开头。
  • 查询词的顺序很重要。查询从第一个单词开始计算。
  • 对列表中的每个项求值查询。如果查询成功，则处理该项，如果查询失败，则忽略该项。
  • 查询是使用一堆布尔值求值的。最初，堆栈包含无限大的“真”值。在求值结束时，如果堆栈至少包含一个“false”值，则查询失败。
  • 查询词按照以下规则运行:
查询 描述
名字吗? 如果项的值为property，则推送'true'名字，如果不是，则为false。
- name ? 如果一个项目没有属性值，则推送'true'名字，否则为“false”。
？名字=x
? =名字=x		 如果属性为true，则推送'true'名字它的值等于x，否则为“false”。
< name = ?x 如果属性为true，则推送'true'名字值小于x，否则为“false”。
? > name =x 如果属性为true，则推送'true'名字值大于x，否则为“false”。
# ?操作 对堆栈中的值应用操作。
  • 从左到右计算操作字符串。
  • 后跟任何其他字符或字尾的十进制数字序列被解释为堆栈索引。顶值的索引为0。
  • 如果索引后跟一个字符，则会压入该索引处值的副本。
  • 后面跟字尾的索引用该索引处的值替换所有值。
  • ！字符将顶值替换为相反的值。
  • ＆弹出两个值并推入逻辑'和'操作的结果。
  • |弹出两个值并推入逻辑“或”操作的结果。
  • 。在索引不做任何事情之后。
  • 。在另一个字符压入顶值的副本之后。


正则表达式在API中不受支持，所以不要尝试使用～象征


例子:

  • 获取所有以太网和VLAN接口:
/interface/print ?type=ether ?type=vlan ?#|
  • 获取所有带有非空注释的路由:
/ ip /线路/打印吗? = >发表评论

OID

的打印命令可以返回SNMP中可用的属性的OID值。

在控制台中，可以通过运行'print OID '命令来查看OID值。在API中，这些属性的名称以“”结尾。Oid "，并且可以通过将它们的名称添加到'.proplist'的值中来检索。一个例子:


/系统/资源/打印
= .proplist =正常运行时间、cpu负载、uptime.oid cpu-load.oid
!再保险
=正常运行时间= 01:22:53
= cpu负载= 0
= uptime.oid = .1.3.6.1.2.1.1.3.0
= cpu-load.oid = .1.3.6.1.2.1.25.3.3.1.2.1

完成!


陷阱!

当由于某种原因API语句失败时，将发送陷阱作为返回消息属性和在某些情况下类别论点。

消息

当API语句失败时，将返回一些通用消息或来自所使用的内部进程的消息，以提供有关失败的更多细节

<<< /ip/address/add <<< =address=192.168.88.1 <<< =interface=asdf <<< >>> !trap >>> =category=1 >>> =message=input不匹配任何interface的值


类别

如果是一般错误，则对其进行分类并返回错误类别。此属性的可能值为

  • 0 -缺少项目或命令
  • 1 -参数值失败
  • 命令执行中断
  • 3 -脚本相关的失败
  • 4 -一般失败
  • API相关失效
  • 6 - TTY相关故障
  • 7 -使用return命令生成的值

命令示例

/系统/包/ getall

/系统/包/ getall

!再保险
= .id = * 5802
=禁用=没有
= namel雷竞技 = routeros-x86
= = 3.0 beta2版本
= 16:24:41构建时= 10月/ 18/2006
=计划=

!再保险
= .id = * 5805
=禁用=没有
= name =系统
= = 3.0 beta2版本
= 17:20:46构建时= 10月/ 18/2006
=计划=

…更多的句子……
!再保险
= .id = * 5902
=禁用=没有
= name =高级工具
= = 3.0 beta2版本
= 17:20:49构建时= 10月/ 18/2006
=计划=

完成!

/ user /主动/听

/ user /主动/听

!再保险
= .id = * 68
=半径=没有
=, = 10月/ 08:40:42 24/2006
= name = admin
=地址= 0.0.0.0
通过= =控制台

!再保险
= .id = * 68
= .dead =是的

…更多的句子……

/cancel，同步命令

/登录

完成!
= ret = 856780 b7411eefd3abadee2058c149a3

/登录
= name = admin
= = 005062 f7a5ef124d34675bf3e81f56c556响应

完成!
--首先开始监听接口更改(标签为2)
/接口/听
.tag = 2
--禁用接口(标签为3)
/界面设置
=禁用=是的
= .id = ether1
.tag = 3
--这是为禁用命令(标签3)完成的。
完成!
.tag = 3

--使能接口(标签为4)
/界面设置
=禁用=没有
= .id = ether1
.tag = 4
--这个更新是由第一个set命令(标签3)所做的更改生成的。
!再保险
= .id = * 1
=禁用=是的
=动态=没有
=运行=没有
= name = ether1
= mtu = 1500
= =醚型
.tag = 2

--这是为启用命令(标签4)完成的。
完成!
.tag = 4

--获取接口列表(标签为5)
/ /接口getall
.tag = 5

--这个更新是由第二个set命令(标签4)所做的更改生成的。
!再保险
= .id = * 1
=禁用=没有
=动态=没有
= = yes运行
= name = ether1
= mtu = 1500
= =醚型
.tag = 2

--这些是对gettall命令的回复(标签5)
!再保险
= .id = * 1
=禁用=没有
=动态=没有
= = yes运行
= name = ether1
= mtu = 1500
= =醚型
.tag = 5

!再保险
= .id = * 2
=禁用=没有
=动态=没有
= = yes运行
= name = ether2
= mtu = 1500
= =醚型
.tag = 5

--这里的接口有两个端点(标签5)
完成!
.tag = 5

--停止监听-请求取消带有标记2的命令，取消本身使用标记7
/取消
=标签= 2
.tag = 7

--监听命令中断(标记2)
陷阱!
= = 2级
= =消息打断了
.tag = 2

--取消命令完成(标签7)
完成!
.tag = 7

--监听命令完成(标记2)
完成!
.tag = 2

示例客户机

一个简单的Python3中的API客户端

示例输出:

debian@localhost:~/api-test$ ./api.py 10.0.0.1 admin " << /login <<< >>> !done >>> =ret=93b438ec9b80057c06dd9fe67d56aa9a >>> <<< /login <<< =name=admin <<< =response=00e134102a9d330dd7b1849fedfea3cb57 <<< >>> !done >>> /user/getall <<< /user/getall <<< < >>> !re >>> =。id = * 1 > > > =禁用=没有> > > = name =管理> > > =组=全部> > > =地址= 0.0.0.0/0 > > > =子网掩码= 0.0.0.0  >>> >>> ! 完成> > >

另请参阅

API的例子

不同语言的API实现，由不同的源提供。它们没有任何特定的顺序。

  • 没有标签