帮助文档

KVM API开发文档(2022)

一: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 kvm
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创建) 接口类型:kvm_create

参数名 说明 必须
id 此为自定义的编号,为空数据库自动自增一般为空即可,特殊情况使用
userid vm开通到那个用户编号下
areaid 按区域id开通,自动轮训区域下全部节点,如要指定节点开通请为空 是/否
nodeid 按指定节点id开通 是/否
osid 镜像编号(镜像api列表获取)
vmname 英文或数字 最小2位 (不包含其他字符)
cpu cpu核心数
cpu_limit cpu基线限制,100=不限制cpu 最大100 建议最小不少于50
cpu_mode 0为显示cpu  1为隐藏cpu型号
ram 最小内存(单位mb)
disk vm数据磁盘,为0时不创建数据盘就一个系统盘,反之大于0创建一个数据盘  否 
disk_sys_iops 限制vm系统磁盘iops (单位mb),为空为0不限制
disk_data_iops 限制vm数据磁盘iops(单位mb),为空为0不限制
disk_sys_mode 系统盘(支持参数 writeback,writethrough,none,unsafe,directsync)默认writeback
disk_data_mode 数据盘(支持参数 writeback,writethrough,none,unsafe,directsync)默认writeback
port vm上行端口速率(单位m)最小不能低于1
ports vm下行端口速率(单位mb)最小1
bwlimit 限制每月流量使用 为0不限制(单位g)
backup_snapshot 允许创建快照数量,为0不允许创建,为-1时按全局用户组设置的分配
backup_full 允许创建完整备份数量,为0不允许创建,为-1时按全局用户组设置的分配
portmap 端口映射数量,为0不允许
binding_domain 共享nat建站绑定域名数量,为0不允许
vmpass vps的登录密码 最小6为 不包含特殊字符
vncpass vps vnc密码 最小6位 不包含特殊字符  
remote_port 创建后是否更改远程端口号,为0不更改,为1自动生成随机端口,或自己指定10000~65535之间
ip ip数量,如输入1那么创建分配1个ip,也可以指定ip,列表获取
additionals_ip 额外的ip地址,多个以,分割,如果ip=整数,此字段略过
ipv6 IPV6地址或传数字如1代表分配一个IPV6,非必须字段可以留空
additionals_ipv6 额外IPV6地址,多个以,分割,必须ipv6有主IPV6地址(非数字),并附带额外更多的一般留空即可
iprandom 1=随机ip (必须ip字段=数字时候才会触发),默认等于0
iptype 0=开通ipv4    2=开通内网ipv4    为空按全部ip类型分配(如果节点混开模式才需要指定下)
remark vm备注描述
returnjson 默认为空,如等于1返回方式看如下

 第一种返回方式:

成功返回 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":"","additionals_ipv6":"2699:fcd0:100:9600::223","areaid":"11","areaname":"华东区域1","firewall_uuid":"67496511-70c2-89fc-a149-261648977663","id":"192","ip":"192.168.1.85","ipv6":"2607:fcd0:990:5600::222","mac":"52:54:fa:9b:ce:b1","nodeid":"2","nodename":"可用区2","os":"Centos7.6","osid":"4","privateip":"10.0.3.95","privateip_mac":"00:16:f9:84:83:bb","remark":"","remote_port":"0","status":"0","userid":"8080","uuid":"375c267f-a9c5-52e2-33f9-ce1648977663","vmname":"cloud33455","vmpass":"xiJdWF6Ov1sO","vncpass":"1BVI51eUvdoxeffk"}

 

  (vps更新) 接口类型:kvm_update

参数名 说明 必须
id 编辑修改的主机id
update_vm 默认0,为1时更改硬件信息可能需要重启
areaid 区域id(无特殊情况无需修改)
nodeid 节点id(无特殊情况无需修改)
userid 修改用户编号(类似过户)
cpu cpu核心数
cpu_limit cpu限制 最大100,建议最小不低于50
cpu_mode 0=显示cpu,1=隐藏cpu
ram 内存 (单位mb)
disk 数据盘大小,单位g(只能增加不能缩小)  否 
disk_sys_iops  vm系统盘iops限制(单位mb)为0不限制 否 
disk_data_iops  vm数据盘iops限制(单位mb)为0不限制 否 
disk_sys_mode 系统盘(支持参数 writeback,writethrough,none,unsafe,directsync)默认writeback  
disk_data_mode 数据盘(支持参数 writeback,writethrough,none,unsafe,directsync)默认writeback  
port 上行端口速率 单位mm(最小1) 否 
ports 下行端口速率 单位mb(最小1)  
bwlimit 每个月可用流量 单位g 否 
bwusage 已使用的流量 单位gb  支持浮点数
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(必须传IP格式,列表获取),否则留空
additionals_ipv6 如修改额外IP,多个以,分割(列表获取),否则留空
addipnumber 为主机自动添加多少个ip地址,为空不添加,否则请大于0 (请在主控后台在点击下绑定ip地址才生效,目的激活ip防盗,否则ip人工绑定无法使用)
status 主机状态(0=安装,1=锁定,2=正常,-1=中止,-2=超流量运行,-3=超流量停止)
remark vm描述/备注

