一：api接口验证方式

api接口验证地址：http://主控域名/api/v3

api接口响应方式：http post get

api接口ip白名单：支持(建议后台设定有效的api白名单ip)

api验证公共参数：

参数	类型	说明	是否必须
api_sign	string	md5(api秘钥+api_random+api_timestamp)，小写md5	是
api_random	string	随机数（保证不会重复）	是
api_timestamp	int	时间戳（10位长度）	是
api_language	string	如果等于chinese，那么将错误信息返回中文简体（utf-8编码），为空返回英文错误提示	否
api_type	string	hyper	是
action	string	填写下面接口名称	是

二：api接口响应模式

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

三：api接口操作

(测试通讯） 接口名称：test

成功返回：0

 (创建用户) 接口类型：user_add

参数名	参数说明	必须
userid	自定义用户编号，可以是第三方财务的用户id传入，保证唯一性	是
username	用户名	是
password	密码 >=6位	是
name	姓名/名称等	否
email	邮箱地址	是
phone	手机号码	否
vcount	服务数量 默认0	否
utype	默认0（0=普通用户，10=管理员级别，其他自定义分组id）	否
status	用户状态（0=正常用户 1=禁止用户）	是
remark	用户备注信息	否
mail_verified	默认0，等于1为该邮箱地址已验证	否
mobile_verified	默认0，等于1为该手机号码已验证	否
reg_ip	注册ip地址	否
login_ip	登录ip地址	否

成功返回0|188   注意这个188是数据库自增的编号（并非userid编号）

  (修改用户) 接口类型：user_update

参数名	参数说明	必须
id	数据库查询中的自增id（非userid）	是
userid	修改用户编号，类似过户，一般为空不修改	否
password1	为空不修改，反之大于6位	否
password2	确认密码，为空不修改，反之大于6位	否
name	姓名/名称	否
email	邮箱地址	否
phone	手机号码	否
username	用户名	否
vcount	服务数量	否
utype	0=普通用户，10=管理员级别	否
status	0=正常，1=禁用账号	否
mail_verified	等于1已验证邮箱	否
mobile_verified	等于1已验证手机号	否
cvdate	重装限制日期如20190501 或则低于当前时间或则0或则留空即可	否
rvcount	按用户级别 已重装的次数	否
reg_ip	注册ip地址	否
login_ip	登录ip地址	否

成功返回0

   (删除用户) 接口类型：user_delete

参数名	说明	必须
userid	用户编号，（您创建时自定义的非自增id）	是

成功返回0

    (查询用户) 接口类型：user_info

参数名	说明	必须
id	数据库中自增生成的编号	否
userid	自定义的用户编号	否
username	用户名	否
name	按名称	否
email	邮箱地址	否
phone	手机号码	否
utype	用户组id（0=普通用户，10=管理员）	否
login_ip	按登录ip查询（已包含注册ip全部索引查询）	否
remark	按备注信息模糊查询	否

成功返回json数组，不存在返回为空

  (vps创建) 接口类型：vm_create

参数名	说明	必须
id	此为自定义的编号，为空数据库自动自增一般为空即可，特殊情况使用	否
userid	vm开通到那个用户编号下	是
areaid	按区域id开通，自动轮训区域下全部节点，如要指定节点开通请为空	是/否
nodeid	按指定节点id开通	是/否
osid	镜像编号（镜像api列表获取）	是
vmname	英文或数字 最小2位 （不包含其他字符）	是
cpu	cpu核心数	是
cpu_limit	cpu基线限制，100=不限制cpu 最大100 建议最小不少于50	是
cpu_weight	cpu权重，一般为10即可，如果vm权重不同当节点cpu不足情况下按权重高优先分配	是
ram_min	最小内存（单位mb）	是
ram	最大内存（单位mb） 如果最小内存和最大内存相同，则为静态内存，反之动态内存	是
ram_buffer	内存缓存比一般20 （动态内存功能）	是
ram_weight	内存权重一般为50即可，数字越大，当节点内存不足时优先使用内存	是
systemdisk	系统磁盘扩容如：100,150 前者win后者linux用户安装不同系统分配不同系统盘容量，留空按默认值	否
disk	vm数据磁盘，为0时不创建数据盘就一个系统盘，反之大于0创建一个数据盘	否
disk_sys_iops	限制vm系统磁盘iops （单位mb），为空为0不限制	否
disk_data_iops	限制vm数据磁盘iops（单位mb），为空为0不限制	否
port	vm端口速率（单位m）最小不能低于1	是
bwlimit	限制每月流量使用 为0不限制（单位g）	否
backup_snapshot	允许创建快照数量，为0不允许创建，为-1时按全局用户组设置的分配	是
backup_full	允许创建完整备份数量，为0不允许创建，为-1时按全局用户组设置的分配	是
portmap	端口映射数量，为0不允许	是
binding_domain	共享nat建站绑定域名数量，为0不允许	是
vmpass	vps的密码	是
remote_port	创建后是否更改远程端口号，为0不更改，为1自动生成随机端口，或自己指定10000~65535之间	否
ip	ip数量，如输入1那么创建分配1个ip，也可以指定ip，列表获取	是
additionals_ip	额外的ip地址，多个以,分割，如果ip=整数，此字段略过	否
ipv6	ipv6数量，如输入1那么创建分配1个ipv6，也可以指定ipv6,列表获取	否
additionals_ipv6	额外ipv6地址，多个以,分割，需和ipv6字段一同使用（非数字）	否
iprandom	1=随机ip （必须ip字段=数字时候才会触发），默认等于0	否
iptype	0=开通ipv4   2=开通内网ipv4    为空按全部ip类型分配（如果节点混开模式才需要指定下）	否
remark	vm备注描述	否
returnjson	默认为空，如果等于1那么成功返回 0|json 看下面演示

 第一种返回方式：

成功返回 0|188|192.168.1.123  (188为入库后生成的主机编号，后者是主ip地址)

 如果主机分配了多个ip地址那么ip哪里以英文,分割 如2个ip： 成功返回 0|188|192.168.1.123,192.168.1.124

第二种返回方式：

如果 returnjson=1 返回如下： （格式：）0|json信息，additionals_ip如果多ipv4则以,分割，additionals_ipv6 如果多ipv6则以为，分割

0|{"additionals_ip":"192.168.1.19,192.168.1.20","additionals_ipv6":"2607:fcd0:1999:8600::1040","areaid":"1","areaname":"华东区域","guid":"","id":"341","ip":"192.168.1.18","ipv6":"2607:fcd0:100:5600::1030","mac":"00:15:5d:2b:63:90","nodeid":"1","nodename":"可用区 a","os":"centos7.6","osid":"15","remark":"","remote_port":"0","status":"0","userid":"8080","vmname":"cloud33453","vmpass":"9pgu0skw2sdh"}

  (vps更新) 接口类型：vm_update

参数名	说明	必须
id	编辑修改的主机id	是
update_vm	默认0，为1时更改硬件信息可能需要重启	否
areaid	区域id（无特殊情况无需修改）	否
nodeid	节点id（无特殊情况无需修改）	否
userid	修改用户编号（类似过户）	否
cpu	cpu核心数	否
cpu_limit	cpu限制 最大100，建议最小不低于50	否
cpu_weight	cpu权重 最大100	否
ram_min	最小内存 （单位mb）	否
ram	最大内存（单位mb）如果最大最小内存相等，为静态内存	否
ram_buffer	内存缓存比（动态内存功能），一般为20	否
ram_weight	内存权重 最大100，推荐50	否
systemdisk	系统盘扩容如100,150 前者win后者linux，留空按默认，设置后重装系统才有效	否
disk	数据盘大小，单位g（只能增加不能缩小）	否
disk_sys_iops	vm系统盘iops限制（单位mb）为0不限制	否
disk_data_iops	vm数据盘iops限制（单位mb）为0不限制	否
port	端口速率 单位m（最小1）	否
bwlimit	每个月可用流量 单位g	否
bwusage	已使用的流量	否
bwdate	下次重置流量日期，时间戳或则指定格式如：2019-11-15 00:28:22	否
backup_snapshot	快照数量为0不允许，为-1按用户组设定的全局	否
backup_full	备份数量为0不允许，为-1按用户组设定的全局	否
portmap	端口映射数量 为0不允许	否
binding_domain	nat建站数量	否
rvcount	已重装次数	否
cvdate	上次重装系统的日期 格式如 20190816	否
ip	如修改ip（必须传ip格式 列表获取）	否
additionals_ip	修改额外ip，多个以,分割  （列表获取）	否
ipv6	如修改ipv6（必须传ipv6格式，列表获取），否则不修改留空	否
additionals_ipv6	如修改额外ipv6，多个以,分割，否则请留空	否
addipnumber	为主机自动添加多少个ip地址，为空不添加，否则请大于0 （请在主控后台在点击下绑定ip地址才生效，目的激活ip防盗，否则ip人工绑定无法使用）	否
status	主机状态（0=安装，1=锁定，2=正常，-1=中止，-2=超流量运行，-3=超流量停止）	否
remark	vm描述/备注	否

成功返回0

    (vps删除) 接口类型：vm_delete

参数名	说明	必须
vmid	主机编号	是
forcedelete	默认0，为1强制删除主机	否
returnmsg	默认空，为1时删除后成功返回 0|json信息	否

成功返回0  如果returnmsg=1 那么成功返回 0|json信息

    (查询vps可用的ip地址) 接口类型：vm_freeip

参数名	说明	必须
nodeid	根据计算节点id查询全部可用的ip地址（一般用于新创建vm查询可用镜像使用）	是
vmid	默认空，如果输入主机id，那么将所有 空闲ip+vm正在用的ip全部查询出来，方便做到下拉框显示ip列表那些选中状态，否则为空，只查询根据节点所有可用的ip来展示输出json	否
iptype	0,1,2（各代表查询ipv4,ipv6,内网ipv4）为空查询全部，或则如0,2查询公网ipv4和内网ipv4一起查询	否
iprandom	0=按顺序（默认），1=将查询ip打乱后输出（适用于开通按随机ip）	否
limits	查询多少条  为空查询全部	否

 成功返回json数组

 (vps电源操作) 接口类型：vm_start，vm_restart，vm_stop，vm_force_restart，vm_force_stop

参数名	说明	必须
vmid	主机编号	是

 成功返回0

  (vm状态获取) 接口类型：vm_state

参数名	说明	必须
vmid	主机编号	是

成功返回

running|{"backuptask":"0","bwdate":"1635756349","bwlimit":"500","bwusage":"0","osid":"15","ostype":"centos","taskmsg":"0","taskstatus":"3","taskstep":"3","tasktype":"3","vmname":"yuan","os":"centos7.6.vhdx"}

（按|分割） 在|前者是状态 ，后者是一些任务进度的类型 名称等字面意思

状态有：

locked，overdue，overbw，setupfailed，setup running，off，paused，saved

（锁定，过期中止，超流量停机，安装错误，安装中，运行中，关机中，挂起中，保存中）

  (vm重置ip） 接口类型：vm_setips     （此选项主要是把主机ip重新自动在线绑定一次，防止用户误删除ip等）

参数名	说明	必须
vmid	主机编号	是

成功返回0

  (vm重置远程端口号） 接口类型：vm_setport

参数名	说明	必须
vmid	主机编号	是
remote_port	0=恢复初始端口，1=随机端口生成 （或指定10000~65535内的端口）	是

成功返回0

  (vm vnc控制台） 接口类型：vm_console

参数名	说明	必须
vmid	主机编号	是
subvaction	state,enable,logout  (获取状态，开启vnc，退出vnc)	是

使用state成功返回json

{"expiretime":"","guid":"138d0073-5026-458d-b2b6-77084e8628fe","nodeip":"192.168.1.23","state":"enabled","vmname":"vnc_yuan","vncserver":"http://192.168.1.23:8001","vnctoken":""}

使用enable成功返回0，再次查询返回，请自行结合主控平台的后缀js加密后提交http即可进入vnc控制台

{"expiretime":"1636995382","guid":"138d0073-5026-458d-b2b6-77084e8628fe","nodeip":"192.168.1.23","state":"enabled","vmname":"vnc_yuan","vncserver":"http://192.168.1.23:8001","vnctoken":"stpj"}

使用logout退出vnc  成功返回0

  (vm重装系统） 接口类型：vm_reload

参数名	说明	必须
vmid	主机编号	是
osid	镜像id，列表获取	是
rot	等于0只重装系统盘，等于1=全盘重装	是

成功返回0

  (vm快照创建/恢复/删除） 接口类型：vm_snapshot

参数名	说明	必须
vmid	主机编号	是
subvaction	create,revert,del,list	是
snapshotname	创建不需要，恢复和删除需要填写	是

创建成功返回 0|快照名称

删除成功返回/恢复成功返回0

list获取列表 返回json数组

  (vm在线修改密码） 接口类型：vm_resetps

参数名	说明	必须
vmid	主机编号	是
vmuser	为空系统使用默认账号，否则自动创建一个账号（目前仅支持windows系统自建账号）
vmpass	修改的密码（>=6）	是

成功返回0

  (vm光驱管理） 接口类型：vm_cd_manage

参数名	说明	必须
vmid	主机编号	是
subvaction	change,list （更改，列表）	是
cdid	cd镜像id（列表获取）-1为卸载vm光驱，否则请输入光驱id	是

subvaction=list 成功查询返回json数组，查询没有 返回为空

subvaction=change 必须填写cdid的编号，如果cdid=-1为卸载光驱

成功返回0

  (共享ip）端口映射 接口类型：vm_portmap

参数名	说明	必须
portid	映射规则id，列表查询，仅限删除才用到此id，使用此id以下参数名都不用填写	否
vmid	主机id	是
subvaction	支持子类型 add,del	是
privateport	内部端口：如3389  范围1-65535	是

成功返回0

  (共享ip）nat建站 接口类型：vm_domain

参数名	说明	必须
domainid	规则的id，列表查询，仅限删除才用到此id，使用此id以下参数名都不用填写	否
vmid	主机id	是
subvaction	子类型：add,del	是
domainname	绑定域名	是
privateport	内部网站端口 如80	是

 （列表，nat建站列表） 接口类型：hypernat

参数名	说明	必须
userid	用户id	否
nodeid	计算节点id	否
vmid	vps id	否
ip	主机ip	否
domainname	域名	否
nattype	1=映射类型，2=web建站类型	否

成功返回json数组

 (添加/删除）安全组 接口类型：vm_safegroup

参数名	说明	必须
subvaction	add,del	是
vmid	主机id	是
safeid	只有删除(del)安全组id才提供这个字段即可，添加请不要传这个字段	否
direction	inbound,outbound   (代表 进和 出方向)	是
protocol	tcp,udp,all  (代表，tcp协议,udp协议,all=全部)	是
port	端口（1-65535）	是
actiontype	allow,deny   （代表 允许，拒绝）	是
ip	允许的ip：0.0.0.0代表任意ip，或则请指定ip	是

成功返回0

 

 

  (为主机自动添加ip数量） 接口类型：vm_addip

参数名	说明	必须
vmid	主机id	是
ip_num	ip数量（大于0），否则请留空	否
ipv6_num	ipv6数量（大于0），否则请留空	否
binding_ip	等于1自动将新ip绑定到主机，否则只更新数据库为主机ip	否

成功返回0

  (获取主机是否支持nat共享ip列表） 接口类型：vm_exinfo

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

成功返回json  （可以根据publicip是否为空，确认这个所在云主机是否支持共享ip云主机，当然remote_port=0为默认远程端口，如果大于10000 小于65535，代表远程连接端口号）

其他字段说明：

iptype=（0,1,2 = 公网ipv4，ipv6，内网ipv4），当前云主机所在ip属于公网v4还是内网v4的ip，可以区分

bwlimit=0为不限制流量 单位g，

rvcount=重装的次数

{"bwdate":"1645975100","bwlimit":"0","bwusage":"0","guid":"143f8cb7-084a-4a79-ba55-827842ce6595","id":"309","ip":"172.16.3.3","iptype":"2","mac":"00:15:5d:e0:64:5d","os":"windows 2003r2","ostype":"windows","publicip":"192.168.1.202","remote_port":"0","rvcount":"0","vmname":"natwin2003"}

  (获取区域列表） 接口类型：area

参数名	说明	必须
id	区域id	否
name	区域名称	否
remark	描述/备注	否

成功返回json数组

  (获取hyper云主机列表） 接口类型：hyper

参数名	说明	必须
id	主机id	否
areaid	区域编号	否
nodeid	节点编号	否
vmname	主机名称	否
guid	主机guid	否
ip	主机ip地址	否
ipv6	主机ipv6地址	否
osid	镜像编号	否
cdid	媒介光驱编号	否
status	状态（0=安装，1=锁定，2=正常，-1=中止，-2=超流量运行，-3=超流量停机）	否
remark	主机描述	否

成功返回json数组

  (获取hyper云主机备份列表/快照列表） 接口类型：hyperbackup

参数名	说明	必须
userid	用户编号	否
vmid	主机编号	否
backuptype	1=快照，2=完整备份，为空查询全部	否
name	根据快照名/备份名查询	否
status	状态（1=正常完成）	否

 成功返回json数组

 (获取hyper云主机安全组列表） 接口类型：safegroup

参数名	说明	必须
id	安全组id	否
vmid	主机id	是
ip	安全组策略ip	否

成功返回json数组  demo演示：

[{"id":"48","vmid":"9","vtype":"hyper","direction":"inbound","actiontype":"allow","protocol":"tcp","port":"3389","ip":"0.0.0.0","priority":"2","remark":""}]

 

 

  (获取hyper ip池列表） 接口类型：hyperipblock

参数名	说明	必须
id	池id	否
name	名称	否
nodeid	节点id	否
ip	根据主机ip返回池信息（如返回网关掩码等）	否
iptype	0=ipv4 ,1=ipv6 , 2=内网ipv4 为空查询全部	否

 成功返回json数组

  (获取hyper ip列表） 接口类型：hyperip

参数名	说明	必须
ipblockid	ip池编号	否
vmid	主机id（或则如 0|主机编号，这样会把指定空闲ip与vmid所有一起查询出来，方便实现下拉列表记录）	否
ip	根据主机ip查询	否
iptype	0=查询ipv4，1=查询ipv6   为空查询全部	否
remark	备注	否

成功返回json数组

 (获取hyper 镜像列表） 接口类型：hyperos

参数名	说明	必须
id	镜像编号	否
name	镜像名 如windows2008r2	否
osname	镜像实际名称（如windows.208r2.vhdx）	否
ostype	镜像类型，支持类型查询（windows,centos,debian,ubuntu）以主控后台为准	否
osfile	支持类型（os,cd） 镜像 , iso镜像	否
remark	描述	否
vmid	注：使用该字段必须指定osfile类型（查询vps在计算节点允许的镜像分配，一把用于重装系统调用此选项输出镜像列表）	否
nodeid	注：使用该字段必须指定osfile类型（根据节点id，查询指定可用的镜像列表）	否

成功返回json数组

 (获取hyper 节点列表） 接口类型：hypernode

参数名	说明	必须
id	节点id	否
areaid	区域id (多个id请以,分割)	否
ip	节点ip	否
maxcpu	查询>=的最大cpu资源（一般用于查询这个节点下是否有资源够开通云主机的核心数量）	否
allowram	查询>=的最大空闲内存（一般用于查询这个节点下是否有资源够开通云主机的内存数 单位mb）	否
allowdisk	查询>=的最大空闲磁盘（一般用于查询这个节点下是否有资源够开通云主机的硬盘数 单位g）	否
status	0=正常，1=维护中	否
remark	备注	否
limits	限制查询几条 默认查询全部	否

成功返回json数组

 (获取hyper 任务列表） 接口类型：hypertask

参数名	说明	必须
vmid	主机id	否
vmname	主机名称	否
tasktype	任务类型（1=创建，2=重装，3=备份，4=恢复备份，5=重置ip，6=重置密码，7=重置端口）	否
taskstep	任务步骤 1=正在复制，2=复制完毕正在启动 3=完成	否
status	任务状态 0=等待安装 1=正在安装 2=正在启动验证联网 3=完成	否
nodeid	节点编号	否

成功返回json数组

 

  (获取hyper 监控图表） 接口类型：vm_monitor

参数名	说明	必须
vmid	主机id	是
yyyymmdd	查询日期，为空查询当天数据	否

成功返回json数组，如果查询不到返回[]

字段说明：cpu字段=百分比，disk=系统读,系统写，数据盘读，数据盘写，memory=已使用，总内存，百分比，network=上行，下行，vmname=云主机名称

 [{"cpu":"0.1","disk":"0,0,0,0","memory":"1024,1024,0","network":"0,1","systemversion":"rstack v1.0","time":"1661702416","times":"2022-08-29 00:00:16","vmname":"ser50861952"},{"cpu":"0.1","disk":"0,0,0,0","memory":"1024,1024,0","network":"0,0","systemversion":"rstack v1.0","time":"1661702476","times":"2022-08-29 00:01:16","vmname":"ser50861952"}]