帮助文档

Hyper-z 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 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即可,数字越大,当节点内存不足时优先使用内存
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
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数组

  (为主机自动添加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

参数名 说明 必须
name 区域名称
label hyper,kvm,server,host
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 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数组,如果查询不到返回[]

 

 

 

免费使用RStack

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

开始免费试用 请求演示