ROS API 中文说明
                             
前言： 
    ROS 是 一个比较流行的软路由系统，它的强大在于它的高度定制性，它提供了应用程序编程使用的API接口，是它应用更加灵活，我们可以自己开发软件或WEB程序来操控ROS，比较实用的例子就是当用ROS管理小区网络时，我们用自己写的软件来管理上网账号，安全又方便，总之好处多多，
 
  本文基于官方API文档：wiki.mikrotik/wiki/API 翻译而成，结合了作者的理解，水平有限，难免有错漏的地方，望大家批评指正，谢谢！
 
正文：
1 简介
2 通讯协议
2.1 API词
2.1.1 命令词
2.1.2 属性词
2.1.3 API 属性词
2.1.4 查询语句
2.1.5 回复语句
2.2 API 特定命令说明
3 初始登录
4 标签(.Tags )
5 API命令说明
5.1 查询词说明
5.2 OID
6 API 命令例子
6.1 /system/package/getall
6.2 /user/active/listen
6.3 /cancel, simultaneous commands
7 客户端程序例子
8 参考
8.1 API examples in the Wiki
8.2 API examples on the MikroTik Forum
8.3 API exmaples elsewhere
简介：
    应用程序编程接口（API），允许用户创建定制的软件解决方案与RouterOS的
沟通，收集信息，调整配置和管理路由器。 API紧随命令行界面（CLI）的语法。
它可以用来创建转换或自定义的配置工具，以帮助管理使用RouterOS的路由器。
使用API需要RouterOS版本3.x或更高的版本。
默认情况下，API使用端口8728，默认服务是禁用的。通讯服务的名称是API，请
在IP-SERVER里开启，服务管理的详细信息，请参阅相应的手册部分。
通讯协议：
    应用程序与路由器的通信是通过发送和接收路由器的一个或多个编码的句子来
完成的。一个句子是以零字符结尾的单词序列。词是句子以某种方式编码 -（编码
长度是数据的一部分），路由器发送和接收回复并发送这些句子。每个句子发送到路由器
使用API没有特定的顺序，每个命令字是以零字符标记结束的。当路由器
接收到完整的句子（命令字，或多个属性的话，零字符结束），它就开始执行命令，
并将结果返回给应用程序。
API语句：
  词是句子的一部分。每个词长都用某种方式编码 - 词长编码跟随词的内容就是一个句子。词的长度应为将要发送的字节计数（不包括词长编码）。
词长编码如下：
Value of length
# of bytes
Encoding
0 <= Len <= 0x7F
1
Len, lowest byte  词长度
0x80 <= Len <= 0x3FFF
2
Len | 0x8000, two lower bytes 
0x4000 <= Len <= 0x1FFFFF
3
Len | 0xC00000, three lower bytes
0x200000<=Len <= 0xFFFFFFF
4
Len | 0xE0000000
Len >= 0x10000000
5
0xF0 and Len as four bytes
对应的10进制：
长度
字节数
词长编码
0 <= 长度<=127
1
长度低位
128 <= 长度<= 16383
2
位或（长度 ，32768） 取低2位
16384<= 长度<= 2097151
3空值是指零长度的字符串
位或（长度 ，12582912）取低3位
2097152 <= 长度 <= 268435455
4
位或（长度 ，3758096384）
长度 >= 268435456
5
{240} + 到字节集(长度)
每个词的编码长度，然后紧接着许多字节的词内容（词长编码 + 词内容）；
字组合成句子，以零字符结束；
最高长度可以达到0x7FFFFFFFFF,最高占用4字节；
词长编码字节（Len）总是在最前面（网络顺序）；
如果单词的第一个字节是> =0xF8，那么它是一个保留的控制字节。未知的控制字节API客户端接收后无法继续，因为它不知道如何解释以下字节；
目前，控制字节不使用；
句子一般情况是这样的：<词长编码><词的内容>，主要有5种类型：命令语句，属性语句，API属性语句，查询语句，回复语句；
       
命令语句（Command word）
  在句子的第一个字是由名字（属性）和零长度的词终止字的命令。命令字的名称应以'/'开始。命令中的名字，与命令行界面输入的一样，要注意的API中的命令不能有空格，需要用以'/'替换，比如查看网卡信息 "/int pri" 在API里就必须这样"/int/pri"，不然无法识别；
注意：发送的命令必须严格按照这样的顺序：
 
编码长度
内容前缀"/"
命令行的转换命令(空格用"/"替换)
API特定的命令：
  getall
  login
  cancel
命令连接例子：
/login
/
ip/address/getall
/user/active/listen
/interface/vlan/remove
/system/reboot
2.1.2 属性语句（Attribute word）
    每个命令都有其自己的属性列表，命令内容决定属性。
    属性结构由5部分组成，顺序如下：
编码长度
内容前缀( ! - = )
属性名称
    分离符号( ! - = )
    属性值（可以被忽略，说明这个属性没有值）
注意：为了编码方便，一个命令里的多个属性赋值可以在一句里完成
      属性值可以为空
没有编码的长度前缀的例子：
=address=10.0.0.1       
=name=iu=c3Eeg       
=disable-running-check=yes
注意：属性词和API参数的顺序并不重要，不应依赖；
2.1.3 API属性语句
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.2  API 语句
    API语句是使用API通信的主要对象
⏹空的句子被忽略；
⏹句子是以字符"0"作为结束标志的；
⏹客户端登陆后发送句子有数量和大小的限制；
⏹属性语句没有顺序区别，比如.proplist属性语句的顺序和计数就是多变的；
句子结构如下：
⏹第一句话应该包含命令字；
⏹应包含结束标志字符{0}；
⏹可以包含0个或多个属性词，没有特定的顺序，不管什么属性词必须在句子里发送，属性词的顺序并不重要；

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。