实例
创建虚拟机
接口描述
创建虚拟机。
接口路径
POST /v1/domains
请求参数
名称 | 类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
name | string | 否 | vm+vmId | 虚拟机name |
memory | int | 是 | 虚拟机内存(KB) | |
cpu_count | int | 是 | 虚拟机cpu数量 | |
networks | []Network | 否 | default(NAT)网络 | 虚拟机网络配置 |
gpu_model | string | 否 | GPU型号 | |
gpu_count | int | 否 | 1(指定GPU型号时,默认配置一块GPU) | GPU数量 |
system_volume | Volume | 是 | 虚拟机系统盘配置 | |
data_volumes | []Volume | 否 | 虚拟机数据盘配置 | |
count | int | 否 | 1 | 虚拟机数量 |
image_id | int | 是 | 镜像ID | |
datacenter_id | int | 是 | 数据中心ID |
Network:
名称 | 类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
network_id | int | 是 | 网络id(网络id和子网id必须使用一个) | |
subnet_id | int | 是 | 子网id(网络id和子网id必须使用一个) | |
type | string | 是 | 网络类型,当前支持default(nat)和bridge两种类型 |
Volume:
名称 | 类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
capacity | int | 是(当指定backing_file时,capacity的值不应小于backing_file磁盘的size) | 磁盘容量 | |
storage_pool | string | 是 | 磁盘所在存储池 | |
format | string | 否 | qcow2(qcow2格式的磁盘才支持快照功能) | 磁盘格式 |
backing_file | string | 否 | qcow2磁盘的backing file | |
backing_file_pool | string | 否 | backing file所在存储池 | |
filesystem | string | 否 | Windows系统为ntfs,Linux系统为ext4 | 磁盘文件系统 |
请求示例:
// 创建桥接网络虚拟机
{
"name": "demo1",
"memory": 60817408,
"cpu_count": 18,
"image_id": 6,
"data_volumes": [
{"capacity": 320,"storage_pool": "vmdata"}
],
"datacenter_id": 6,
"networks": [ // 虚拟机有三块网卡
{"subnet_id": 18, "type":"bridge"},
{"subnet_id": 19, "type":"bridge"},
{"subnet_id": 20, "type":"bridge"}
],
"gpu_model":"NVIDIA GeForce RTX 3070 Ti",
"count": 40 // 批量创建40台虚拟机
}
响应数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述 |
data | []int | 虚机ID |
reason | string | 异常时的原因 |
重启虚拟机
接口描述
重启虚拟机(异步)。
接口路径
PUT /v1/domains/:id/reboot
请求参数
参数名称 | 是否必须 | 示例 | 备注 |
---|---|---|---|
id | 是 | /v1/domains/1/reboot | 虚拟机id |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
task_id | int | 任务id(重启为异步操作,可以通过虚机id查看虚机状态,或者通过任务id查看重启任务状态) |
reason | string | 异常时的原因 |
启动虚拟机
接口描述
启动虚拟机。
接口路径
PUT /v1/domains/:id/start
请求参数
参数名称 | 是否必须 | 示例 | 备注 |
---|---|---|---|
id | 是 | /v1/domains/1/start | 虚拟机id |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
reason | string | 异常时的原因 |
关闭虚拟机
接口描述
关闭虚拟机(异步)。
接口路径
PUT /v1/domains/:id/shutdown
请求参数
参数名称 | 是否必须 | 示例 | 备注 |
---|---|---|---|
id | 是 | /v1/domains/1/shutdown | 虚拟机id |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
task_id | int | 任务id(关闭虚机为异步操作,可以通过虚机id查看虚机状态,或者通过任务id查看关闭虚机任务状态) |
reason | string | 异常时的原因 |
强制关机
接口描述
强制关机。
接口路径
PUT /v1/domains/:id/destroy
请求参数
参数名称 | 是否必须 | 示例 | 备注 |
---|---|---|---|
id | 是 | /v1/domains/1/destroy | 虚拟机id |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
reason | string | 异常时的原因 |
重置虚拟机
接口描述
重建虚拟机(异步)。
接口路径
PUT /v1/domains/:id/rebuild
请求参数
路径参数:
参数名称 | 是否必须 | 示例 | 备注 |
---|---|---|---|
id | 是 | /v1/domains/1/rebuild | 虚拟机id |
body参数:
参数名称 | 参数类型 | 默认值 | 描述 |
---|---|---|---|
rebuild_self | bool | 使用当前镜像重装虚拟机 | |
image_id | int | 使用指定镜像重置系统盘 | |
system_disk | Volume | ||
data_disks | []Volume | ||
auto_boot | bool | false | 重置后是否启动虚拟机 |
请求示例:
// 使用虚机磁盘的当前backing file重置,并自动开机
{"rebuild_self": true, "auto_boot":true}
// 使用指定镜像重置系统盘
{"image_id":1, "auto_boot":true}
// 使用指定镜像重置系统盘,指定backing_file重置数据盘
{
"image_id": 1,
"data_disks": [
{
"backing_file_id": 11
}
],
"auto_boot":true
}
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
task_id | int | 任务id |
reason | string | 异常时的原因 |
查看实例就绪状态
接口描述
查看当前实例是否就绪(操作系统是否已完全启动)。
接口路径
GET /v1/domains/:id/readiness
请求参数
路径参数:
参数名称 | 是否必须 | 示例 | 备注 |
---|---|---|---|
id | 是 | /v1/domains/1/readiness | 虚拟机id |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
data | string | 就绪状态: Ready:已就绪 NotReady:未就绪 |
reason | string | 异常时的原因 |
查看虚拟机
接口描述
查看虚拟机详情。
接口路径
GET /v1/domains/:id
请求参数
参数名称 | 是否必须 | 示例 | 备注 |
---|---|---|---|
id | 是 | /v1/domains/1 | 虚拟机id |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
data | object | 响应数据,数据结构见示例 |
reason | string | 异常时的原因 |
返回数据示例:
{
"code": 100001,
"msg": "success",
"data": {
"id": 7, // 虚拟机id
"created_at": "2025-01-22T11:13:54.099+08:00", // 创建时间
"updated_at": "2025-01-22T11:14:31.158+08:00", // 更新时间
"uuid": "f3d1d7a9-f4e8-4b06-b861-a99b2b8760f0", // 虚拟机uuid
"name": "vm012", // 虚拟机名字
"os": "windows10", // 虚拟机系统
"real_name": "vm7", // 虚拟机在服务器上的名字(vm+id)
"state": "running", // 虚拟机状态
"memory": 8388608, // 内存(KB)
"max_memory": 8388608, // 最大可用内存(KB)
"cpus": 4, // cpu核心数
"cpu_model": "Intel(R) Xeon(R) CPU E5-2650 v3 @ 2.30GHz", // CPU型号
"server_id": 2, // 服务器id
"server_hostname": "10.100.9.31", // 服务器hostname
"server_ip": "10.100.9.31", // 服务器ip
"image_id": 2, // 镜像id
"datacenter_id": 1, // 数据中心id
"datacenter_name": "office", // 数据中心名称
"is_release": false, // 是否已是否
"volumes": [ // 虚拟机磁盘
{
"id": 9, // 磁盘id
"created_at": "2025-01-22T11:13:54.118+08:00", // 创建时间
"updated_at": "2025-01-22T11:14:31.162+08:00", // 更新时间
"volume_name": "3aebf81268514e0f8b3c7c61b0fbffc2", // 磁盘文件名称
"device": "vda",
"capacity": 40, // 磁盘容量
"type": "file", // 磁盘类型
"is_system": true, // 是否是系统盘
"backing_file": "/opt/export/baseimg/debug_ems.qcow2", // 磁盘镜像文件
"backing_file_pool": "baseimg", // 磁盘镜像存储池名称
"backing_file_format": "qcow2", // 磁盘镜像格式
"mount_flag": "persistent", // 挂载选项
"disk_type": "SSD", // 磁盘类型
"filesystem": "",
"path": "/opt/srv/kvm/3aebf81268514e0f8b3c7c61b0fbffc2", // 磁盘路径
"storage_pool": "local_system", // 磁盘所在存储池名称
"storage_pool_name": "local_system", // 磁盘所在存储池名称
"storage_pool_id": 1, 磁盘所在存储池id
"format": "qcow2", // 磁盘格式
"datacenter_name": "office",
"virtual_machine_id": 7,
"volume_type": "volume",
"image_id": 2,
"uid": 1,
"parent": 2,
"root": 9,
"active": 9,
"aged": false
},
{
"id": 10,
"created_at": "2025-01-22T11:13:54.118+08:00",
"updated_at": "2025-01-22T11:14:31.163+08:00",
"volume_name": "0112e9c1969b4e05a5a2f957c15a2060",
"device": "sdb",
"capacity": 100,
"type": "file",
"backing_file": "/opt/srv/kvm/d48ea901ad864f9894ccb721156d09e6",
"backing_file_format": "qcow2",
"mount_flag": "persistent",
"disk_type": "SSD",
"filesystem": "ntfs",
"path": "/opt/srv/kvm/0112e9c1969b4e05a5a2f957c15a2060",
"storage_pool": "local_system",
"storage_pool_name": "local_system",
"storage_pool_id": 1,
"format": "qcow2",
"datacenter_name": "office",
"virtual_machine_id": 7,
"volume_type": "volume",
"uid": 1,
"parent": 11,
"root": 10,
"active": 10,
"aged": false
}
],
"ip_addresses": [ // 虚拟机网络信息
{
"id": 7,
"created_at": "2025-01-22T11:13:54.131+08:00",
"updated_at": "2025-01-22T11:14:31.16+08:00",
"ip": "192.168.122.99",
"mac_address": "a8:3a:44:3e:cb:76",
"bridge_name": "default",
"state": 2,
"static": false,
"virtual_machine_id": 7,
"subnet_id": 0
}
],
"deleted_at": null
}
}
虚拟机state字段含义
- running:运行中
- starting:启动中
- start_failure:启动失败
- creating:创建中
- create_failure:创建失败
- shutting_down:关机中
- shutdown_failure:关机失败
- shutdown:已关机
- destroy:已销毁
- paused:已挂起
- snapshot_reverting:正在使用快照回滚
- snapshot_revert_failure:使用快照回滚失败
- rebuilding:正在重置虚拟机
- rebuild_failure:重置虚拟机失败
- rebooting:重启中
- reboot_failure:重启失败
- migrating:迁移中
- migrate_failure:迁移失败
- unknown:未知
查看虚拟机列表
接口描述
查看虚拟机列表。
接口路径
GET /v1/domains
请求参数
参数名称 | 是否必须 | 示例 | 备注 |
---|---|---|---|
datacenter_id | 否 | /v1/domains?datacenter_id=1 | 查询指定数据中心的虚拟机 |
server_id | 否 | /v1/domains?server_id=1 | 查询指定服务器上的虚拟机 |
state | 否 | /v1/domains?state=running | 查询指定状态的虚拟机 |
mac | 否 | /v1/domains?mac=a8:06:cb:be:c9:04 | 通过mac地址过滤虚拟机 |
offset | 否 | /v1/domains?offset=10 | 跳过记录数量 |
limit | 否 | /v1/domains?limit=10 | 限制查询数量(default:100) |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
data | []object | 响应数据,数据结构见示例 |
reason | string | 异常时的原因 |
返回数据示例:
{
"code": 100001,
"msg": "success",
"data": {
"count": 2,
"items": [
{
"id": 5, // 实例id
"created_at": "2025-01-22T10:58:14.704+08:00", // 实例创建时间
"updated_at": "2025-01-22T11:13:40.877+08:00", // 实例更新时间
"uuid": "002263a9-fc96-475e-846d-954211582f2a", // 实例uuid
"name": "vm", // 实例name
"os": "windows10", // 系统
"real_name": "ins5", // 实例在服务器上的name
"state": "running", // 实例状态
"memory": 8388608, // 内存(KB)
"max_memory": 8388608, // 最大可用内存(KB)
"cpus": 4, // cpu
"cpu_model": "Intel(R) Xeon(R) CPU E5-2650 v3 @ 2.30GHz", // CPU型号
"server_id": 2, // 实例所在服务器id
"server_hostname": "10.100.9.31", // 实例所在服务器hostname
"server_ip": "10.100.9.31",
"datacenter_id": 1, // 数据中心id
"datacenter_name": "office", // 数据中心名称
"is_release": false, // 实例是否已经被释放
"deleted_at": null
},
{
"id": 7,
"created_at": "2025-01-22T11:13:54.099+08:00",
"updated_at": "2025-01-22T11:14:31.158+08:00",
"uuid": "f3d1d7a9-f4e8-4b06-b861-a99b2b8760f0",
"name": "vm012",
"os": "windows10",
"real_name": "ins7",
"state": "running",
"memory": 8388608,
"max_memory": 8388608,
"cpus": 4,
"cpu_model": "Intel(R) Xeon(R) CPU E5-2650 v3 @ 2.30GHz",
"server_id": 2,
"server_hostname": "10.100.9.31",
"server_ip": "10.100.9.31",
"datacenter_id": 1,
"datacenter_name": "office",
"is_release": false,
"deleted_at": null
}
]
}
}
挂载磁盘
接口描述
挂载磁盘到虚拟机。
接口路径
PUT /v1/domains/mount
请求参数
参数名称 | 参数类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
domain_id | int | 是 | 虚拟机Id | |
volume_id | int | 是 | volume id | |
readonly | bool | 否 | false | 是否只读挂载 |
flags | string | 是 | 挂载选项: - live:必须在开机状态下挂载,重启后失效; - config:需要重启虚机后生效; - persistent:即时生效,重启后不失效(相当于live+config,必须要在开机状态使用) |
|
serial | string | 否 | 挂载时指定磁盘serial |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
reason | string | 异常时的原因 |
卸载磁盘
接口描述
从虚拟机卸载磁盘。
接口路径
PUT /v1/domains/umount
请求参数
参数名称 | 参数类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
domain_id | int | 是 | 虚拟机Id | |
volume_id | int | 是 | volume id | |
flags | string | 是 | 卸载选项: - live:必须在开机状态下挂载,重启后失效; - config:需要重启虚机后生效; - persistent:即时生效,重启后不失效(相当于live+config,必须要在开机状态使用) |
|
deletable | bool | 否 | false | 卸载后是否要删除磁盘 |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
reason | string | 异常时的原因 |
修改虚拟机配置
接口描述
修改虚拟机CPU、内存、磁盘配置。
接口路径
PUT /v1/domains/:id/modify
请求参数
路径参数
参数名称 | 参数类型 | 是否必须 | 备注 |
---|---|---|---|
id | int | 是 | 虚拟机id |
body参数
参数名称 | 参数类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
memory | int | 否 | 内存(KB) | |
cpus | int | 否 | cpu | |
system_disk_capacity | int | 否 | 系统盘容量(GB) | |
data_disk_capacity | int | 否 | 数据盘容量(GB) | |
power_on | bool | 否 | false | 修改完配置后是否自动开机 |
多数据盘虚机暂不支持修改数据盘容量
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
reason | string | 异常时的原因 |
删除虚拟机
接口描述
删除虚拟机。
接口路径
DELETE /v1/domains/:id
请求参数
路径参数
参数名称 | 参数类型 | 是否必须 | 备注 |
---|---|---|---|
id | int | 是 | 虚拟机id |
query参数
参数名称 | 参数类型 | 是否必须 | 示例 | 备注 |
---|---|---|---|---|
delete_volumes | string | 否 | ?delete_volume=all | 删除虚机时,是否删除虚机磁盘,可选值: all:删除虚机所有磁盘; system:删除系统盘; data:删除数据盘; none:只删除虚机,不删除磁盘(default) |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
reason | string | 异常时的原因 |
执行命令
接口描述
在虚拟机内执行系统命令。
接口路径
POST /v1/domains/guest-command
接口参数
参数名称 | 类型 | 是否必须 | 默认值 | 备注 |
---|---|---|---|---|
id | int | 是 | 虚拟机id | |
cmd | string | 是 | 命令 | |
args | array | 否 | 命令参数 | |
cmd_type | string | 否 | build-out | build-in OR build-out build-in用于执行qemu-guest-agent内置的命令 build-out用于执行自定义命令 |
timeout | string | 否 | 15秒 | 超时时间 |
build-in可用命令:
command | 含义 |
---|---|
help |
查看帮助(guest-info ) |
get-network |
查看虚机网络信息 |
ping |
Ping the guest agent,如果不返回错误信息,则成功 |
get-hostname |
获取主机名 |
get-time |
获取虚拟机系统时间(相对于1970-01-01 in UTC) |
get-timezone |
获取时区 |
get-user |
获取用户 |
get-os |
获取虚机系统信息 |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
data | Result | 异常时的原因 |
Result:
名称 | 类型 | 描述 |
---|---|---|
id | int | |
exit_code | int | 0:表示命令执行成功,可从stdout读取命令执行结果; -1表示内部错误,从stderr读取错误详情; 大于0表示命令执行失败,从stderr读取命令执行失败结果。 |
stdout | string | 命令执行成功结果。 |
stderr | string | 命令执行失败结果。 |
创建快照
接口描述
创建虚拟机快照(异步)。
接口路径
POST /v1/snapshots
接口参数
参数名称 | 类型 | 是否必须 | 默认值 | 备注 |
---|---|---|---|---|
domain_id | int | 是 | 虚拟机Id | |
name | string | 是 | 快照名称 | |
description | string | 否 | 快照描述 | |
backup_type | int | 否 | 快照类型 | 可用值: 1:只给系统盘做快照 2:只给数据盘做快照 3:给所有磁盘做快照 |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
reason | string | 响应异常时的原因 |
data | Object | 响应数据 |
Object:
名称 | 类型 | 描述 |
---|---|---|
backup_id | int | 快照Id |
task_id | int | 任务Id |
快照回滚
接口描述
使用快照回滚虚拟机(回滚后并不会自动开机,异步)。
接口路径
PUT /v1/snapshots/:id/revert
接口参数
参数名称 | 类型 | 是否必须 | 默认值 | 备注 |
---|---|---|---|---|
id | int | 是 | 快照Id |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
reason | string | 响应异常时的原因 |
data | Object | 响应数据 |
Object:
名称 | 类型 | 描述 |
---|---|---|
task_id | int | 任务Id |
删除快照
接口描述
删除快照(异步)。
接口路径
DELETE /v1/snapshots/:id
DELETE /v1/snapshots/:id
接口参数
路径参数
参数名称 | 类型 | 是否必须 | 默认值 | 备注 |
---|---|---|---|---|
id | int | 是 | 快照Id | |
路径参数 |
参数名称 | 类型 | 是否必须 | 默认值 | 备注 |
---|---|---|---|---|
id | int | 是 | 快照Id |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
reason | string | 响应异常时的原因 |
查看快照列表
接口描述
查看快照列表。
接口路径
GET /v1/snapshots
接口参数
query参数:
参数名称 | 类型 | 是否必须 | 默认值 | 备注 |
---|---|---|---|---|
vm_id | int | 否 | 虚拟机id | |
limit | int | 否 | 100 | 限制查询数量 |
offset | int | 否 | 跳过记录数 |
返回数据
名称 | 类型 | 描述 |
---|---|---|
code | int | 状态码(100001表示成功,其它表示异常) |
msg | string | 状态码描述信息 |
data | []object | 响应数据,数据结构见示例 |
reason | string | 异常时的原因 |
返回数据示例:
{
"code": 100001,
"data": {
"count": 1,
"count": 1,
"items": [
{
"id": 1, // 快照id
"created_at": "2025-02-19T06:45:30.442Z", // 创建时间
"updated_at": "2025-02-19T06:46:30.595Z", // 更新时间
"name": "test001", // 快照名称
"description": "", // 快照描述
"status": "active", // 快照状态
"virtual_machine_id": 740 // 虚拟机Id
}
"id": 1, // 快照id
"created_at": "2025-02-19T06:45:30.442Z", // 创建时间
"updated_at": "2025-02-19T06:46:30.595Z", // 更新时间
"name": "test001", // 快照名称
"description": "", // 快照描述
"status": "active", // 快照状态
"virtual_machine_id": 740 // 虚拟机Id
}
]
},
"msg": "success"
}