帮助文档

API开发文档(2021版)

一:API接口验证方式

Api接口验证地址:http://主控域名/process?c=api&action=接口类型

Api接口响应方式:HTTP POST GET

Api接口IP白名单:支持(建议后台设定有效的API白名单IP)

Api验证公共参数:

参数 类型 说明 是否必须
sign string md5(后台设定的API秘钥)
建议在rstack主控平台设置白名单IP

二:API接口响应模式

响应类型 响应返回值 说明
成功 0 或 0|相关数据 操作成功后的返回值
失败 -1|错误内容 只要判断前缀是否-1|  就代表错误 截取|后面错误内容返回
查询数据 JSON数组 根据查询列表接口返回JSON数组,如查询失败,签名失效等,也会返回-1,如果查询为空返回[]

三:API接口操作

(测试通讯) 接口类型:test

成功返回:0

(测试节点通信自检) 接口类型:node_test

参数 类型 说明 必须
id int 计算节点ID
成功返回:0|版本号

 (创建用户/编辑用户/删除用户/用户列表) 接口类型:users

参数 参数说明 必须
id 用户ID(为空自动新增ID添加用户 ,不为0代表自定义ID创建用户) 编辑用户必须提供有效ID 是/否
type 支持参数 list,create,edit,delete (列表,创建,编辑,删除[删除只需提供ID即可])
username 用户名称(不包含特殊字符)
password 创建用户必须要,长度大于6位, 如果编辑用户为空代表不修改密码 是/否
admin_password 管理员密码,如果是创建普通用户请为空,如果要建管理员请设置密码 长度 大于6位 是/否
count 用户名下的产品数量 一般创建用户的话为空即可
phone 手机号码  
email 邮箱地址
level 用户级别 0=普通用户 100=管理员(后台权限,需设置管理密码才可登陆)
status 0=正常 1=禁用  
remark 备注说明
login_ip 这个用于查询(list)
order asc,desc (用于查询list)

成功返回:create返回:0|用户ID,edit返回0 ,delete返回0,list直接返回JSON数组

(创建主机)  接口类型: create_virtual

参数名 参数说明

必须

zone_id  区域ID,自动按优先级选计算节点开通,如要指定节点开通请为空  是/否
node_id  如指定了区域ID,这里为空,否则请指定计算节点ID开通  是/否
template_id  计算节点允许的模板镜像ID  是
hostname  主机名称 字母和数字组合 最长12,  是
username / user_id  用户名或用户ID 任意选一个  是
cpu  CPU的数量  是
cpu_percent  CPU基线,最大100 ,建议30起步,为空不设置基线  否
cpu_mode  CPU模式 0=显示CPU 1=隐藏CPU  否
memory  内存单位MB,最小256  是
data_disk_size  云主机的数据盘容量,为0时不创建数据盘  否
system_disk_mode  支持参数 writeback,writethrough,none,unsafe,directsync  否
system_disk_iops  固态2400 机械300  否
system_disk_read  系统磁盘的读限制 单位MB 为空使用全局,为0不限IO,其他限制单位MB  否
system_disk_write  系统磁盘的写限制 单位MB 为空使用全局,为0不限IO,其他限制单位MB  否
data_disk_mode  支持参数 writeback,writethrough,none,unsafe,directsync  否
data_disk_iops  固态2400 机械300  否
data_disk_read  数据磁盘的读限制 单位MB 为空使用全局,为0不限IO,其他限制单位MB  否
data_disk_write  数据磁盘的写限制 单位MB 为空使用全局,为0不限IO,其他限制单位MB  否
network_out  网络限制 上行 单位MB 最小1  是
network_in  网络限制 下行 单位MB 最小1  是
bwlimit  流量限制 单位G  为0或为空不限制  否
snapshot  允许创建快照数量 为空不允许创建  否
backup  允许创建完整备份数量 为空不允许创建  否
nat_acl_limit  允许创建端口映射数量 为空不允许  否
nat_web_limit  允许共享IP建站映射数量 为空不允许  否
rvlimit  每天允许重装多少次 为空不允许重装  否
system_password  系统密码,允许一些特殊字符  是
vnc_password  VNC密码 必须是字母和数字组合  是
ip  整数=IP数量(如1代表分配一个IP) 或 IP地址  如:192.168.1.3 (2种模式任意选)  是
additionals_ip  额外IP,多个IP以,分割 如:192.168.1.4,192.168.1.5  为空没有额外IP  否
ip_mode  为1=按公网IP池开通,为2=按内网IP池开通  为0(默认)=按全部IP池的优先级开(针对单服务器混开出独立IP云主机与共享IP云主机,精准匹配开通不同IP类型主机,若不做NAT请为0即可)  否
remote_port 留空不随机默认,1=按系统自动生成随机端口,或指定自定义端口范围10000~65535,需镜像里加入追加脚本
random_ip  为0按IP池顺序开通IP,为1时随机分配IP(此功能必须ip=整数才有效)  否
remark  备注  否

