ROS API 中文说明

ROS API 中文说明

前言：

ROS 是一个比较流行的软路由系统，它的强大在于它的高度定制性，它提供了应用程序编程使用的API接口，是它应用更加灵活，我们可以自己开发软件或WEB程序来操控ROS，比较实用的例子就是当用ROS管理小区网络时，我们用自己写的软件来管理上网账号，安全又方便，总之好处多多，

本文基于官方API文档：/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属性语句的结构必须严格按照下面的顺序：

编码长度

内容与名称前缀"=."

属性名称

名称后缀符"="

属性值