成功返回0

    (vps删除) 接口类型:kvm_delete

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

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

    (查询vps可用的ip地址) 接口类型:kvm_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电源操作) 接口类型:kvm_start,kvm_restart,kvm_stop,kvm_force_restart,kvm_force_stop

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

 成功返回0

  (vm状态获取) 接口类型:kvm_state

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

成功返回

running|{"backuptask":"0","bwdate":"1644078526","bwlimit":"0","bwusage":"524288000","os":"windows2003_new","osid":"1","ostype":"windows","taskmsg":"0","taskstatus":"3","taskstep":"3","tasktype":"3","vmname":"new2003"}

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

状态有:

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

(锁定,过期中止,超流量停机,安装错误,安装中,运行中,关机中,挂起中,保存中)

  (vm重置ip) 接口类型:kvm_setips     (此选项主要是把主机ip重新自动在线绑定一次,防止用户误删除ip等)

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

成功返回0

  (vm重置远程端口号) 接口类型:kvm_setport

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

成功返回0

  (vm vnc控制台) 接口类型:kvm_console

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

使用state成功返回json

{"expiretime":"1642696743","state":"enabled","uuid":"95895c62-24d7-a3fa-7206-ff1641195071","vmname":"new2003","vncserver":"http://192.168.1.55:8080","vnctoken":"0tko2ke3a9s9hiu8przwhhjtz3icgvz_bfarxouhqopovznnbhfjtjweeh0exqjnbqnh7upwigg4ycuubqrndszyqkouvn7x-qboaehzcqtaavo-dgtvrz6icpcv5oajxx2jbop3wdh1_lgzt5pl_of3a28_mi8fjif1u2viy7xjgbupq8ntr9lntwftjc17"}

state=enabled为开启vnc中,disabled为未开启vnc请先开启

只需要将拼接get vncserver地址+uuid+vnctoken

演示demo:http://192.168.1.55:8080/?uuid=提取的uuid&token=提取的vnctoken 访问即可连接vnc

使用logout退出vnc  成功返回0

  (vm重装系统) 接口类型:kvm_reload

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

成功返回0

  (vm快照创建/恢复/删除) 接口类型:kvm_snapshot

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

创建成功返回 0|完整备份名称

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

list获取列表 返回json数组

  (vm完整备份创建/恢复/删除) 接口类型:kvm_backup

参数名 说明 必须
vmid 主机id
subvaction create,revert,del
backupname 创建不需要,恢复和删除需要填写

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

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

 

  (vm在线修改密码) 接口类型:kvm_resetps

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

成功返回0

  (vm在线修改vnc密码) 接口类型:kvm_resetvncps

参数名 说明 必须
vmid 主机id
vncpass 新的vnc密码

成功返回0

 

  (vm光驱管理) 接口类型:kvm_cd_manage

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

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

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

成功返回0

  (为主机自动添加ip数量) 接口类型:kvm_addip

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

成功返回0

 

  (共享ip)端口映射 接口类型:kvm_portmap

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

  (共享ip)nat建站 接口类型:kvm_domain

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

 (列表,nat建站列表) 接口类型:kvmnat

参数名 说明 必须
userid 用户id
nodeid 计算节点id
vmid vps id
ip 主机ip
domainname 域名
nattype 1=映射类型,2=建站类型
成功返回json数组

   (获取主机是否支持nat共享ip列表) 接口类型:kvm_exinfo

参数名 说明 必须
vmid 主机id

成功返回json  

导出部分vps数据  (可以根据该信息判断当前是否 共享ip云主机  只需要查看publicip是否等于空该信息在计算节点中设置)

混合云开通可以按转发节点ip的publicip是否等于空,iptype=0,1,2(代表ipv4,ipv6,内网ipv4的类型以此判断当前主机是属于什么ip类型,是否显示转发节点公网ip等)

也有一些如远程端口号查看0为当前端口 非0为目前端口,mac地址,ip地址,类型,os名称 os类型等相关信息

{"bwdate":"1644078526","bwlimit":"0","bwusage":"524288000","id":"41","ip":"192.168.1.58","iptype":"0","mac":"52:54:37:ed:56:f3","nodeid":"2","os":"win2008r2_new","ostype":"windows","privateip":"10.0.0.48","privateip_mac":"00:16:41:3f:d9:ac","publicip":"","remote_port":"0","rvcount":"2","uuid":"95895c62-24d7-a3fa-7206-ff1641195071","vmname":"new2003"}

  (获取区域列表) 接口类型:area

参数名 说明 必须
name 区域名称
label hyper,kvm,server,host
remark 描述/备注

成功返回json数组

  (获取kvm云主机列表) 接口类型:kvm

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

成功返回json数组

  (获取kvm云主机备份列表/快照列表) 接口类型:kvmbackup

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

 成功返回json数组

  (获取kvm ip池列表) 接口类型:kvmipblock

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

 成功返回json数组

  (获取kvm ip列表) 接口类型:kvmip

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

成功返回json数组

 (获取kvm 镜像列表) 接口类型:kvmos

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

成功返回json数组

 (获取kvm 节点列表) 接口类型:kvmnode

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

成功返回json数组

 (获取kvm 任务列表) 接口类型:kvmtask

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

成功返回json数组

  (获取kvm 监控图表) 接口类型:kvm_monitor

参数名 说明 必须
vmid 主机id
yyyymmdd 查询日期,为空查询当天数据
成功返回json数组,如果查询不到返回[]

 

 

免费使用RStack

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

开始免费试用 请求演示