实例

创建虚拟机

接口描述

创建虚拟机。

接口路径

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	否		虚拟机数据盘配置
metadata	string	否		实例metadata
userdata	Userdata	否		userdata
count	int	否	1	虚拟机数量
image_id	int	是		镜像ID
datacenter_id	int	是		数据中心ID

metadata：

创建实例时可设置一些实例的元数据，比如hostname：

// 数据要base64编码，比如把hostname设置为win10_demo1:
// metadata参数: {"hostname": "win10_demo1"}
// 需要base64编码:
{
    ...
    "metadata": "eyJob3N0bmFtZSI6ICJ3aW4xMF9kZW1vMSJ9Cg=="
}

创建实例时设置hostname有可能会在第一次开机时重启一次实例。

Userdata：

名称	类型	描述
WriteFiles	[]Fields	创建实例时可传入一些数据，写到指定的文件中

Fields：

名称	类型	描述
content	string	文件内容，需要base64编码
path	string	文件路径

userdata示例：

{
    ...
    "userdata": {
        "write_files": [
            {
                "content": "dGhpcyBpcyB0ZXN0Cg==",
                "path": "C:\path\to\file"
            },
            {
                "content": "dGhpcyBpcyB0ZXN0Cg==",
                "path": "C:\path\to\file"
            }
        ]
    }
}

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	Response	响应数据，数据结构见示例
reason	string	异常时的原因

Response

名称	类型	描述
code	int	状态码，100001表示success，其它表示异常
msg	string	状态码描述信息
data	Instance	实例信息

Instance

实例基础信息。

字段	类型	描述
id	int	实例Id
created_at	string	创建时间
updated_at	string	更新时间
uuid	string	实例uuid
name	string	实例名称
os	string	实例操作系统
state	string	实例状态
memory	int	内存（KB）
max_memory	int	最大内存（KB），当memory < max_memory时，实例可以动态增加内存
cpus	int	cpu核心数
cpu_model	string	cpu型号
server_id	int	服务器Id
image_id	int	镜像Id
is_release	bool	是否已关机并释放资源
datacenter_id	int	数据中心Id
datacenter_name	string	数据中心名称
volumes	[]Volume	磁盘列表
ip_addresses	[]Network	网络信息
port_mapping_rules	[]PortMappingRule	端口映射信息

Volume

实例磁盘信息。

字段	类型	描述
id	int	磁盘Id
created_at	string	创建时间
updated_at	string	更新时间
volume_name	string	磁盘文件名
capacity	int	磁盘大小
format	string	磁盘格式(qcow2/raw)
is_system	bool	是否是系统盘
backing_file	string	qcow2磁盘的backing file
backing_file_pool	string	qcow2磁盘的backing file所在存储池
backing_file_format	string	qcow2磁盘的backing file格式
backing_file_id	int	qcow2磁盘的backing file对应volume的id
mount_flag	string	挂载选项，参考挂载磁盘接口
storage_pool	string	存储池
storage_pool_id	int	存储池Id
virtual_machine_id	int	实例Id

Network

实例网络信息。

字段	类型	描述
id	int	id
created_at	string	创建时间
updated_at	string	更新时间
ip	string	ip地址
mac_address	string	mac地址
bridge_name	string	网桥名称
state	int	ip状态
virtual_machine_id	int	实例Id
subnet_id	int	子网Id

PortMappingRule

端口映射规则信息。

字段	类型	描述
protocol	string	协议： PORT_MAPPING_PROTOCOL_TCP PORT_MAPPING_PROTOCOL_UDP
mapped_addresses	PortMappingMappedAddress	端口映射信息

PortMappingMappedAddress

字段	类型	描述
address	string	ip地址
name	string	线路名称。通常情况下，你应该使用 attribute 属性来判断。这个字段仅在同种线路有多个地址时，用于区分不同的线路。
port_range	[a, b]	端口范围。比如： [10000, 10100]表示端口范围从10000到10100。
attribute	NetworkAddressAttribute	网络地址属性： PublicNetworkAddressAttribute PrivateNetworkAddressAttribute