成功返回:0|{"additionals_ip":"192.168.1.8","backup":"0","bwdate":"1618916601","bwlimit":"0","bwusage":"0","cd_rom_id":"0","cpu":"4","cpu_mode":"host-passthrough","cpu_percent":"90","data_disk_io":"writeback,2400,100,100","data_disk_size":"10","firewall_uuid":"2f964c08-3778-1e17-360c-901616238201","hostname":"demo001","id":"134","ip":"192.168.1.8","ip_mac":"52:54:00:3f:77:a4","memory":"1024","nat_acl_limit":"10","nat_web_limit":"10","network_in":"100","network_out":"100","node_id":"7","private_ip":"10.0.7.22","private_ip_mac":"52:54:00:bb:b4:4b","remark":"","rvcount":"0","rvdate":"20210320","rvlimit":"10","security_group_id":"0","snapshot":"10","status":"install","system_disk_io":"writeback,2400,100,100","system_password":"demo001","template_id":"16","time":"1616238201","user_id":"1","uuid":"142406a2-4cef-e87c-0fc1-881616238201","vnc_password":"demo001","vnc_port":"10556","zone_id":"13"}

说明:其中ip=为主IP,additionals_ip为额外IP多个以,分割,  id=主机ID 其他字段请自行翻译

 (编辑主机)  接口类型: edit_virtual

参数名 参数说明 必须
id 云主机ID
update_vm 为空不更新硬件只更新参数, 为1(且硬件参数有变化时)更新云服务器硬件可能会重启
user_id 更改用户ID,一般用于过户等,基本用不到 为空即可
node_id 计算节点ID,一般用于更换节点(如更换但不同IP池需要在设置下IP),为空不修改
cpu CPU核心
cpu_percent CPU基线 建议30起步 最大100  为0时不限制CPU基线
cpu_mode 为空不修改  为0=显示CPU 为1=隐藏CPU
memory 内存单位MB  最小256
data_disk_size 数据盘容量,不能小于当前容量 
system_disk_mode 支持参数 writeback,writethrough,none,unsafe,directsync 为空不修改
system_disk_iops 系统盘 固态2400 机械300 为空不修改
system_disk_read 系统盘读限制 单位MB  为空不修改,为0不限IO,其他限制单位MB
system_disk_write 系统盘写限制 单位MB  为空不修改,为0不限IO,其他限制单位MB
data_disk_mode 支持参数 writeback,writethrough,none,unsafe,directsync 为空不修改
data_disk_iops 数据盘 固态2400 机械300 为空不修改
data_disk_read 数据盘读限制 单位MB 为空不修改,为0不限IO,其他限制单位MB 否 
data_disk_write 数据盘写限制 单位MB 为空不修改,为0不限IO,其他限制单位MB
network_out 网络上行限制 单位MB 最小1 是 
network_in 网络下行限制 单位MB 最小1
bwlimit 流量限制 单位G 为0不限制或大于0为限制多少G流量每月,为空不修改 否 
bwusage [浮点型]单位G 已用上行流量  如查询主机列表返回是KB 自己 /1024 /1024得到G流量 为空不修改
bwdate 流量重置日期,时间戳 或 标准时间 2018-05-01 08:08:02 (长度19位必须), 为空不修改
snapshot 允许快照创建数量 如:为0不能创建快照, 为空不修改
backup 允许完整备份数量 如:为0不能创建快照 为空不修改
nat_acl_limit 端口映射数量 为0不允许创建, 为空不修改
nat_web_limit 共享IP建站, 为空不允许建站,为空不修改
rvlimit 重装系统限制(每天) 为0不允许,为空不修改
rvcount 已重装次数 为空不修改
rvdate 上次重装日期 格式如:20180501 为空不修改
status 允许参数 running,install,locked,overflow,overbw,overdue,migrate 为空不修改
ip 指定主机IP地址(列表获取 如 192.168.1.3) ,为空不修改
additionals_ip 额外IP(多个以,分割 如192.168.1.4,192.168.1.5) ,为空不修改
成功返回:0

