ROS API 中文说明

ROSAPI中文说明前言：ROS是一个比较流行的软路由系统，它的强大在于它的高度定制性，它提供了应用程序编程使用的API接口，是它应用更加灵活，我们可以自己开发软件或WEB程序来操控ROS，比较实用的例子就是当用ROS管理小区网络时，我们用自己写的软件来管理上网账号，安全又方便，总之好处多多，本文基于官方API文档：翻译而成，结合了作者的理解，水平有限，难免有错漏的地方，望大家批评指正，谢谢！正文：目录1简介2通讯协议2.1API词2.1.1命令词2.1.2属性词2.1.3API属性词2.1.4查询语句2.1.5回复语句2.2API特定命令说明3初始登录4标签(.Tags)5API命令说明5.1查询词说明5.2OID6API命令例子6.1/system/package/getall6.2/user/active/listen6.3/cancel,simultaneouscommands7客户端程序例子8参考8.1APIexamplesintheWiki8.2APIexamplesontheMikroTikForum8.3APIexmapleselsewhere简介：应用程序编程接口（API），允许用户创建定制的软件解决方案与RouterOS的沟通，收集信息，调整配置和管理路由器。API紧随命令行界面（CLI）的语法。它可以用来创建转换或自定义的配置工具，以帮助管理使用RouterOS的路由器。使用API需要RouterOS版本3.x或更高的版本。默认情况下，API使用端口8728，默认服务是禁用的。通讯服务的名称是API，请在IP-SERVER里开启，服务管理的详细信息，请参阅相应的手册部分。通讯协议：应用程序与路由器的通信是通过发送和接收路由器的一个或多个编码的句子来完成的。一个句子是以零字符结尾的单词序列。词是句子以某种方式编码-（编码长度是数据的一部分），路由器发送和接收回复并发送这些句子。每个句子发送到路由器使用API没有特定的顺序，每个命令字是以零字符标记结束的。当路由器接收到完整的句子（命令字，或多个属性的话，零字符结束），它就开始执行命令，并将结果返回给应用程序。API语句：词是句子的一部分。每个词长都用某种方式编码-词长编码跟随词的内容就是一个句子。词的长度应为将要发送的字节计数（不包括词长编码）。词长编码如下：Valueoflength#ofbytesEncoding0=Len=0x7F1Len,lowestbyte词长度0x80=Len=0x3FFF2Len|0x8000,twolowerbytes0x4000=Len=0x1FFFFF3Len|0xC00000,threelowerbytes0x200000=Len=0xFFFFFFF4Len|0xE0000000Len=0x1000000050xF0andLenasfourbytes对应的10进制：长度字节数词长编码0=长度=1271长度低位128=长度=163832位或（长度，32768）取低2位16384=长度=20971513位或（长度，12582912）取低3位2097152=长度=2684354554位或（长度，3758096384）长度=2684354565{240}+到字节集(长度)每个词的编码长度，然后紧接着许多字节的词内容（词长编码+词内容）；字组合成句子，以零字符结束；最高长度可以达到0x7FFFFFFFFF,最高占用4字节；词长编码字节（Len）总是在最前面（网络顺序）；如果单词的第一个字节是=0xF8，那么它是一个保留的控制字节。未知的控制字节API客户端接收后无法继续，因为它不知道如何解释以下字节；目前，控制字节不使用；句子一般情况是这样的：词长编码词的内容，主要有5种类型：命令语句，属性语句，API属性语句，查询语句，回复语句；命令语句（Commandword）在句子的第一个字是由名字（属性）和零长度的词终止字的命令。命令字的名称应以'/'开始。命令中的名字，与命令行界面输入的一样，要注意的API中的命令不能有空格，需要用以'/'替换，比如查看网卡信息/intpri在API里就必须这样/int/pri，不然无法识别；注意：发送的命令必须严格按照这样的顺序：编码长度内容前缀/命令行的转换命令(空格用/替换)API特定的命令：getalllogincancel命令连接例子：/login/ip/address/getall/user/active/listen/interface/vlan/remove/system/reboot2.1.2属性语句（Attributeword）每个命令都有其自己的属性列表，命令内容决定属性。属性结构由5部分组成，顺序如下：编码长度内容前缀(!-=)属性名称分离符号(!-=)属性值（可以被忽略，说明这个属性没有值）注意：为了编码方便，一个命令里的多个属性赋值可以在一句里完成属性值可以为空没有编码的长度前缀的例子：=address=10.0.0.1=name=iu=c3Eeg=disable-running-check=yes注意：属性词和API参数的顺序并不重要，不应依赖；2.1.3API属性语句API属性语句的结构必须严格按照下面的顺序：编码长度内容与名称前缀=.属性名称名称后缀符=属性值system/resource/print=.proplist=uptime,cpu-load,uptime.oid,cpu-load.oid目前只有这样的API属性的标签。注意：如果句子包含了属性语句标签，返回的每一个句子和从路由器标记句子将标记相同的标签，关于标签后面的章节有单独的介绍；2.1.4查询语句查询语句支持对参数进行一定范围内的模糊查询，在下面的章节中有单独介绍；例如句子使用查询词的属性：/interface/print?type=ether?type=vlan?#|!查询语句以符号?开始，目前查询语句只支持print命令；警告：查询语句始终是在最前面；2.1.5回复语句回复语句只能由路由器发送，它仅发送完整的句子，由客户端发送响应。回复语句的第一个字是以!开始的；发送的每一句话产生至少一个答复（如果连接没有得到终止）；每一句的最后答复是答复的第一个字!done；错误和异常情况以!trap开始；开始数据回复以!re开始；如果连接被关闭，RouterOS发送!fatal作为致命的原因进行答复并且关闭连接；2.2API语句API语句是使用API通信的主要对象空的句子被忽略；句子是以字符0作为结束标志的；客户端登陆后发送句子有数量和大小的限制；属性语句没有顺序区别，比如.proplist属性语句的顺序和计数就是多变的；句子结构如下：第一句话应该包含命令字；应包含结束标志字符{0}；可以包含0个或多个属性词，没有特定的顺序，不管什么属性词必须在句子里发送，属性词的顺序并不重要；可以包含没有一个或几个查询词，查询词在句子的顺序是很重要的；注：零长度的词(字节'0')终止了一句,如果没有提供,路由器将无法测试句字的有效性，只能把收到的句子当做句子的一部分；初始登录/login!done=ret=ebddd18303a54111e2dea05a92ab46b4/login=name=admin=response=001ea726ed53ae38520c8334f82d44c9f2!done注意：每个命令和响应结束都有一句空的语句；首先，客户端发送/login命令路由器的回复包含=ret=需要的参数客户端发送第二个/login命令,接着是用户名(=name=username)和密码(=response=response)验证命令；在错误的情况下，答复包含=RET=错误消息。在成功登录客户端的情况下，就可以开始发出命令。标签(.tag)它是可以同时运行多个命令，而不必等待前一个完成。如果API的客户端是这样做的，需要区分命令的反应，它可以使用在命令句子'.tag'API的参数。如果你有“.tag”命令句与非空值的参数，然后'.tag'参数完全相同的值将包含在该命令生成的所有答复。如果不包括'.tag'参数，或它的值是空的，那么这个命令所有的反应将不会有“.tag”参数。命令描述/cancle（取消）可选参数：=tag=tag，取消所有正在运行的命令；不能取消本身所有取消的命令都是中断操作，并且在通常情况下会产生'!trap'和'!done'的回复;请注意，/cancel是单独的命令，可以有它自己独特的'.tag'参数，它是不相关'=.tag'这个命令的参数；listen(监听)listen是在控制台print命令可用的情况下使用，它没有预期中的效果（即可能无法正常工作）；!re数据回复句子会产生特定的项目列表中的一些变化；当项目被删除或以其他任何方式清除，数据回复句子('!re'）的属性值会包含'=.dead=yes';此命令不会终止。终止使用取消命令/canclegetall（获取全部信息）getall命令是在控制台print命令可用的情况下使用，自3.21版本以后的getall命令是print命令的别名。回复包含=.id=项目内部编号属性print（显示）API的print命令和控制台的print命令的不同主要有以下几个方面：虽然参数不支持，但可以使用查询词（见下文）筛选项目。传回的项目可能有额外的属性。返回的属性的顺序是没有定义的。如果列表中包含重复的条目，这些条目的处理没有被定义。如果属性格式目前是在.proplist里，但项目里没有这个属性，该项目没有这个属性的值，（?名称将评估该项目为假）如果没有设置.proplist参数，将打印所有的属性，甚至那些比较耗时的项目（如文件内容性能记数),因此推荐使用.proplist参数，设置=detail=argument，虽然可能会有遗漏，但是换回的却是高性能。查询print命令接受限制返回的句子设置的查询词。此功能是自RouterOS的3.21开始的。查询词以符号?'开始。查询词的顺序是在最前面的，从第一个字开始模糊查询。对查询列表中每个项目进行评估，如果查询成功，项目被处理，如果查询失败，项目将被忽略。查询评估在堆栈使用布尔逻辑值。最初，堆栈包含无限量的“真”值。在评估结束时，如果堆栈包含至少一个“假”值，查询失败。查询词按照下列规定操作：查询词描叙?name如果项目属性名称的值不为空，堆栈压入真，否则压入假?-name如果项目属性名称的值为空，堆栈压入真，否则压入假?name=x或?=name=x如果项目属性名称的值=x,堆栈压入真，否则压入假?name=x如果项目属性名称的值x,堆栈压入真，否则压入假?name=x如果项目属性名称的值x,堆栈压入真，否则压入假?#操作符适用于操作在堆栈的值。操作字符串是从左向右计算的。任何其他的字符或单词的末尾的十进制数字序列被解释为一个堆栈指数。最高值指数0。后跟一个字符的索引，压入该指数值的副本指数是由单词的末尾替换所有值与该指数的值。！操作符是反义字符，替换堆顶值为反义值；&操作符是逻辑与操作符，从堆栈弹出2个值，进行逻辑与操作并将结果压于入堆栈|操作符是逻辑或操作符,从堆栈弹出2个值，进行逻辑“或”操作并将结果压于入堆栈.索引后什么都不做.另一个字符后压入副本值到堆顶。例子:取得所有的以太网和VLAN接口：/interface/print?type=ether?type=vlan?#|获取所有有备注的路由：/ip/route/print?comment=OIDprint命令可以返回属性是在SNMPOID值。此功能出现在3.23版本以后。在控制台，OID值可以运行'printoid'命令看出。在API这些属性有.OID结束的名称，并可以加入他们的名字的值