PublicNetworkAddressAttribute

公网地址属性。

字段	类型	描述
preferred_providers	InternetServiceProvider	运营商

PrivateNetworkAddressAttribute

私有地址属性（暂无属性）。

InternetServiceProvider

名称	描述
ISP_CHINA_TELECOM	电信
ISP_CHINA_UNICOM	联通
ISP_CHINA_MOBILE	移动
ISP_UNKNOWN	未知运营商

返回数据示例：

{
    "code": 100001,
    "msg": "success",
    "data": {
        "id": 56,
        "created_at": "2025-06-17T14:23:44.133+08:00",
        "updated_at": "2025-06-19T16:01:02.904+08:00",
        "uuid": "ec72f485-09fa-4677-97ca-2cac88113a98",
        "name": "vm",
        "os": "windows10",
        "real_name": "ins56",
        "state": "running",
        "autostart": false,
        "memory": 8388608,
        "max_memory": 8388608,
        "cpus": 8,
        "cpu_model": "Intel(R) Xeon(R) CPU E5-2650 v3 @ 2.30GHz",
        "server_id": 3039,
        "image_id": 1,
        "datacenter_id": 43,
        "datacenter_name": "Tianjin_prod",
        "is_release": false,
        "volumes": [
            {
                "id": 213,
                "created_at": "2025-06-17T14:23:44.156+08:00",
                "updated_at": "2025-06-17T14:23:44.156+08:00",
                "volume_name": "553e1a8b74014f6d8bf490288b749300",
                "capacity": 40,
                "format": "qcow2",
                "is_system": true,
                "backing_file": "/opt/export/baseimg/win10_21h1_debug.qcow2",
                "backing_file_pool": "systems",
                "backing_file_format": "qcow2",
                "mount_flag": "persistent",
                "storage_pool": "local_system",
                "backing_file_id": 0,
                "storage_pool_id": 11,
                "virtual_machine_id": 56
            }
        ],
        "ip_addresses": [
            {
                "id": 69,
                "created_at": "2025-06-11T15:00:02.335+08:00",
                "updated_at": "2025-06-17T14:24:23.196+08:00",
                "ip": "10.100.9.100",
                "mac_address": "a8:a2:7a:af:2b:9d",
                "bridge_name": "br0",
                "state": 2,
                "virtual_machine_id": 56,
                "subnet_id": 5
            }
        ],
        "deleted_at": null,
        "port_mapping_rules": [
            {
                "protocol": "PORT_MAPPING_PROTOCOL_TCP",
                "mapped_addresses": [
                    {
                        "address": "10.100.9.100",
                        "name": "internal",
                        "port_range": [
                            10000,
                            10100
                        ],
                        "attribute": {
                            "private": {}
                        }
                    },
                    {
                        "address": "1.1.1.1",
                        "name": "public",
                        "port_range": [
                            20000,
                            20100
                        ],
                        "attribute": {
                            "public": {
                                "preferred_providers": [
                                    "ISP_CHINA_MOBILE"
                                ]
                            }
                        }
                    },
                    {
                        "address": "2.2.2.2",
                        "name": "public",
                        "port_range": [
                            20000,
                            20100
                        ],
                        "attribute": {
                            "public": {
                                "preferred_providers": [
                                    "ISP_CHINA_TELECOM"
                                ]
                            }
                        }
                    },
                    {
                        "address": "3.3.3.3",
                        "name": "public",
                        "port_range": [
                            20000,
                            20100
                        ],
                        "attribute": {
                            "public": {
                                "preferred_providers": [
                                    "ISP_CHINA_UNICOM"
                                ]
                            }
                        }
                    }
                ]
            },
            {
                "protocol": "PORT_MAPPING_PROTOCOL_UDP",
                "mapped_addresses": [
                    {
                        "address": "10.100.9.100",
                        "name": "internal",
                        "port_range": [
                            10000,
                            10100
                        ],
                        "attribute": {
                            "private": {}
                        }
                    },
                    {
                        "address": "3.3.3.3",
                        "name": "public",
                        "port_range": [
                            20000,
                            20100
                        ],
                        "attribute": {
                            "public": {
                                "preferred_providers": [
                                    "ISP_CHINA_UNICOM"
                                ]
                            }
                        }
                    },
                    {
                        "address": "1.1.1.1",
                        "name": "public",
                        "port_range": [
                            20000,
                            20100
                        ],
                        "attribute": {
                            "public": {
                                "preferred_providers": [
                                    "ISP_CHINA_MOBILE"
                                ]
                            }
                        }
                    },
                    {
                        "address": "2.2.2.2",
                        "name": "public",
                        "port_range": [
                            20000,
                            20100
                        ],
                        "attribute": {
                            "public": {
                                "preferred_providers": [
                                    "ISP_CHINA_TELECOM"
                                ]
                            }
                        }
                    }
                ]
            }
        ]
    }
}

