API接口介绍及使用说明
- API接口
- 2023-05-01
- 2832热度
- 0评论
使用说明
API密钥获取
API密钥获取请前往【角色管理】【管理员及API】页面,显示管理员对应的API密钥列。
管理员所在权限分组,需具备对应接口的请求授权才可使用,请注意提前分配好需要的权限。
接口使用
所有接口使用form-data接收您提交的数据,使用json返回请求结果。
其中api_key为接口密钥,必须提交。接口有提交频率限制,请勿高频调用。
复数形式参数支持多数据传入,使用英文逗号间隔,如lists,可以使用 "114.114.114.114,223.5.5.5,119.29.29.29"同时传入多个ip规则。
认证方式
所有接口均需要提供api_key参数进行认证。api_key需要在RosZ后台"管理员账号"页面中创建并配置相应权限。
权限配置说明:
端口转发相关接口需要:查看及管理主账号端口转发配置(API)、添加端口转发(API)、修改端口转发(API)、删除端口转发(API)、绑定端口转发(API)
组网架构查询接口需要:查看及管理主账号智能组网配置(API)
通道信息查询接口需要:查看智能组网通道信息(API)
路由信息查询接口需要:查看智能组网全部路由配置(API)
错误码说明
code=0:请求成功
code=1:请求失败,msg字段包含详细错误信息
常见错误:
"请求受限,请联系管理员!":IP访问频率超限
"API密钥错误 或 未授权,请联系管理员!":api_key无效或权限不足
"XXX不能为空":缺少必需参数
"XXX格式错误":参数格式不符合要求
"XXX不存在或无权限操作":资源不存在或无权限
使用注意事项
1. 所有接口均有访问频率限制,请合理控制调用频率
2. api_key需要妥善保管,避免泄露
3. 端口转发数量受VIP等级限制,超限时需要升级或清理
4. 参数支持模糊匹配的接口,使用LIKE方式查询
5. 参数支持逗号分隔的接口,可同时查询多个值
6. 时间格式统一为:2006-01-02 15:04:05
7. 所有地址支持CIDR格式(如192.168.1.0/24)
8. 建议在正式使用前先在测试环境验证接口功能
调用示例(curl)
示例1:查询端口转发
curl -X POST https://rosz.cn/api/vpn/port_info \
-F "api_key=your_api_key_here" \
-F "protocol=tcp"
示例2:添加端口转发
curl -X POST https://rosz.cn/api/vpn/port_add \
-F "api_key=your_api_key_here" \
-F "dst_port=8080" \
-F "to_address=192.168.1.100" \
-F "to_port=80" \
-F "protocol=tcp" \
-F "comment=测试端口转发"
示例3:查询组网架构
curl -X POST https://rosz.cn/api/vpn/group_info \
-F "api_key=your_api_key_here" \
-F "group_name=测试组网"
示例3-2:查询组网架构(包含端口转发域名)
curl -X POST https://rosz.cn/api/vpn/group_info \
-F "api_key=your_api_key_here" \
-F "group_name=测试组网" \
-F "port_forwarding_domain=example.com"
示例4:绑定端口转发到组网架构
curl -X POST https://rosz.cn/api/vpn/port_bind \
-F "api_key=your_api_key_here" \
-F "vpn_group_id=123" \
-F "port_ids=1,2,3"
示例5:查询通道信息
curl -X POST https://rosz.cn/api/vpn/tunnel_info \
-F "api_key=your_api_key_here" \
-F "search_type=正常通道"
示例6:查询路由信息
curl -X POST https://rosz.cn/api/vpn/route_info \
-F "api_key=your_api_key_here" \
-F "search_type=普通路由"
网络安全
安全组接口
安全组查询接口
用途:获取安全组信息
路径:https://rosz.cn/api/sec/group_info
请求:POST
参数:
api_key:请求密钥
groups:查询的安全组名称,支持同时多个数据传入;为空时返回所有信息
names:查询的安全组别名,支持同时多个数据传入;为空时返回所有信息
comment:查询的安全组备注
返回示例:
{
"code": 0,
"msg": "ok",
"count": 2,
"data": [
{
"group": "test2",
"name": "别名1",
"comment": "备注1",
"created_at": "2023-05-01 09:16:14"
},
{
"group": "test",
"name": "别名2",
"comment": "备注2",
"device_ids": "4252",
"created_at": "2023-04-30 00:18:07"
}
]
}
安全规则查询接口
用途:获取安全组规则信息
路径:https://rosz.cn/api/sec/list_info
请求:POST
参数:
api_key:请求密钥
groups:查询的安全组名称,支持同时多个数据传入;为空时返回所有信息
lists:查询的安全组规则信息,支持同时多个数据传入;为空时返回所有信息
comment:查询的安全规则备注
expire:安全规则到期时间
返回示例:
{
"code": 0,
"msg": "ok",
"count": 1,
"data": [
{
"group": "test",
"lists": "baidu.com",
"range": 16,
"created_at": "2023-04-30 00:42:13",
"expire": "2099-12-31 23:59:59"
}
]
}
新增安全规则接口
用途:新增安全规则
路径:https://rosz.cn/api/sec/list_add
请求:POST
参数:
api_key:请求密钥
groups:关联的安全组名称,支持同时多个数据传入;不可为空
lists:安全规则信息,IP或者域名,也可以为CIDR格式IP段,支持同时多个数据传入;不可为空
range:包容度,仅对域名规则有效,范围1-65536,不可为空,如使用256代表间隔256个ip以内的作为连续IP规则使用,建议16;不可为空
comment:安全规则备注;可为空
expire:安全规则到期时间,格式为"2024-09-05 14:01:27";为空则设置为永久有效
返回示例:
{
"code": 0,
"data": {},
"msg": "成功添加6条IP规则!"
}
安全规则删除接口
用途:删除安全组规则
路径:https://rosz.cn/api/sec/list_del
请求:POST
参数:
api_key:请求密钥
groups:删除的安全组名称,支持同时多个数据传入;不可为空
lists:删除的安全组规则信息,支持同时多个数据传入;不可为空
返回示例:
{
"code": 0,
"data": {},
"msg": "安全组规则删除完成!"
}
智能组网
组网架构接口
组网架构信息查询接口
用途:获取组网架构详细信息
路径:https://rosz.cn/api/vpn/group_info
请求:POST
参数:
api_key:请求密钥
group_name:组网名称(模糊匹配)
comment:备注(模糊匹配)
created_at:创建时间起始值(格式:2024-01-01 00:00:00)
port_forwarding_domain:端口转发域名(传入后在返回的bound_ports中显示该字段)
返回示例:
{
"code": 0,
"msg": "ok",
"count": 1,
"data": [
{
"id": 1,
"group_name": "测试组网",
"vpn_mode": "wireguard",
"vpn_zone": 1,
"vpn_zone_str": "国内",
"comment": "测试用组网架构",
"isolation_mode": 1,
"isolation_mode_str": "隔离",
"distance": 240,
"center_port_start": 30001,
"center_port_end": 50000,
"interface_ip_cidr": "10.0.0.0/24",
"created_at": "2024-01-01 10:00:00",
"operator_info": "主账号",
"center_devices": [
{
"device_id": 100,
"identity": "Center-Router",
"custom_name": "中心路由器",
"comment": "主机房设备",
"ip_info": "中国 上海",
"connected_ips": ["1.2.3.4", "5.6.7.8"],
"connected_pools": ["192.168.1.0/24", "192.168.2.0/24"]
}
],
"edge_devices": [
{
"device_id": 200,
"identity": "Edge-Router",
"custom_name": "边缘路由器",
"comment": "分支机构设备",
"ip_info": "中国 北京",
"connected_pools": ["172.16.1.0/24"]
}
],
"bound_ports": [
{
"port_id": 1,
"protocol": "tcp",
"dst_port": "8080",
"to_address": "192.168.1.100",
"to_port": "80",
"src_address_list": "test_list",
"comment": "Web服务转发",
"bound_devices": [100, 200],
"port_forwarding_domain": "example.com"
}
]
}
]
}
字段说明:
vpn_zone:1=国内,2=海外,3=全球
isolation_mode:1=隔离,2=互通,3=全通
center_devices:中心节点设备详细信息,包含对接IP和互联网段
edge_devices:边缘节点设备详细信息,包含互联网段
bound_ports:绑定的端口转发配置,包含绑定的设备列表
port_forwarding_domain:端口转发域名(仅在传入该参数时显示)
通道与路由接口
通道信息查询接口
用途:获取组网通道连接状态和网络质量信息
路径:https://rosz.cn/api/vpn/tunnel_info
请求:POST
参数:
api_key:请求密钥
vpn_group_id:组网ID,支持逗号分隔多个ID
device_keyword:设备关键字(匹配设备型号、序列号、MAC、IP、Identity、别名、备注等)
address_keyword:地址关键字(匹配通道地址、接口地址、互联网段等)
search_type:搜索类型(正常通道、断开通道、状态未知通道、边缘隔离模式、边缘互通模式、全通模式)
返回示例:
{
"code": 0,
"msg": "ok",
"count": 1,
"data": [
{
"id": 1,
"vpn_group_id": 1,
"vpn_group_name": "测试组网",
"vpn_group_comment": "测试用组网",
"center_device_id": 100,
"center_device_info": "Center-Router | 中心路由器",
"center_address": "1.2.3.4",
"center_address_info": "中国 上海 电信 (1.2.3.4)",
"center_interface_address": "10.0.0.1",
"center_port": 30001,
"center_devices_pool": "192.168.1.0/24",
"edge_device_id": 200,
"edge_device_info": "Edge-Router | 边缘路由器",
"edge_address": "5.6.7.8",
"edge_interface_address": "10.0.0.2",
"edge_devices_pool": "172.16.1.0/24",
"isolation_mode": 1,
"isolation_mode_str": "隔离",
"distance": 240,
"auto_repair_down_seconds": "12次 | 1分钟",
"down_seconds_now": "0次 | 0秒",
"status": "正常",
"ping_avg": "10.5 ms",
"ping_min": "8.2 ms",
"ping_max": "15.3 ms",
"ping_lost_percentage": "0.0%",
"rx_bit_rate": "10.5 Mbps",
"tx_bit_rate": "8.3 Mbps",
"all_bit_rate": "18800000 bps",
"peer_rx_bytes": "1.2 GB",
"peer_tx_bytes": "800.5 MB",
"peer_all_bytes": "2.0 GB",
"last_hand_shake": "10秒前",
"created_at": "2024-01-01 10:00:00",
"operator_info": "主账号"
}
]
}
字段说明:
status:通道状态(正常/断开/未知)
auto_repair_down_seconds:自动修复配置(未启用或配置的中断时长)
down_seconds_now:当前中断时长
网络质量指标:延迟、丢包率、带宽、流量等
路由信息查询接口
用途:获取组网路由配置信息
路径:https://rosz.cn/api/vpn/route_info
请求:POST
参数:
api_key:请求密钥
vpn_group_id:组网ID,支持逗号分隔多个ID
src_device_keyword:源设备关键字
dst_device_keyword:目标设备关键字
dst_address:目的地址(模糊匹配)
gateway:网关地址(模糊匹配)
search_type:搜索类型(普通路由、互联接口、递归路由、递归子网、递归网关、中心设备、边缘设备)
返回示例:
{
"code": 0,
"msg": "ok",
"count": 1,
"data": [
{
"id": 1,
"vpn_group_id": 1,
"vpn_group_name": "测试组网",
"vpn_group_comment": "测试用组网",
"route_type": 0,
"route_type_str": "普通路由",
"src_device_id": 100,
"src_device_info": "Center-Router (中心路由器)",
"src_device_ip_info": "中国 上海 (1.2.3.4)",
"src_device_type": 1,
"src_device_type_str": "中心设备",
"src_interface_address": "10.0.0.1",
"distance": 240,
"dst_device_id": 200,
"dst_device_info": "Edge-Router (边缘路由器)",
"dst_device_ip_info": "中国 北京 (5.6.7.8)",
"dst_address": "172.16.1.0/24",
"gateway_address": "10.0.0.2",
"status": "正常",
"ping_avg": "10.5 ms",
"ping_lost_percentage": "0.0%",
"rx_bit_rate": "10.5 Mbps",
"tx_bit_rate": "8.3 Mbps",
"peer_rx_bytes": "1.2 GB",
"peer_tx_bytes": "800.5 MB",
"peer_all_bytes": "2.0 GB",
"created_at": "2024-01-01 10:00:00",
"operator_info": "主账号"
}
]
}
字段说明:
route_type:路由类型(0=普通路由,1=递归网关,2=递归子网,3=互联接口)
src_device_type:源设备类型(0=边缘设备,1=中心设备)
包含通道状态和网络质量信息
端口转发接口
端口转发查询接口
用途:获取端口转发配置信息
路径:https://rosz.cn/api/vpn/port_info
请求:POST
参数:
api_key:请求密钥
comment:备注(模糊匹配)
src_address_list:源地址列表名称(模糊匹配)
dst_port:目的端口(模糊匹配)
to_address:转发地址(模糊匹配)
to_port:转发端口(模糊匹配)
protocol:协议类型(精确匹配,tcp或udp)
返回示例:
{
"code": 0,
"msg": "ok",
"count": 2,
"data": [
{
"id": 1,
"src_address_list": "test_list",
"dst_port": "8080,8081",
"to_address": "192.168.1.100",
"to_port": "80",
"protocol": "tcp",
"comment": "测试端口转发",
"created_at": "2024-01-01 10:00:00",
"operator_info": "主账号",
"bind_device_num": 3
}
]
}
端口转发添加接口
用途:添加端口转发配置
路径:https://rosz.cn/api/vpn/port_add
请求:POST
必需参数:
api_key:请求密钥
dst_port:目的端口,支持单个(8080)、逗号分隔(8080,8081)、范围(8080-8090)、混合格式
to_address:转发地址,支持IP地址或CIDR格式(如192.168.1.100或192.168.1.0/24)
protocol:协议类型,tcp或udp
可选参数:
src_address_list:源地址列表名称(RouterOS地址列表名)
to_port:转发端口,支持单个或范围格式,允许为空(为空时表示与dst_port一致)
comment:备注
返回示例(成功):
{
"code": 0,
"msg": "ok",
"data": {
"id": 10,
"message": "添加端口转发成功"
}
}
返回示例(失败):
{
"code": 1,
"msg": "目的端口格式错误:端口必须在1-65535之间"
}
注意事项:
1. 端口转发数量受VIP等级限制
2. dst_port支持多种格式,to_port仅支持单个或范围
3. to_port为空时默认与dst_port一致
端口转发修改接口
用途:修改端口转发配置
路径:https://rosz.cn/api/vpn/port_edit
请求:POST
必需参数:
api_key:请求密钥
id:端口转发ID
可修改参数:
src_address_list:源地址列表名称
dst_port:目的端口
to_address:转发地址
to_port:转发端口
protocol:协议类型
comment:备注
返回示例:
{
"code": 0,
"msg": "修改端口转发成功"
}
注意事项:
1. 只需提供需要修改的字段
2. 未提供的字段保持原值不变
3. 修改的内容需通过相应的格式验证
端口转发删除接口
用途:删除端口转发配置
路径:https://rosz.cn/api/vpn/port_del
请求:POST
必需参数:
api_key:请求密钥
ids:端口转发ID,支持逗号分隔多个ID进行批量删除(如:1,2,3)
返回示例:
{
"code": 0,
"msg": "ok",
"data": {
"message": "删除端口转发成功",
"deleted_count": 3,
"deleted_ids": [1, 2, 3]
}
}
注意事项:
1. 支持批量删除
2. 删除端口转发时会同时删除其绑定关系
3. 只能删除属于当前用户的端口转发
端口转发绑定接口
用途:将端口转发配置绑定到组网架构的中心设备
路径:https://rosz.cn/api/vpn/port_bind
请求:POST
必需参数:
api_key:请求密钥
vpn_group_id:组网架构ID
可选参数:
port_ids:端口ID列表,支持逗号分隔多个ID(如:1,2,3);不传或传空则清空该组网的端口绑定
返回示例(成功):
{
"code": 0,
"msg": "ok",
"data": {
"vpn_group_id": 123,
"bound_port_count": 5,
"affected_device_count": 3,
"message": "绑定端口转发成功"
}
}
返回示例(失败):
{
"code": 1,
"msg": "组网架构不存在或无权限操作"
}
注意事项:
1. 绑定操作会自动应用到组网架构的所有中心设备
2. 采用覆盖式绑定,不会保留旧的绑定关系
3. 传入空的port_ids或不传该参数,可清空该组网的所有端口绑定
4. 只能绑定属于当前用户的端口转发配置
5. 绑定后会自动更新设备配置并标记同步
6. 可通过组网架构查询接口(/api/vpn/group_info)查看绑定结果
如有问题或需要技术支持，请联系站长微信：302268