MikroTik RouterOS API 操作手册

原文链接：http://wiki.mikrotik.com/wiki/Manual:API

译者：luodichen@126.com

【CSDN排版太乱了，已上传到百度文库，链接：http://wenku.baidu.com/view/dac2c0edaeaad1f346933f11.html】

概述

本文档描述如何使用MikroTik RouterOS API对RouterOS进行配置。使用API（应用程序编程接口）可以定制自己的“WinBox”程序。这篇文档帮助你为RouterOS v3及更新的版本编写简化的或者本地化的路由器配置程序。

API使用8728端口与配置主机通信，该端口在路由器上默认是关闭的，使用如下的命令打开API功能：

/ip service enable api

 

协议

l  协议流由格式化的字序列组成。

l  每个字以字长度开头，其后紧跟若干字节字的内容。

l  若干个字组成一个段（原文sentence(s)，下同），在段的结尾以一个空字作为结束标志。

l  字长度按如下的方式编码：

长度值	字节数	编码方式
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 and len as four bytes

       注:len表示字内容的长度

l  尽管这一方案允许的最大字长度为0x7FFFFFFFF，但只支持最多四个字节的字长度。

l  字节按高位优先（网络字节序）的方式发送。

l  如果一个字长度的第一个字节值大于等于0xF8则说明这是一个保留的控制字节。当收到这种未知的控制字节时，API客户端将不执行任何操作，因为它无法解析收到的数据。

l  目前控制字节还没有被使用。

 

API段的简短描述

l  空的段将被忽略。

l  当收到一个0长度的字后表示段结束，这时段开始被执行。

l  在客户端成功登录之前它发送段的长度和数量是受限制的。

l  命令

n    第一个字是命令名，如下所示：

/login

/ip/address/getall

/user/active/listen

/interface/vlan/remove

/system/reboot

 

n    API命令与控制台上使用的命令类似，将控制台命令中的空格用“/”取代后即为API命令名。有一些命令是API特有的，例如getall和login。

n    命令名以“/”开头。

n    命令参数跟在命令名之后，例如：

=address=10.0.0.1

=name=iu=c3Eeg

=disable-running-check=yes

 

n   命令参数以“=”开头，其后紧跟参数名称，然后再跟另一个等号“=”最后是参数的值。

n   API专有的参数名例如“.id”以一个圆点“.”开头。

n   参数的值可以为空，并且允许保留参数名后的等号“=”。

n   命令段可以包含由API协议处理的特别参数，这些参数以圆点“.”开头，然后紧跟参数名，再跟等号“=”，最后是参数的值。

n   目前唯一的命令段特别参数是“tag”。

n   命令参数与API参数的顺序是不重要的，并且不能依赖它们的顺序。

n   可以使用附加的查询参数来限制命令的作用范围，关于它们的详细说明请见其后的章节。例：

/interface/print

?type=ether

?type=vlan

?#|!

 

n   查询限定参数以问号“?”开头。

n   查询限定参数的顺序是重要的。

n   目前只有“print”命令可以使用查询限定参数。

n   返回结果中第一个字以叹号“!”开头。

n   每个命令至少产生一个回复（如果连接没有断开的话）。

n   每个命令的最后一个回复的第一个字是“!done”。

n   当发生错误或异常时回复以“!trap”开头。

n   正常的数据回复以“!re”开头。

n   如果API连接被关闭，RouterOS将发送“!fatal”回复，然后断开连接。

登录系统

/login

!done

=ret=ebddd18303a54111e2dea05a92ab46b4

/login

=name=admin

=response=001ea726ed53ae38520c8334f82d44c9f2

!done

l  首先，客户端发送“/login”命令。

l  注意每个命令和回应都以空字结束。

l  回复包含“=ret=challenge”参数。

l  客户端发送第二个“/login”命令以及“=name=username”和“=response=response”。

l  如果发生错误，回应中包含“=ret=error”信息。

l  如果登录成功，客户即可开始发送其它命令。

Tags

l  可以同时运行多个命令并且无需等待之前的命令完成。如果API客户端需要区分不同的命令产生的结果则可以在段中使用“tag”API参数。

l  如果在一个命令中使用了非空的“tag”参数，那么由这个命令产生的所有回复段中的“tag”参数的值将与该命令中设置的“tag”参数值一致。

l  如果在一个命令中使用了空值的“tag”参数，那么该命令返回的段中将不包含“tag”参数。

命令描述

l  /cancel

n   可选的参数：=tag=tag of command to cancel，如果没有该参数，则取消所有正在运行的命令。

n   cancel命令不能取消它本身。

n   所有被取消的命令都会中断执行并像通常情况一样产生“!trap”或“!done”回应。

n   请注意/cancel也是一个单独的命令，它也有自己独立的.tag参数，与=tag参数无关。

l  listen

n   listen命令在控制台的print命令有效的场合均有效，但不保证它在所有的情况下都有预期的效果。

n   当配置条目发生变化时产生!re回复段。

n   当配置条目被删除或者因为其它原因而消失时，!re回复段将包含一个=.dead=yes值。

n   这个命令不会自行结束，如有需要使用/cancel命令来手动结束。

l  getall

n   getall命令在控制台的print命令有效的场合均有效。从v3.21版开始，getall只是print命令的别名。

n   返回内容包含=.id=Item internal number属性。

l  print

n   API的print命令在如下几点上与控制台版本不同：

u      不支持where参数，可以使用查询限定字来过滤被查询的条目。

u      使用.proplist参数指定要显示的属性名称，属性名称以逗号分隔作为其参数。