(删除主机)  接口类型:delete_virtual

参数名 参数说明 必须
id / hostname 主机id
force_delete 等于1为强制删除,无视被控返回错误,建议为空,无法删除才使用
成功返回:0

(查询主机列表)  接口类型:virtuals

参数 参数说明 必须
id 主机ID
user_id 用户编号
zone_id 根据区域ID搜索
node_id 根据节点ID搜索
hostname 主机名称 
ip 主机IP
ip_mac 主机公网网卡MAC地址
private_ip 主机私网IP
private_ip_mac 主机私网IP MAC地址
uuid 主机UUID
firewall_uuid 主机对应防火墙UUID
security_group_id 安全组ID(在安全组中可以使用此ID列出未绑定的数据 为0未使用绑定安全组)
template_id 镜像模板ID
cd_rom_id 光驱媒介ID
status 允许参数 running,install,locked,overflow,overbw,overdue,migrate 为空不查询
remark 根据备注模糊查询
order  asc,desc
成功返回:JSON数组

 (登录VNC终端)  接口类型:login_vnc【请拼接以下参数使用get或post访问】会自动跳转到VNC地址

参数名 参数说明 必须
timestamp 时间戳
loginkey md5(后台APIKEY秘钥+timestamp)
id 主机id

(获取主机状态)  接口类型:virtual_status

参数名 参数说明 必须
id 主机id

成功返回:

install|{"bwdate":"2020-08-06 00:00:00","bwlimit":"0","bwusage":"0","hostname":"new888","taskid":"1","taskmessage":"100","taskstatus":"2","tasktype":"2","template_id":"16","template_name":"windows2003r2.qcow2"}

| 前面返回值包含:running,install,installfailed,paused,shutoff,locked,overflow,overbw,overdue,migrate,unknown(未知状态刷新重试)

| 后面JSON参数值:(可选项,如果只是单纯显示主机状态觉得体验不好,就可以用此方法加入一些进度/状态变化/进程等显示给前端增加用户体验度)

参数 说明
bwlimit 限制流量单位G,0为不限制
bwusage 已用流量单位KB
bwdate 下次流量重置清零日期
taskid 任务ID
tasktype 任务类型:1=创建,2=重装,3=备份,4=恢复备份,5=重置IP验证,6=重置系统密码验证IP,7=迁移中
taskmessage 任务内容:比如在创建和重装时可以读取进度条 返回的是复制进度,当复制进度100后,taskstatus会等于2 验证中,验证完毕后这些参数将全部初始化为空
taskstatus 任务状态:0=等待,1=执行中,2=验证中,3=完成,4=错误

(重置主机状态)  接口类型:reset_virtual_status

参数名 参数说明 必须
id / hostname 主机id
status 状态 running,install,locked,overflow,overbw,overdue,migrate
成功返回:0

(重置主机系统密码)  接口类型:reset_system_password

参数名 参数说明 必须
id 主机id
system_password 系统密码(密码6位以上)
type 等于task为任务模式爆破重置密码需要重启, 为空实时修改密码(一般用这个即可)
成功返回:0

(重置主机VNC密码)  接口类型:reset_vnc_password

参数名 参数说明 必须
id 主机id
vnc_password VNC密码(请使用英文+数字组合并大于6位)
成功返回:0

 (重置IPv4地址绑定)  接口类型:reset_virtual_ip

参数名 参数说明 必须
id 主机id(重新将数据库对应主机里的IP绑定到云主机上)
del_rule 等于1删除防火墙规则(安全组失效) 建议为空
成功返回:0

 (重装主机操作系统)  接口类型:reset_system

参数名 参数说明 必须
id 主机id
template_id 镜像ID(列表获取)
reset_system_type 0=格式化C盘,1=全盘格式化
成功返回:0

(主机电源操作)  接口类型:power

参数名 参数说明 必须
id / hostname 主机id
type 支持参数 start,restart,shutdown,force_shutdown,force_restart 

成功返回:0


(主机挂载ISO引导)  接口类型:change_cd_rom

