跳转至

实例

创建虚拟机

接口描述

创建虚拟机。

接口路径

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"
}