Ø 返回的结果可能包含附加的属性。

Ø 返回的属性顺序是未定义的。

Ø 如果属性列表中包含重复的属性名，那么处理这些属性名的结果是未定义的。

Ø如果某个属性出现在.proplist属性列表中，但被查询的条目没有这个属性，则这个属性不会出现在返回结果中。

Ø如果没有指定.proplist参数，那么所有的属性都会由print命令返回，这种情况会使处理速度变慢（如文件内容和性能计数器），因此提倡使用.proplist参数。Omission of .proplist may have high performance penalty if =detail=argument is set.（没看懂，囧~）

查询

print命令允许使用查询限定字来限定返回的条目，这一特性从v3.21版本开始出现。

l  查询限定字由问号“?”开头。

l  查询限定字的顺序是重要的，从第一个查询字开始处理。

l  查询限定字匹配每一个条目，如果匹配成功，则该条目被处理，否则忽略该条目。

l  查询匹配系统使用一个布尔栈来工作，在初始时这个栈中包含无穷多个true，在处理完成后，若栈中包含至少一个false，则该查询匹配失败。

?name        如果条目中包含以name命名的属性，压true入栈，否则压false入栈。

?-name       如果条目中不包含以name命名的属性，压true入栈，否则压false入栈。

?name=x

?=name=x   如果条目中的name属性值等于x，压true入栈，否则压false入栈。

?<name=x   如果条目中的name属性值小于x，压true入栈，否则压false入栈。

?>name=x   如果条目中的name属性值大于x，压true入栈，否则压false入栈。

?#operations

n   操作字符串从左到右处理。

n   任何其它的字符之后或者字的未尾的小数点后的数字序列称为栈的索引，栈顶的索引值为0。

n   跟在字符后面的索引值意味着将其值的拷贝压入索引指向的栈位置。

n   跟在字末尾的索引值意味着替换索引指向的栈位置。

n   !字符用反值替换栈顶的值。

n   &字符弹出栈顶2个元素，并将其求与运算后的结果压入栈。

n   |字符弹出栈顶2个元素，并将其求或运算后的结果压入栈。

n   索引后的圆点“.”是无用的。

n   其它字符后的圆点“.”将栈顶的值的拷贝压入栈。

举例：

l  输出所有ethernet和VLAN接口的信息：

/interface/print

?type=ether

?type=vlan

?#|

l  输出所有注释非空的路由：

/ip/route/print

?>comment=

 

OID

print命令可以将SNMP协议的OID值作为属性返回，这个特性在v3.23版本开始出现。

在控制台中，可以使用print oid命令来显示OID值。在API中，这些属性名以“.oid”结束，并且可以把它们添加到.proplist的参数中，例：

/system/resource/print

=.proplist=uptime,cpu-load,uptime.oid,cpu-load.oid

 !re

=uptime=01:22:53

=cpu-load=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

 !done

 

命令举例

/system/package/getall

/system/package/getall

 !re

=.id=*5802

=disabled=no

=name=routeros-x86

=version=3.0beta2

=build-time=oct/18/2006 16:24:41

=scheduled=

 !re

=.id=*5805

=disabled=no

=name=system

=version=3.0beta2

=build-time=oct/18/2006 17:20:46

=scheduled=

... more !re sentences ...

 !re

=.id=*5902

=disabled=no

=name=advanced-tools

=version=3.0beta2

=build-time=oct/18/2006 17:20:49

=scheduled=

 !done

 

/user/active/listen

/user/active/listen

 !re

=.id=*68

=radius=no

=when=oct/24/2006 08:40:42

=name=admin

=address=0.0.0.0

=via=console

 !re

=.id=*68

=.dead=yes

... more !re sentences ...

 

/cancel，多条命令同时执行

/login

 !done

=ret=856780b7411eefd3abadee2058c149a3

/login

=name=admin

=response=005062f7a5ef124d34675bf3e81f56c556

 !done

-- first startlistening for interface changes (tag is 2)

/interface/listen

.tag=2

-- disableinterface (tag is 3)

/interface/set

=disabled=yes

=.id=ether1

.tag=3

-- this is donefor disable command (tag 3)

 !done

.tag=3

-- enable interface (tag is 4)

/interface/set

=disabled=no

=.id=ether1

.tag=4

-- this updateis generated by change made by first set command (tag 3)

 !re

=.id=*1

=disabled=yes

=dynamic=no

=running=no

=name=ether1

=mtu=1500

=type=ether

.tag=2

-- this is donefor enable command (tag 4)

 !done

.tag=4

-- get interfacelist (tag is 5)

/interface/getall

.tag=5

-- this updateis generated by change made by second set command (tag 4)

 !re

=.id=*1

=disabled=no

=dynamic=no

=running=yes

=name=ether1

=mtu=1500

=type=ether

.tag=2

-- these arereplies to getall command (tag 5)

 !re

=.id=*1

=disabled=no

=dynamic=no

=running=yes

=name=ether1

=mtu=1500

=type=ether

.tag=5

 !re

=.id=*2

=disabled=no

=dynamic=no

=running=yes

=name=ether2

=mtu=1500

=type=ether

.tag=5

-- hereinterface getall ends (tag 5)

 !done

.tag=5

-- stoplistening - request to cancel command with tag 2, cancel itself uses tag 7

/cancel

=tag=2

.tag=7

-- listencommand is interrupted (tag 2)

 !trap

=category=2

=message=interrupted

.tag=2

-- cancelcommand is finished (tag 7)

 !done

.tag=7

-- listencommand is finished (tag 2)

 !done

.tag=2