虚拟机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	ListResponse	响应数据，数据结构见示例
reason	string	异常时的原因

ListResponse

字段	类型	描述
count	int	实例总数
items	[]Instance	实例列表

返回数据示例：

{
    "code": 100001,
    "msg": "success",
    "data": {
        "count": 2,
        "items": [
            {
                "id": 39,
                "created_at": "2025-06-03T16:23:12.259+08:00",
                "updated_at": "2025-06-19T16:01:02.896+08:00",
                "uuid": "8f18b96a-95bc-4b71-99df-c52d854c7912",
                "name": "vm",
                "os": "",
                "real_name": "ins39",
                "state": "running",
                "autostart": false,
                "memory": 8388608,
                "max_memory": 8388608,
                "cpus": 8,
                "cpu_model": "Intel(R) Xeon(R) CPU E5-2650 v3 @ 2.30GHz",
                "server_id": 3039,
                "datacenter_id": 43,
                "datacenter_name": "Tianjin1_prod",
                "is_vgpu": false,
                "is_release": false,
                "volumes": [
                    {
                        "id": 183,
                        "created_at": "2025-06-03T16:23:12.281+08:00",
                        "updated_at": "2025-06-03T17:47:34.268+08:00",
                        "volume_name": "04c1ba464dd446d4b45504a3cc4242ea",
                        "capacity": 40,
                        "format": "qcow2",
                        "is_system": true,
                        "backing_file": "win10_21h1_debug.qcow2",
                        "backing_file_pool": "baseimg",
                        "backing_file_format": "qcow2",
                        "mount_flag": "persistent",
                        "storage_pool": "local_system",
                        "backing_file_id": 0,
                        "storage_pool_id": 11,
                        "virtual_machine_id": 39
                    }
                ],
                "ip_addresses": [
                    {
                        "id": 67,
                        "created_at": "2025-06-03T16:23:12.285+08:00",
                        "updated_at": "2025-06-03T16:24:22.326+08:00",
                        "ip": "192.168.122.57",
                        "mac_address": "a8:53:77:ee:88:8f",
                        "bridge_name": "default",
                        "state": 2,
                        "static": false,
                        "virtual_machine_id": 39,
                        "subnet_id": 0
                    }
                ],
                "deleted_at": null
            },
            {
                "id": 56,
                "created_at": "2025-06-17T14:23:44.133+08:00",
                "updated_at": "2025-06-19T16:01:02.904+08:00",
                "uuid": "ec72f485-09fa-4677-97ca-2cac88113a98",
                "name": "vm",
                "os": "",
                "real_name": "ins56",
                "state": "running",
                "autostart": false,
                "memory": 8388608,
                "max_memory": 8388608,
                "cpus": 8,
                "cpu_model": "Intel(R) Xeon(R) CPU E5-2650 v3 @ 2.30GHz",
                "server_id": 3039,
                "datacenter_id": 43,
                "datacenter_name": "Tianjin1_prod",
                "is_vgpu": false,
                "is_release": false,
                "volumes": [
                    {
                        "id": 213,
                        "created_at": "2025-06-17T14:23:44.156+08:00",
                        "updated_at": "2025-06-17T14:23:44.156+08:00",
                        "volume_name": "553e1a8b74014f6d8bf490288b749300",
                        "capacity": 40,
                        "format": "qcow2",
                        "is_system": true,
                        "backing_file": "/opt/export/baseimg/win10_21h1_debug.qcow2",
                        "backing_file_pool": "systems",
                        "backing_file_format": "qcow2",
                        "mount_flag": "persistent",
                        "storage_pool": "local_system",
                        "backing_file_id": 0,
                        "storage_pool_id": 11,
                        "virtual_machine_id": 56
                    }
                ],
                "ip_addresses": [
                    {
                        "id": 69,
                        "created_at": "2025-06-11T15:00:02.335+08:00",
                        "updated_at": "2025-06-17T14:24:23.196+08:00",
                        "ip": "10.100.9.100",
                        "mac_address": "a8:a2:7a:af:2b:9d",
                        "bridge_name": "br0",
                        "state": 2,
                        "static": true,
                        "virtual_machine_id": 56,
                        "subnet_id": 5
                    }
                ],
                "deleted_at": null,
                "port_mapping_rules": [
                    {
                        "protocol": "PORT_MAPPING_PROTOCOL_TCP",
                        "mapped_addresses": [
                            {
                                "address": "10.100.9.100",
                                "name": "internal",
                                "port_range": [
                                    10100,
                                    10200
                                ],
                                "attribute": {
                                    "private": {}
                                }
                            },
                            {
                                "address": "1.1.1.1",
                                "name": "public",
                                "port_range": [
                                    10100,
                                    10200
                                ],
                                "attribute": {
                                    "public": {
                                        "preferred_providers": [
                                            "ISP_CHINA_MOBILE"
                                        ]
                                    }
                                }
                            },
                            {
                                "address": "2.2.2.2",
                                "name": "public",
                                "port_range": [
                                    10100,
                                    10200
                                ],
                                "attribute": {
                                    "public": {
                                        "preferred_providers": [
                                            "ISP_CHINA_TELECOM"
                                        ]
                                    }
                                }
                            },
                            {
                                "address": "3.3.3.3",
                                "name": "public",
                                "port_range": [
                                    10100,
                                    10200
                                ],
                                "attribute": {
                                    "public": {
                                        "preferred_providers": [
                                            "ISP_CHINA_UNICOM"
                                        ]
                                    }
                                }
                            }
                        ]
                    },
                    {
                        "protocol": "PORT_MAPPING_PROTOCOL_UDP",
                        "mapped_addresses": [
                            {
                                "address": "10.100.9.100",
                                "name": "internal",
                                "port_range": [
                                    10100,
                                    10200
                                ],
                                "attribute": {
                                    "private": {}
                                }
                            },
                            {
                                "address": "3.3.3.3",
                                "name": "public",
                                "port_range": [
                                    10100,
                                    10200
                                ],
                                "attribute": {
                                    "public": {
                                        "preferred_providers": [
                                            "ISP_CHINA_UNICOM"
                                        ]
                                    }
                                }
                            },
                            {
                                "address": "1.1.1.1",
                                "name": "public",
                                "port_range": [
                                    10100,
                                    10200
                                ],
                                "attribute": {
                                    "public": {
                                        "preferred_providers": [
                                            "ISP_CHINA_MOBILE"
                                        ]
                                    }
                                }
                            },
                            {
                                "address": "2.2.2.2",
                                "name": "public",
                                "port_range": [
                                    10100,
                                    10200
                                ],
                                "attribute": {
                                    "public": {
                                        "preferred_providers": [
                                            "ISP_CHINA_TELECOM"
                                        ]
                                    }
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

挂载磁盘

接口描述

挂载磁盘到虚拟机。

接口路径

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

接口参数

路径参数

参数名称	类型	是否必须	默认值	备注
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"
}