参数名 参数说明 必须
id 主机id
cd_rom_id ISO镜像ID(镜像列表获取)
type mount,umount
成功返回:0

(创建快照,恢复快照,删除快照)  接口类型:snapshots

参数名 参数说明 必须
id 主机id
type create,revert,delete
name 快照名称(创建不需要)
成功返回:create返回 0|快照名称,revert和delete返回0

 (查询快照列表)  接口类型:snapshots

参数名 参数说明 必须
id 快照ID
type list
name 快照名称
status 状态 参数 running,shutoff
virtual_id 主机ID
order asc,desc

成功返回:JSON数组


(创建,恢复,删除完整备份)  接口类型:backups

参数名 参数说明 必须
id 主机id
name 备份名称(创建不需要) 是/否
type create,revert,delete
成功返回: create返回0|备份名称,revert和delete返回0

 (完整备份列表)  接口类型:backups

参数名 参数说明 必须
id  备份ID  否
type  list  是
virtual_id 主机ID
name 备份名称
status 状态:0=正常 1=备份中 2=恢复中
返回成功:JSON数组

(创建,编辑修改安全组)  接口类型:security_groups

参数 参数说明 必须
id 安全组ID,新建为0,编辑为要修改的ID 是/否
type create,edit,delete   (编辑和删除必须提供id,新建不需要ID )
name 创建安全组的名称
user_id 创建到那个用户编号ID下(列表查询用户ID)
remark 备注

成功返回:0

(安全组列表)  接口类型:security_groups

参数名 参数说明 必须
id 安全组id
type list
user_id 用户ID
name 安全组名称
remark 备注
order asc,desc
成功返回:JSON数组

 (安全组应用/同步)  接口类型:security_group_apply

参数 参数说明 必须
id 安全组ID
bind_virtual_id 绑定的主机ID多个以,分割(查询未绑定的可到virtuals列表查询安全组ID=0的主机进行绑定)或可查询当前安全组的ID(查询当前安全组绑定了那些主机等)
user_id 用户ID  

成功返回:0

(安全组策略 添加,修改,删除)  接口类型:security_group_acls

参数名 参数说明 必须
id 安全组 规则id (0新建,不为0要编辑的ID)
type create,edit,delete (编辑和删除必须提供ID,创建不需要)
user_id 用户ID
security_group_id 安全组ID
direction 规则方向 in,out 入方向,出方向
policy 授权策略 accept, drop   允许,拒绝
protocol_type 协议类型all,udp,icmp,tcp
port_start 端口开始 -1为不限制  如果整数最大65535
port_end 端口结束 -1为不限制  如果整数最大65535
priority 优先级1~1000 值越小越优先
level 0=普通用户  100=该记录仅管理看到
ip_start IP开始 0.0.0.0 为不限制
ip_end IP结束 0.0.0.0 为不限制

成功返回:0


 (安全组策略 列表)  接口类型:security_group_acls

参数 参数说明 必须
id 安全组策略ID
type list
user_id 用户ID
security_group_id 安全组ID
direction out,in  出方向,入方向
policy accept,drop  允许,拒绝
protocol_type all,tcp,udp,icmp
level 0=查看用户的 100=查看管理员可以看到的策略
remark 备注查询
order asc,desc
成功返回:JSON数组

 (NAT端口转发 创建,删除)  接口类型:nat_acls

参数名 参数说明 必须
nat_acl_id id
virtual_id 主机ID
protocol_type 协议类型 tcp,udp
interior_port 内部端口如3389
exterior_port 自动生成公网端口
type add,del (如删除只要提供nat_acl_id即可)
成功返回:0

 (NAT端口转发 列表)  接口类型:nat_acls

参数名 参数说明 必须
id 主机id
type list
node_id 节点ID
virtual_id 主机ID
exterior_port 公网端口 如10003
interior_port 内网端口 如3389
protocol_type 协议类型 tcp,udp
ip IP地址
成功返回:JSON数组

 (NAT建站 添加,删除)  接口类型:nat_webs

参数名 参数说明 必须
nat_web_id id
type add,del (如删除只要提供nat_web_id即可)
domain 域名(如rstack.com.cn)
virtual_id 主机ID
interior_port 内部端口 如80端口建站用途
exterior_port 系统自动生成
成功返回:0

 (NAT建站 添加,删除)  接口类型:nat_webs

参数名 参数说明 必须
id 主机ID
type list
node_id 节点ID
virtual_id 主机ID
domain 域名
order asc,desc 正序或反序
成功返回:JSON数组

(重建云服务器)  接口类型:rebuild_virtual

参数 参数说明 必须
id 云服务器ID(注:重建云服务器主要用于节点操作系统重装后的快速恢复)
成功返回:0

(重建全部VNC)  接口类型:rebuild_vnc

成功返回:0

(重建全部NAT端口转发与建站)  接口类型:rebuild_nat

参数 参数说明 必须
node_id 节点ID

成功返回:0

(虚拟网卡获取/启用/禁用)  接口类型:virtual_interface

参数 参数说明 必须
type 支持get,set
id 主机ID
status 支持down,up (如果是get 状态为空即可, 如果为set 必须填写 down或up ,代表禁用和启用) 是/否

成功返回:get返回0|状态(down,up) , set返回0

(云服务器迁移)  接口类型:migrate

参数 参数说明 必须
id 主机ID
node_id 要迁移目标节点ID(不能迁移给自己节点ID)必须2个节点存储路径都一致且自检都通过(注:如果2个节点使用的不同IP池,迁移完毕后需要在平台编辑主机设置新的IP地址并绑定IP让新IP注入到云服务器中)
network 迁移走 公网=0 内网=1 (走内网必须节点服务器绑定了内网IP并且RS节点也写入了内网IP 如果没有请写0)
mode 1=冷迁移普通(任务模式) 2=冷迁移高级(任务模式)(无感迁移,必须开机的) 3=热迁移(实时迁移预计几秒迁移完毕 需共享存储)
timeout 任务运行多久视为超时 一般看自己网络决定 系统默认初始化20分钟 如果网络非常垃圾建议设定长一点

成功返回:0

(获取节点硬件信息)  接口类型:node_info

参数 参数说明 必须
id 节点ID
成功返回:JSON数组

(区域查询)  接口类型:zones

参数名 参数说明 必须
id 按区域id查找
name 按名称
remark 按备注
order asc,desc  正序或反序

成功返回:JSON数组


(计算节点查询)  接口类型:nodes

参数名 参数说明 必须
id  节点ID
name  节点名称
zone_id  区域ID
ip  节点IP
private_ip  节点私有IP
status  0=正常  1=维护中
remark  备注
order  asc,desc  正序或反序
成功返回:JSON数组

(IP池查询)  接口类型:ip_pools

参数名 参数说明 必须
id 池id
name 池名称
bind_node_id 绑定的节点ID(会将全部可用的节点ID对应的IP池列出)
type 类型 ipv4,ipv6,intranet
order asc,desc  正序或反序

成功返回:JSON数组


(IP地址查询)  接口类型:ip_address

参数名 参数说明 必须
ip 按ID查询
ip_pool_id 按IP池ID查询
ip 查询指定IP地址
virtual_id 主机ID (如果为0 查询全部未使用的IP)
status 0=启用中  1=禁用状态
remark 备注查询
order asc,desc  正序或反序

成功返回:JSON数组

(查看主机是否支持NAT转发模式) 接口类型:nat_public_ip

参数 参数说明 说明
virtual_id 主机ID
ip 主机IP

成功返回:公共IP地址,不支持返回为空


(镜像列表查询)  接口类型:templates

参数名 参数说明 必须
id 按镜像id查询
node_id 节点ID(输入节点ID即查询节点允许使用的模板 配合 下面字段type=qcow2查询全部可用的模板安装)
name 显示名称
template_name 实际镜像的名称
system_type 按系统类型 windows,centos,debian,ubuntu
type 镜像类型 qcow2,iso
remark 备注
order asc,desc  正序或反序

成功返回:JSON数组


(任务列表查询)  接口类型:tasks

参数 参数说明 必须
id 任务ID
hostname 主机名
type 1=创建,2=重装,3=备份,4=恢复备份,5=重置IP验证,6=重置系统密码,7=迁移中
status 0=等待 1=执行 2=验证 3=完成 4=错误
node_id 节点ID
limit 限制查询多少条数据,为空不限制
成功返回:JSON数组

(查询主机监控JSON)  接口类型:kvm_monitor_view

参数名 参数说明 必须
id 主机id
yyyymmdd 为空查询当天,可指定日期 格式如 20180501
成功返回:JSON数组

免费使用RStack

即刻下载, 免费体验RStack正式版

开始免费试用 请求演示