VM

2.8.1 Add VM

API endpoint

POST  /NSphere/api/vm-resource/add

API description

Add a VM. hostId and clusterId must not both be empty and must not both be provided. Compute virtualization environments do not support creating Ultra-mode VMs. When adding a VM under a cluster, a compute virtualization environment supports only new files, and a hyperconverged environment supports only new files.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"hostId": 1,
"clusterId": null,
"hostPoolId": 1,
"title": "",
"description": null,
"isStart": 1,
"system": 1,
"osVersion": "CentOS 8(64-bit)",
"autoMigrate": 1,
"autoTools": true,
"vmPriority": 2,
"cpu": 2,
"cpuSocket": 2,
"cpuCore": 1,
"maxCpuSocket": null,
"cpuShares": 512,
"blkiotune": 200,
"cpuMode": "custom",
"cpuModel": 10,
"osBit": "x86_64",
"cpuGurantee": 0,
"cpuQuota": null,
"cpuQuotaUnit": "MHz",
"cpuExclusive": "disable",
"numaBalance": "disable",
"memory": 4096,
"memoryLocked": 0,
"memoryPriority": 0,
"maxMemory": null,
"memoryLimit": null,
"memoryLimitUnit": "GB",
"autoMem": 0,
"watchdogAction": null,
"vtpmVersion": null,
"networks": [
{
"hotPluggable": true,
"mac": null,
"queues": 1,
"queueSize": 1024,
"ipAddr": null,
"ipv6IpAddr": null,
"name": null,
"mode": "veb",
"dpdk": false,
"vswitchId": null,
"tcpCheckSum": true,
"deviceModel": "virtio",
"driver": "vhost",
"mtu": 1500,
"inAvgBandwidth": 100,
"inBurst": 100,
"outAvgBandwidth": 100,
"outBurst": 100,
"inbound": false,
"outbound": false,
"profileId": 1,
"profileName": "Default",
"vlanType": 0,
"driverType": null,
"networkPortGroupId": 1,
"networkPortGroupName": null,
"resPoolId": null,
"securityGroupId": "1,-1",
"vlanTrunkId": 1,
"pvlanRuleId": null
}
],
"storages": [
{
"diskDevice": "disk",
"driveType": "qcow2",
"storeFile": null,
"capacity": 81920,
"targetBus": "virtio",
"type": "file",
"cacheType": "none",
"cacheFile": null,
"secretUuid": null,
"poolName": "isopool",
"hotPluggable": true,
"mode": 2,
"unmap": false,
"encryptPw": null,
"naa": null,
"serial": null,
"clustersize": null,
"diskMode": "subordinate",
"algorithm": null,
"diskIOMode": "native",
"backupBlock": null,
"kmsClusterId": null,
"kmsKeyName": null,
"encryptionType": null
}
],
"devList": [
{
"devType": 0,
"devName": "",
"vendorId": 1,
"productId": 1,
"controller": null,
"deviceDriver": "vfio",
"shared": true,
"count": null,
"gpuType": null
}
],
"bindPcpu": [
{
"id": 0,
"devId": null
}
],
"netusbList": [
{
"hostIp": "",
"usbredirPort": null,
"bus": "",
"dev": null,
"port": null,
"path": "",
"idvendor": "",
"manufacturer": "",
"idproduct": "",
"product": "",
"controller": ""
}
],
"hugepage": false,
"domainCpuGlobalQuota": false,
"encryptCardAddress": [],
"enableUltra": null,
"vmView": {
"dirId": 0,
"dirName": ""
},
"enableReduceCPU": true,
"enableIncreaseCPU": true,
"enableMultiQueue": true
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainAddDTO	Add-VM request entity	body	true	ApiDomainAddDTO	ApiDomainAddDTO
hostId	VM host ID		false	integer(int64)
clusterId	VM cluster ID.		false	integer(int64)
hostPoolId	VM data center ID.		true	integer(int64)
title	VM display name		true	string
description	VM description. Maximum length 2048 characters.		false	string
isStart	Whether to start the VM. 1: start, 0: do not start.		true	integer(int32)
system	Guest operating system installed on the VM. 0: Windows, 1: Linux, 2: BSD.		true	integer(int32)
osVersion	Guest operating system version. Allowed values: Microsoft Windows Server 2025(64-bit),Microsoft Windows Server 2022(64-bit),Microsoft Windows Server 2019(64-bit),Microsoft Windows Server 2016(64-bit),Microsoft Windows Server 2012 R2,Microsoft Windows Server 2012,Microsoft Windows Server 2008 R2(64-bit),Microsoft Windows Server 2008(64-bit),Microsoft Windows Server 2008(32-bit),Microsoft Windows Server 2003 R2(64-bit),Microsoft Windows Server 2003 R2(32-bit),Microsoft Windows Server 2003(64-bit),Microsoft Windows Server 2003(32-bit),Microsoft Windows 11(64-bit),Microsoft Windows 10(64-bit),Microsoft Windows 10(32-bit),Microsoft Windows 8.1(64-bit),Microsoft Windows 8.1(32-bit),Microsoft Windows 8(64-bit),Microsoft Windows 8(32-bit),Microsoft Windows 7(64-bit),Microsoft Windows 7(32-bit),Microsoft Windows XP Professional(32-bit),Other Windows (64-bit),Other Windows (32-bit),zhongbiaoV7OS64,zhongbiaoV6OS64,zhongbiaoV6OS32,zhongbiaoV5OS32,zhongbiaoSystemV6OS64,neoShineDeskV4OS32,neoShineServerV4OS64,neoShineServerV3OS64,huawei29,huawei20sp264,huawei20sp164,zhongxinV4OS64,zhongxinV3OS64,yiminServerV764,yiminServersV464,yiminServersOS64,yiminServersOS32,cvmNsphereOS64,linxTechV8064,linxTechV6064,linxTechV4264,Alibaba Cloud Linux 2,Alibaba Cloud Linux 3,kylin (64-bit),kylinV10 (64-bit),kylinV10Desk (64-bit),UOS 20 SP1Desk(64-bit),UOS SP2(64-bit),UOS Server 20 1020e(64-bit),UOS Server 20 1060e(64-bit),BCLinux(64-bit),Red Hat Enterprise Linux 10(64-bit),Red Hat Enterprise Linux 9(64-bit),Red Hat Enterprise Linux 9(32-bit),Red Hat Enterprise Linux 8(64-bit),Red Hat Enterprise Linux 8(32-bit),Red Hat Enterprise Linux 7(64-bit),Red Hat Enterprise Linux 7(32-bit),Red Hat Enterprise Linux 6(64-bit),Red Hat Enterprise Linux 6(32-bit),Red Hat Enterprise Linux 5.10(64-bit),Red Hat Enterprise Linux 5.10(32-bit),Red Hat Enterprise Linux 5.9(64-bit),Red Hat Enterprise Linux 5.9(32-bit),Red Hat Enterprise Linux 5.8(64-bit),Red Hat Enterprise Linux 5.8(32-bit),Red Hat Enterprise Linux 5.7(64-bit),Red Hat Enterprise Linux 5.7(32-bit),Red Hat Enterprise Linux 5.6(64-bit),Red Hat Enterprise Linux 5.6(32-bit),Red Hat Enterprise Linux 5.5(64-bit),Red Hat Enterprise Linux 5.5(32-bit),Red Hat Enterprise Linux 5.4(64-bit),Red Hat Enterprise Linux 5.4(32-bit),Red Hat Enterprise Linux 5.3(64-bit),Red Hat Enterprise Linux 5.3(32-bit),Red Hat Enterprise Linux 5.2(64-bit),Red Hat Enterprise Linux 5.2(32-bit),Red Hat Enterprise Linux 5.1(64-bit),Red Hat Enterprise Linux 5.1(32-bit),Red Hat Enterprise Linux 5.0(64-bit),Red Hat Enterprise Linux 5.0(32-bit),Red Hat Enterprise Linux 4(64-bit),Red Hat Enterprise Linux 4(32-bit),Novell SUSE Linux Enterprise 15(64-bit),Novell SUSE Linux Enterprise 12(64-bit),Novell SUSE Linux Enterprise 11(64-bit),Novell SUSE Linux Enterprise 11(32-bit),Novell SUSE Linux Enterprise 10(64-bit),Novell SUSE Linux Enterprise 10(32-bit),Novell SUSE Linux Enterprise 8/9(64-bit),Novell SUSE Linux Enterprise 8/9(32-bit),SUSE openSUSE(64-bit),SUSE openSUSE(32-bit),CentOS 10(64-bit),CentOS 10(32-bit),CentOS 9(64-bit),CentOS 9(32-bit),CentOS 8(64-bit),CentOS 8(32-bit),CentOS 6/7(64-bit),CentOS 6/7(32-bit),CentOS 5.10(64-bit),CentOS 5.10(32-bit),CentOS 5.9(64-bit),CentOS 5.9(32-bit),CentOS 5.8(64-bit),CentOS 5.8(32-bit),CentOS 5.7(64-bit),CentOS 5.7(32-bit),CentOS 5.6(64-bit),CentOS 5.6(32-bit),CentOS 5.5(64-bit),CentOS 5.5(32-bit),CentOS 5.4(64-bit),CentOS 5.4(32-bit),CentOS 5.3(64-bit),CentOS 5.3(32-bit),CentOS 5.2(64-bit),CentOS 5.2(32-bit),CentOS 5.1(64-bit),CentOS 5.1(32-bit),CentOS 5.0(64-bit),CentOS 5.0(32-bit),CentOS 4(64-bit),CentOS 4(32-bit),Debian GUN/Linux 13(64-bit),Debian GUN/Linux 12(64-bit),Debian GUN/Linux 11(64-bit),Debian GUN/Linux 10(64-bit),Debian GUN/Linux 9(64-bit),Debian GUN/Linux 8(64-bit),Debian GUN/Linux 8(32-bit),Debian GUN/Linux 7(64-bit),Debian GUN/Linux 7(32-bit),Debian GUN/Linux 6(64-bit),Debian GUN/Linux 6(32-bit),Debian GUN/Linux 5(64-bit),Debian GUN/Linux 5(32-bit),Debian GUN/Linux 4(64-bit),Debian GUN/Linux 4(32-bit),Asianux 4(64-bit),Asianux 4(32-bit),Asianux 3(64-bit),Asianux 3(32-bit),Deepin 23(64-bit),Deepin 15(64-bit),Deepin 15(32-bit),Oracle Linux 10(64-bit),Oracle Linux 9(64-bit),Oracle Linux 9(32-bit),Oracle Linux 8(64-bit),Oracle Linux 7(64-bit),Oracle Linux 7(32-bit),Oracle Linux 6.8(64-bit),Oracle Linux 6.8(32-bit),Oracle Linux 6.7(64-bit),Oracle Linux 6.7(32-bit),Oracle Linux 6.6(64-bit),Oracle Linux 6.6(32-bit),Oracle Linux 6.5(64-bit),Oracle Linux 6.5(32-bit),Oracle Linux 6.4(64-bit),Oracle Linux 6.4(32-bit),Oracle Linux 6.3(64-bit),Oracle Linux 6.3(32-bit),Oracle Linux 6.2(64-bit),Oracle Linux 6.2(32-bit),Oracle Linux 6.1(64-bit),Oracle Linux 6.1(32-bit),Oracle Linux 6.0(64-bit),Oracle Linux 6.0(32-bit),Oracle Linux 4/5(64-bit),Oracle Linux 4/5(32-bit),Ubuntu Linux(64-bit),Ubuntu Linux(32-bit),Fedora 25(64-bit),Fedora 24(64-bit),Fedora 23(64-bit),Fedora 22(64-bit),Fedora 21(64-bit),Fedora 20(64-bit),Fedora 17(64-bit),Fedora 15(64-bit),Fedora 12(32-bit),Fedora 11(64-bit),Fedora 10(32-bit),Fedora 9(32-bit),Fedora 8(32-bit),Red Flag Asianux Server 7(64-bit),Red Flag Asianux Server 4.5(64-bit),Red Flag Asianux Server 4(64-bit),Red Flag Asianux Server 4(32-bit),Red Flag Asianux Server 3(64-bit),Red Flag Asianux Server 3(32-bit),Red Flag Asianux Server 2(64-bit),Red Flag Asianux Server 2(32-bit),Anolis OS 23.1,Anolis OS 8.8,Anolis OS 8.6,Anolis OS 8.4,Anolis OS 7,AnolisOS 23(64-bit),NFS OS,Edubuntu,Zorin OS,Astra Linux,Scientific Linux,Elementary OS,Slackware Linux,Linux Mint,Mageia,Manjaro,StartOS,greenSpace,GreatTurbo,Solaries,Rocky,Rocky 9(64-bit),Kali,TrueOS,TencentOS,AlmaLinux 9,openEuler 23,openEuler 24,openEuler 25,Other Linux(64-bit),Other Linux(32-bit),FreeBSD 12.0(64-bit),FreeBSD 11.1(64-bit),FreeBSD 11.1(32-bit),FreeBSD 11.0(64-bit),FreeBSD 11.0(32-bit),FreeBSD 10.3(64-bit),FreeBSD 10.3(32-bit),FreeBSD 10.2(64-bit),FreeBSD 10.2(32-bit),FreeBSD 10.1(64-bit),FreeBSD 10.1(32-bit),otherBSD(64-bit),otherBSD(32-bit)		true	string
autoMigrate	Whether the VM allows auto-migration. 0: no, 1: yes.		true	integer(int32)
autoTools	Whether NSpheretools auto-upgrades		true	boolean
vmPriority	VM business priority. 1: low, 2: medium, 4: high.		true	integer(int32)
cpu	VM vCPU count		true	integer(int32)
cpuSocket	VM CPU socket count		true	integer(int32)
cpuCore	VM CPU cores per socket		true	integer(int32)
maxCpuSocket	Host CPU core count. Do not provide a value.		false	integer(int32)
cpuShares	VM CPU scheduling priority. High = 1024, Medium = 512, Low = 256.		true	integer(int32)
blkiotune	VM I/O weight. 200: low, 300: medium, 500: high.		true	integer(int32)
cpuMode	CPU working mode. custom: compatible mode; host-model: host-match mode; host-passthrough: passthrough mode; emc: EMC mode.		true	string
cpuModel	CPU model. 10: Intel@ Merom Generation, 20: Intel@ Penryn Generation, 30: Intel@ Nehalem Generation, 40: Intel@ Westmere Generation, 50: Intel@ SandyBridge Generation, 60: Intel@ IvyBridge Generation, 70: Intel@ Haswell Generation, 80: Intel@ Broadwell Generation, 90: Intel@ Skylake-Client Generation, 100: Intel@ Skylake-Server Generation, 110: Intel@ Cascadelake-Server Generation, 120: Intel@ Icelake-Client Generation, 130: Intel@ Icelake-Server Generation, 10010: AMD Opteron Generation 1, 10020: AMD Opteron Generation 2, 10030: AMD phenom Generation, 10040: AMD Opteron Generation 3, 10050: AMD Opteron Generation 4, 10060: AMD Opteron Generation 5, 10070: AMD EPYC Generation.		false	integer(int32)
osBit	VM architecture bits. Allowed values: x86_64, i686, or arch64.		true	string
cpuGurantee	CPU reservation (MHz)		true	integer(int64)
cpuQuota	CPU limit		false	number(double)
cpuQuotaUnit	CPU limit unit (MHz or GHz)		false	string
cpuExclusive	VM CPU exclusive. numa: enabled, disable: off.		true	string
numaBalance	VM NUMA smart scheduling. enable: on, disable: off.		true	string
memory	VM memory, in MB.		true	integer(int64)
memoryLocked	Memory reservation percentage. 0-100.		true	integer(int32)
memoryPriority	Memory resource priority. 0: low, 50: medium, 100: high.		true	integer(int32)
maxMemory	Host memory (GB). Do not provide a value.		false	integer(int64)
memoryLimit	Memory limit		false	number(double)
memoryLimitUnit	Memory limit unit (GB|MB).		false	string
autoMem	Whether memory overcommit is enabled. 0: off, 1: on.		true	integer(int32)
watchdogAction	VM watchdog action (reset|poweroff|migrate)		false	string
vtpmVersion	vTPM device (1.2|2.0)		false	string
networks	VM network configuration entity		true	array	ApiDomainAddNetworkDTO
hotPluggable	Whether hot-plug is supported		true	boolean
mac	vNIC MAC address		false	string
queues	Multi-queue. Must be >= 1 and less than (vCPU count x cores). Required when kernel acceleration is enabled; optional otherwise.		false	integer(int32)
queueSize	Queue depth. Low: 256; High: 1024.		true	integer(int32)
ipAddr	Bound IP		false	string
ipv6IpAddr	Bound IPv6		false	string
name	vSwitch name		false	string
mode	VM vNIC forwarding mode. Allowed values: dvs (corresponds to vSwitch forwarding mode VXLAN (SDN)), veb.		true	string
dpdk	Whether DPDK		true	boolean
vswitchId	vSwitch ID		false	integer(int64)
tcpCheckSum	Whether TCP checksum is enabled. Required when kernel acceleration is enabled; optional otherwise.		false	boolean
deviceModel	Driver model. rtl8139 (standard vNIC), virtio (high-speed vNIC), e1000 (Intel e1000), SR_IOV (SR-IOV passthrough), smart (smart vNIC). When SR_IOV is used, resPoolId is required.		true	string
driver	Whether kernel acceleration is enabled. Value is vhost when VM network kernel acceleration is enabled.		false	string
mtu	MTU value. Required. Range: 1000-9000.		true	integer(int64)
inAvgBandwidth	Inbound average bandwidth, in Kbps. Range: 8-34359743 Kbps. Required when inbound is true.		false	integer(int64)
inBurst	Inbound burst buffer size, in KBytes. Range: 1-4194303 KBytes. Required when inbound is true.		false	integer(int64)
outAvgBandwidth	Outbound average bandwidth, in Kbps. Range: 8-34359743 Kbps. Required when outbound is true.		false	integer(int64)
outBurst	Outbound burst buffer size, in KBytes. Range: 1-4194303 KBytes. Required when outbound is true.		false	integer(int64)
inbound	Whether inbound traffic limit is enabled		false	boolean
outbound	Whether outbound traffic limit is enabled		false	boolean
profileId	Network policy template ID. If both profileId and profileName are provided, profileId takes precedence.		false	integer(int64)
profileName	Network policy template name. If both profileId and profileName are provided, profileId takes precedence; profileId alone is sufficient.		false	string
vlanType	Whether the network policy template is of VLAN type. 0: no, 1: yes.		false	integer(int32)
driverType	SR-IOV driver type. When the network type is SR-IOV, the driver type is vfio.		false	string
networkPortGroupId	Port group ID. When adding a VM via a port group, vswitchId, profileId, profileName, securityGroupId, and vlanTrunkId can be omitted; if all are provided, the port group takes precedence.		false	integer(int64)
networkPortGroupName	Port group name		false	string
resPoolId	SR-IOV resource pool ID.		false	integer(int64)
securityGroupId	Virtual firewall. Composed of firewall ID plus action. Action must be 0 or -1: 0 = whitelist, -1 = blacklist.		false	string
vlanTrunkId	VLAN policy ID		false	string
pvlanRuleId	PVLAN rule ID		false	integer(int64)
storages	VM storage configuration entity		true	array	ApiDomainAddStorageDTO
diskDevice	Storage device type. Must be disk, cdrom, or floppy.		true	string
driveType	Storage driver type. When the storage volume type is file, the disk driver type must be raw (high-speed), luks (encrypted), or qcow2 (smart). When the storage volume type is network or ubd, the driver type must be raw. When the storage volume type is block, do not provide a value. CD-ROM driver type must be imgFileName (image), nspheretools (install NSpheretools), or host_cdrom (CD/DVD). Floppy driver type must be autoVirtio or file.		false	string
storeFile	Storage file		false	string
capacity	Storage capacity (MB)		false	integer(int64)
targetBus	Disk bus type. ide: IDE disk; usb: USB disk; virtio: high-speed disk; virtioScsi: high-speed SCSI disk.		false	string
type	Storage volume type. file: file; block: block device; ultra: ubd. When the storage type is network, disk encryption is not supported, cache mode supports only none|directsync, ultra mode is not supported, existing files are not supported; driveType must be raw, mode must be 2, clustersize must be 262144, diskIOMode must be null, diskMode must be subordinate, and priority must be 2.		false	string
cacheType	Disk cache mode. none: L1 virtual cache; writeback: L2 virtual cache; writethrough: L1 physical cache; directsync: direct I/O.		false	string
cacheFile	Cache file path		false	string
secretUuid	Disk encryption UUID		false	string
poolName	Storage pool name		false	string
hotPluggable	Whether hot-plug is supported. Only high-speed disks support this parameter.		false	boolean
mode	Disk pre-allocation mode. 0: lazy zeroed, 1: zeroed, 2: thin.		false	integer(int32)
unmap	Whether space reclaim is enabled. Only takes effect for thin-provisioned high-speed iSCSI disks.		false	boolean
encryptPw	Disk encryption key		false	string
naa	Disk NAA		false	string
serial	Serial number		false	string
clustersize	Cluster size. Allowed: 65536|131072|262144|524288|1048576|2097152. Unit: bytes. Encrypted disks cannot set this field.		false	string
diskMode	Disk mode. subordinate: dependent; independent-persistent: independent-persistent.		false	string
algorithm	Disk encryption algorithm (sm4|aes)		false	string
diskIOMode	Disk I/O mode (native; threads). When cacheType is writethrough or writeback, diskIOMode must be threads. Passing null means no change.		false	string
backupBlock	CBT backup block-device binding. Used for VM external-snapshot CBT backup. Supported only on FC network storage or on iSCSI network storage whose storage-pool path is prefixed with "/dev/disk/by-id/".		false	string
kmsClusterId	KMS server ID		false	integer(int64)
kmsKeyName	KMS key name		false	string
encryptionType	Encryption mode. 0: local encryption, 1: KMS-server encryption.		false	integer(int32)
devList	VM device configuration entity		false	array	ApiDomainAddDevDTO
devType	Device type. 0: USB, 1: PCI, 2: GPU/VGPU. When device type is 2, gpuType, vendorId, productId, deviceDriver, shared, and count are required.		true	integer(int32)
devName	Device name. When device type is 2, provide the smart resource pool name.		true	string
vendorId	Vendor ID		false	string
productId	Business template. 1: non-linear editing, 2: transcoding & compositing.		false	string
controller	Connection mode. Required for USB devices. 1: USB 1.0, 2: USB 2.0, 3: USB 3.0.		false	string
deviceDriver	Device type.		false	string
shared	Whether shared		false	boolean
count	Count		false	integer(int32)
gpuType	GPU resource type. 1: GPU, 2: vGPU.		false	string
bindPcpu	VM view entity		false	array	ApiDomainAddBindCpuDTO
id	VM CPU ID		true	integer(int64)
devId	Device ID		false	string
netusbList	VM network USB configuration entity		false	array	ApiDomainAddNetUsbDTO
hostIp	Host IP		true	string
usbredirPort	USB redirection port		false	integer(int32)
bus	USB bus		true	string
dev	USB device		false	integer(int32)
port	USB port		false	integer(int32)
path	USB path		true	string
idvendor	Vendor ID		true	string
manufacturer	Vendor		true	string
idproduct	Product ID		true	string
product	Product name		true	string
controller	USB controller		true	string
hugepage	Whether huge pages are enabled		false	boolean
domainCpuGlobalQuota	Whole-VM limit		false	boolean
encryptCardAddress	Encryption card address		false	array	string
enableUltra	Whether Ultra mode is enabled on the VM. 1: enabled; 0 or empty: disabled. Ultra VMs do not support the storage serial or clustersize parameters; targetBus must be virtio, driveType must be raw, and numaBalance cannot be enabled.		false	integer(int32)
vmView	VM view entity		false	ApiDomainAddVmViewDTO	ApiDomainAddVmViewDTO
dirId	VM group ID		true	integer(int64)
dirName	VM group name		true	string
enableReduceCPU	Online shrink. Requires VM hardware version 2.7 or later. Default false.		false	boolean
enableIncreaseCPU	Online increase.		false	boolean
enableMultiQueue	Multi-queue acceleration		false	boolean

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.2 Add VM disk

API endpoint

PUT  /NSphere/api/vm-resource/attach-disk

API description

Add-VM-disk task. On success, returns the task ID. New API added in E0930.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"diskDevice": "disk",
"driveType": "qcow2",
"storeFile": null,
"capacity": 81920,
"targetBus": "virtio",
"type": "file",
"cacheType": "none",
"cacheFile": null,
"secretUuid": null,
"poolName": "isopool",
"hotPluggable": true,
"mode": 2,
"unmap": false,
"encryptPw": null,
"naa": null,
"serial": null,
"clustersize": null,
"diskMode": "subordinate",
"algorithm": null,
"diskIOMode": "native",
"backupBlock": null,
"kmsClusterId": null,
"kmsKeyName": null,
"encryptionType": null,
"vmId": 1,
"readBytesSec": null,
"readIopsSec": null,
"writeBytesSec": null,
"writeIopsSec": null,
"pathType": 2
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainAddDiskDTO	VM storage configuration entity	body	true	ApiDomainAddDiskDTO	ApiDomainAddDiskDTO
diskDevice	Storage device type. Must be disk, cdrom, or floppy.		true	string
driveType	Storage driver type. When the storage volume type is file, the disk driver type must be raw (high-speed), luks (encrypted), or qcow2 (smart). When the storage volume type is network or ubd, the driver type must be raw. When the storage volume type is block, do not provide a value. CD-ROM driver type must be imgFileName (image), nspheretools (install NSpheretools), or host_cdrom (CD/DVD). Floppy driver type must be autoVirtio or file.		false	string
storeFile	Storage file		false	string
capacity	Storage capacity (MB)		false	integer(int64)
targetBus	Disk bus type. ide: IDE disk; usb: USB disk; virtio: high-speed disk; virtioScsi: high-speed SCSI disk.		false	string
type	Storage volume type. file: file; block: block device; ultra: ubd. When the storage type is network, disk encryption is not supported, cache mode supports only none|directsync, ultra mode is not supported, existing files are not supported; driveType must be raw, mode must be 2, clustersize must be 262144, diskIOMode must be null, diskMode must be subordinate, and priority must be 2.		false	string
cacheType	Disk cache mode. none: L1 virtual cache; writeback: L2 virtual cache; writethrough: L1 physical cache; directsync: direct I/O.		false	string
cacheFile	Cache file path		false	string
secretUuid	Disk encryption UUID		false	string
poolName	Storage pool name		false	string
hotPluggable	Whether hot-plug is supported. Only high-speed disks support this parameter.		false	boolean
mode	Disk pre-allocation mode. 0: lazy zeroed, 1: zeroed, 2: thin.		false	integer(int32)
unmap	Whether space reclaim is enabled. Only takes effect for thin-provisioned high-speed iSCSI disks.		false	boolean
encryptPw	Disk encryption key		false	string
naa	Disk NAA		false	string
serial	Serial number		false	string
clustersize	Cluster size. Allowed: 65536|131072|262144|524288|1048576|2097152. Unit: bytes. Encrypted disks cannot set this field.		false	string
diskMode	Disk mode. subordinate: dependent; independent-persistent: independent-persistent.		false	string
algorithm	Disk encryption algorithm (sm4|aes)		false	string
diskIOMode	Disk I/O mode (native; threads). When cacheType is writethrough or writeback, diskIOMode must be threads. Passing null means no change.		false	string
backupBlock	CBT backup block-device binding. Used for VM external-snapshot CBT backup. Supported only on FC network storage or on iSCSI network storage whose storage-pool path is prefixed with "/dev/disk/by-id/".		false	string
kmsClusterId	KMS server ID		false	integer(int64)
kmsKeyName	KMS key name		false	string
encryptionType	Encryption mode. 0: local encryption, 1: KMS-server encryption.		false	integer(int32)
vmId	VM ID		true	integer(int64)
readBytesSec	Read bandwidth limit (KB/s)		false	integer(int64)
readIopsSec	Read IOPS limit		false	integer(int64)
writeBytesSec	Write bandwidth limit (KB/s)		false	integer(int64)
writeIopsSec	Write IOPS limit		false	integer(int64)
pathType	Disk creation type. 0: existing file, 1: existing block, 2: new file, 3: new block.		false	integer(int32)

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.3 Add VM network

API endpoint

PUT  /NSphere/api/vm-resource/attach-network

API description

Add-VM-network task. On success, returns the task ID. Advanced networks, passthrough vNICs, and VXLAN vSwitches are not supported. New API added in E0930.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"hotPluggable": true,
"mac": "0c:da:41:1d:ef:ef",
"queues": 1,
"queueSize": 1024,
"ipAddr": null,
"ipv6IpAddr": null,
"name": null,
"mode": "veb",
"dpdk": false,
"vswitchId": null,
"tcpCheckSum": true,
"deviceModel": "virtio",
"driver": "vhost",
"mtu": 1500,
"inAvgBandwidth": 100,
"inBurst": 100,
"outAvgBandwidth": 100,
"outBurst": 100,
"inbound": false,
"outbound": false,
"profileId": 1,
"profileName": "Default",
"vlanType": 0,
"driverType": null,
"networkPortGroupId": 1,
"networkPortGroupName": null,
"resPoolId": null,
"securityGroupId": "1,-1",
"vlanTrunkId": 1,
"pvlanRuleId": null,
"vmId": 1
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainAddNetDTO	VM network configuration entity	body	true	ApiDomainAddNetDTO	ApiDomainAddNetDTO
hotPluggable	Whether hot-plug is supported		true	boolean
mac	vNIC MAC address		false	string
queues	Multi-queue. Must be >= 1 and less than (vCPU count x cores). Required when kernel acceleration is enabled; optional otherwise.		false	integer(int32)
queueSize	Queue depth. Low: 256; High: 1024.		true	integer(int32)
ipAddr	Bound IP		false	string
ipv6IpAddr	Bound IPv6		false	string
name	vSwitch name. Not required when a port group is used. When passed together with vswitchId, vswitchId takes precedence.		false	string
mode	VM vNIC forwarding mode. Allowed values: dvs (corresponds to vSwitch forwarding mode VXLAN (SDN)), veb.		true	string
dpdk	Whether DPDK		false	boolean
vswitchId	vSwitch ID. Not required when a port group is used. When passed together with name, vswitchId takes precedence.		false	integer(int64)
tcpCheckSum	Whether TCP checksum is enabled. Required when kernel acceleration is enabled; optional otherwise.		false	boolean
deviceModel	Driver model. rtl8139 (standard vNIC), virtio (high-speed vNIC), e1000 (Intel e1000), SR_IOV (SR-IOV passthrough), smart (smart vNIC). When SR_IOV is used, resPoolId is required.		true	string
driver	Whether kernel acceleration is enabled. Value is vhost when VM network kernel acceleration is enabled.		false	string
mtu	MTU value. Required. Range: 1000-9000.		true	integer(int64)
inAvgBandwidth	Inbound average bandwidth, in Kbps. Range: 8-34359743 Kbps. Required when inbound is true.		false	integer(int64)
inBurst	Inbound burst buffer size, in KBytes. Range: 1-4194303 KBytes. Required when inbound is true.		false	integer(int64)
outAvgBandwidth	Outbound average bandwidth, in Kbps. Range: 8-34359743 Kbps. Required when outbound is true.		false	integer(int64)
outBurst	Outbound burst buffer size, in KBytes. Range: 1-4194303 KBytes. Required when outbound is true.		false	integer(int64)
inbound	Whether inbound traffic limit is enabled		false	boolean
outbound	Whether outbound traffic limit is enabled		false	boolean
profileId	Network policy template ID. If both profileId and profileName are provided, profileId takes precedence.		false	integer(int64)
profileName	Network policy template name. If both profileId and profileName are provided, profileId takes precedence; profileId alone is sufficient.		false	string
vlanType	Whether the network policy template is of VLAN type. 0: no, 1: yes.		false	integer(int32)
driverType	SR-IOV driver type. When the network type is SR-IOV, the driver type is vfio.		false	string
networkPortGroupId	Port group ID. When adding a VM via a port group, vswitchId, profileId, profileName, securityGroupId, and vlanTrunkId can be omitted; if all are provided, the port group takes precedence.		false	integer(int64)
networkPortGroupName	Port group name		false	string
resPoolId	SR-IOV resource pool ID.		false	integer(int64)
securityGroupId	Virtual firewall. Composed of firewall ID plus action. Action must be 0 or -1: 0 = whitelist, -1 = blacklist.		false	string
vlanTrunkId	VLAN policy ID		false	string
pvlanRuleId	PVLAN rule ID		false	integer(int64)
vmId	VM ID		true	integer(int64)

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.4 Back up VM

API endpoint

POST  /NSphere/api/vm-resource/backup

API description

Back up a VM. Only backup-pool backup is supported.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"id": 0,
"backupName": "",
"backupMode": 0,
"backupType": 0,
"keepTimes": null,
"tmpDir": "",
"isCompression": 0,
"readRatio": null,
"writeRatio": null,
"filePath": null,
"devName": null,
"backupMethod": 0,
"backupPoolId": 0
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainBackupDTO	VM backup request entity	body	true	ApiDomainBackupDTO	ApiDomainBackupDTO
id	VM ID		true	integer(int64)
backupName	Backup file name. Only letters, digits, hyphen, underscore, and dot are allowed. The first character cannot be a hyphen or dot, and the value cannot be all digits.		true	string
backupMode	Backup mode. 0: full, 1: incremental, 2: differential.		true	integer(int32)
backupType	Backup type. 0: whole VM, 1: disk backup.		true	integer(int32)
keepTimes	Number of full backups to retain. Range: 1-90. Empty means no limit.		false	integer(int32)
tmpDir	Temporary directory		true	string
isCompression	Whether to compress. 0: no, 1: yes.		true	integer(int32)
readRatio	Disk read rate limit. 0 means no limit.		false	integer(int32)
writeRatio	Disk write rate limit. 0 means no limit.		false	integer(int32)
filePath	Backup storage path		false	string
devName	Backup storage device name		false	string
backupMethod	CBT backup. 0: no, 1: yes.		true	integer(int32)
backupPoolId	Backup pool ID		true	integer(int64)
from	Backup-VM request source, e.g. ssv	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.5 Check whether VM can be migrated (host only)

API endpoint

PUT  /NSphere/api/vm-resource/check-migrate/host

API description

Check whether a VM can be migrated to a different host only.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"id": 0,
"targetHostId": 0,
"enablePostcopy": false,
"autoConverge": false,
"encrypt": false,
"changeEmc": false,
"migrateParallel": false,
"migrateParallelMaxSpeed": 1100,
"networkInfoSet": [
{
"mac": "",
"targetPortGroupId": 0,
"targetPortGroupName": null
}
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainMigrateHostDTO	VM migration (host) parameter entity.	body	true	ApiDomainMigrateHostDTO	ApiDomainMigrateHostDTO
id	VM ID		true	integer(int64)
targetHostId	Destination host ID.		true	integer(int64)
enablePostcopy	Whether memory post-copy is enabled. Ignored on hosts of version 730 or 760. Effective when the VM is running or paused. When enabled, migration to the destination host is faster, but sufficient migration bandwidth must be ensured; 10Gb or higher migration network is recommended. Mutually exclusive with concurrent migration. If the network is interrupted or the destination host fails during post-copy migration, VM services are disrupted.		false	boolean
autoConverge	Whether to actively throttle CPU. Effective when the VM is running or paused. When enabled, lowers the VM CPU scheduling frequency during migration, reducing the amount of migrated data so the migration finishes faster.		false	boolean
encrypt	Whether to encrypt. Effective when the VM is paused or running. Provides more secure data transfer. Mutually exclusive with concurrent migration.		false	boolean
changeEmc	Whether to switch EMC mode. Used when a VM already in EMC mode is migrated across clusters to an EMC cluster, to keep CPU modes compatible.		false	boolean
migrateParallel	Whether to enable concurrency. Ignored on hosts of version 730 or 760. Concurrency requires 10Gb or higher network and low CPU utilization on both source and destination hosts; use with caution. Mutually exclusive with memory post-copy and encryption. The business-priority migration policy cannot be used when concurrency is enabled.		false	boolean
migrateParallelMaxSpeed	Maximum rate for concurrent migration, in MB/s. Effective when concurrency is enabled. Range: 300 to a dynamic upper bound determined by network bandwidth. Ignored on hosts of version 730 or 760.		false	integer(int64)
networkInfoSet	Destination network port group configuration.		false	array	ApiMigrateNetworkInfoDTO
mac	MAC address.		true	string
targetPortGroupId	Destination network port group ID. Verify that the selected destination host can actually use this port group; otherwise the request will fail.		true	integer(int64)
targetPortGroupName	Destination network port group name. Used as an echo name in some error scenarios.		false	string

Response status

Response code	Description	schema
200	OK	ApiResponseBoolean

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	boolean

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": true
}

2.8.6 Check whether VM can be migrated (host and storage)

API endpoint

PUT  /NSphere/api/vm-resource/check-migrate/host-storage

API description

Check whether a VM can be migrated to a different host and storage.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"diskFormat": "qcow2",
"diskMode": null,
"migrateRateType": 0,
"migrateRateLimitType": 0,
"migrateSpeed": "noLimit",
"rateLimitValue": 150,
"migrateTimeOut": null,
"storageInfoSet": [
{
"srcFile": "",
"srcPool": null,
"srcPoolTitle": null,
"srcDev": "",
"targetPath": null,
"targetPool": null,
"targetPoolTitle": null
}
],
"id": 0,
"targetHostId": 0,
"autoConverge": false,
"encrypt": false,
"enablePostcopy": false,
"changeEmc": false,
"migrateParallel": false,
"migrateParallelMaxSpeed": null,
"networkInfoSet": [
{
"mac": "",
"targetPortGroupId": 0,
"targetPortGroupName": null
}
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainMigrateHostStorageDTO	VM migration (host and storage) parameter entity.	body	true	ApiDomainMigrateHostStorageDTO	ApiDomainMigrateHostStorageDTO
diskFormat	Specified format. qcow2: smart, raw: high-speed. If omitted or empty, unchanged. Migration acceleration cannot be enabled at the same time when changing the storage format. The specified format takes effect only when the destination storage pool type is local file directory, shared file system, or NFS network file system.		false	string
diskMode	Disk pre-allocation. 0: lazy zeroed, 1: zeroed, 2: thin. If omitted or empty, unchanged. Migration acceleration cannot be enabled at the same time when changing pre-allocation. Ignored on hosts of version 730 or 760.		false	integer(int32)
migrateRateType	Migration policy. 0: migration priority, 1: business priority. Ignored on hosts of version 730 or 760. Migration priority applies to online VMs; when configured on an offline VM, the actual migration behaves as business priority + custom rate limit + no limit. Business priority is mutually exclusive with migration acceleration.		true	integer(int32)
migrateRateLimitType	Migration rate-limit policy. 0: auto rate limit, 1: manual rate limit. Effective when the migration policy is business priority. Auto rate limit applies to online VMs; on an offline VM configured with business priority + auto rate limit, actual migration behaves as custom rate limit + moderate. Ignored on hosts of version 730 or 760.		false	integer(int32)
migrateSpeed	Migration rate. noLimit: unlimited, normal: moderate, fast: fast, limitMax: capped at maximum. Ignored on hosts of version 730 or 760. Effective when the migration rate-limit policy is custom rate limit. When auto rate limit is configured and the VM migrates offline, the rate adapts to fast.		false	string
rateLimitValue	Maximum rate limit, in MB/s. Range: 1-12500. Effective when the migration rate is limitMax. Ignored on hosts of version 730 or 760.		false	integer(int64)
migrateTimeOut	Migration timeout, in minutes. Range: 5-1440. Migration is cancelled automatically when the timeout expires. Ignored on hosts of version 730 or 760. Effective when the VM is running or paused; if the VM goes offline during migration, this attribute is ignored. If an orchestration end time is also set, whichever cancels first triggers cancellation, and the later one cancels again if the migration task was not stopped.		false	integer(int64)
storageInfoSet	VM migration storage info.		true	array	ApiMigrateStorageInfoDTO
srcFile	Full path of the source VM storage volume.		true	string
srcPool	Source storage pool. Note: local disks (e.g. /dev/disk/by-path/pci-0000:18:00.0-scsi-0:1:0:0) have no storage pool.		false	string
srcPoolTitle	Display name of the storage pool holding the source file. Note: local disks (e.g. /dev/disk/by-path/pci-0000:18:00.0-scsi-0:1:0:0) have no storage pool.		false	string
srcDev	Source storage device name, e.g. vda.		true	string
targetPath	Destination storage path. Leave empty to indicate a special storage volume (local disk, iSCSI, FC block storage pool, logical volume). Otherwise it is required.		false	string
targetPool	Destination storage pool name. Leave empty to indicate a special storage volume (local disk, iSCSI, FC block storage pool, logical volume). Otherwise it is required.		false	string
targetPoolTitle	Destination storage pool display name.		false	string
id	VM ID		true	integer(int64)
targetHostId	Destination host ID.		true	integer(int64)
autoConverge	Whether to actively throttle CPU. Effective when the VM is running or paused. When enabled, lowers the VM CPU scheduling frequency during migration, reducing the amount of migrated data so the migration finishes faster.		false	boolean
encrypt	Whether to encrypt. Effective when the VM is paused or running. Provides more secure data transfer. Mutually exclusive with concurrent migration.		false	boolean
enablePostcopy	Whether memory post-copy is enabled. Ignored on hosts of version 730 or 760. Effective when the VM is running or paused. When enabled, migration to the destination host is faster, but sufficient migration bandwidth must be ensured; 10Gb or higher migration network is recommended. Mutually exclusive with concurrent migration. If the network is interrupted or the destination host fails during post-copy migration, VM services are disrupted.		false	boolean
changeEmc	Whether to switch EMC mode. Used when a VM already in EMC mode is migrated across clusters to an EMC cluster, to keep CPU modes compatible.		false	boolean
migrateParallel	Whether to enable concurrency. Ignored on hosts of version 730 or 760. Concurrency requires 10Gb or higher network and low CPU utilization on both source and destination hosts; use with caution. Mutually exclusive with memory post-copy and encryption. The business-priority migration policy cannot be used when concurrency is enabled.		false	boolean
migrateParallelMaxSpeed	Maximum rate for concurrent migration, in MB/s. Effective when concurrency is enabled. Range: 300 to a dynamic upper bound determined by network bandwidth. Ignored on hosts of version 730 or 760.		false	integer(int64)
networkInfoSet	Destination network port group configuration.		false	array	ApiMigrateNetworkInfoDTO
mac	MAC address.		true	string
targetPortGroupId	Destination network port group ID. Verify that the selected destination host can actually use this port group; otherwise the request will fail.		true	integer(int64)
targetPortGroupName	Destination network port group name. Used as an echo name in some error scenarios.		false	string

Response status

Response code	Description	schema
200	OK	ApiResponseBoolean

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	boolean

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": true
}

2.8.7 Check whether VM can be migrated (storage only)

API endpoint

PUT  /NSphere/api/vm-resource/check-migrate/storage

API description

Check whether a VM can be migrated to different storage only.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"diskFormat": "qcow2",
"diskMode": null,
"migrateRateType": 0,
"migrateRateLimitType": 0,
"migrateSpeed": "noLimit",
"rateLimitValue": 150,
"migrateTimeOut": null,
"storageInfoSet": [
{
"srcFile": "",
"srcPool": null,
"srcPoolTitle": null,
"srcDev": "",
"targetPath": null,
"targetPool": null,
"targetPoolTitle": null
}
],
"id": 0,
"migrateAcceleration": 0
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainMigrateStorageDTO	VM migration (storage) parameter entity.	body	true	ApiDomainMigrateStorageDTO	ApiDomainMigrateStorageDTO
diskFormat	Specified format. qcow2: smart, raw: high-speed. If omitted or empty, unchanged. Migration acceleration cannot be enabled at the same time when changing the storage format. The specified format takes effect only when the destination storage pool type is local file directory, shared file system, or NFS network file system.		false	string
diskMode	Disk pre-allocation. 0: lazy zeroed, 1: zeroed, 2: thin. If omitted or empty, unchanged. Migration acceleration cannot be enabled at the same time when changing pre-allocation. Ignored on hosts of version 730 or 760.		false	integer(int32)
migrateRateType	Migration policy. 0: migration priority, 1: business priority. Ignored on hosts of version 730 or 760. Migration priority applies to online VMs; when configured on an offline VM, the actual migration behaves as business priority + custom rate limit + no limit. Business priority is mutually exclusive with migration acceleration.		true	integer(int32)
migrateRateLimitType	Migration rate-limit policy. 0: auto rate limit, 1: manual rate limit. Effective when the migration policy is business priority. Auto rate limit applies to online VMs; on an offline VM configured with business priority + auto rate limit, actual migration behaves as custom rate limit + moderate. Ignored on hosts of version 730 or 760.		false	integer(int32)
migrateSpeed	Migration rate. noLimit: unlimited, normal: moderate, fast: fast, limitMax: capped at maximum. Ignored on hosts of version 730 or 760. Effective when the migration rate-limit policy is custom rate limit. When auto rate limit is configured and the VM migrates offline, the rate adapts to fast.		false	string
rateLimitValue	Maximum rate limit, in MB/s. Range: 1-12500. Effective when the migration rate is limitMax. Ignored on hosts of version 730 or 760.		false	integer(int64)
migrateTimeOut	Migration timeout, in minutes. Range: 5-1440. Migration is cancelled automatically when the timeout expires. Ignored on hosts of version 730 or 760. Effective when the VM is running or paused; if the VM goes offline during migration, this attribute is ignored. If an orchestration end time is also set, whichever cancels first triggers cancellation, and the later one cancels again if the migration task was not stopped.		false	integer(int64)
storageInfoSet	VM migration storage info.		true	array	ApiMigrateStorageInfoDTO
srcFile	Full path of the source VM storage volume.		true	string
srcPool	Source storage pool. Note: local disks (e.g. /dev/disk/by-path/pci-0000:18:00.0-scsi-0:1:0:0) have no storage pool.		false	string
srcPoolTitle	Display name of the storage pool holding the source file. Note: local disks (e.g. /dev/disk/by-path/pci-0000:18:00.0-scsi-0:1:0:0) have no storage pool.		false	string
srcDev	Source storage device name, e.g. vda.		true	string
targetPath	Destination storage path. Leave empty to indicate a special storage volume (local disk, iSCSI, FC block storage pool, logical volume). Otherwise it is required.		false	string
targetPool	Destination storage pool name. Leave empty to indicate a special storage volume (local disk, iSCSI, FC block storage pool, logical volume). Otherwise it is required.		false	string
targetPoolTitle	Destination storage pool display name.		false	string
id	VM ID		true	integer(int64)
migrateAcceleration	Migration acceleration. 0: off, 1: on. When enabled, storage format and pre-allocation must be left unchanged. Mutually exclusive with business priority. Ignored on hosts of version 730 or 760. Requires storage xcopy support; suited for copying data between LUNs on the same physical storage. Involves write amplification; recommended for VMs whose services are not latency-sensitive.		false	integer(int32)

Response status

Response code	Description	schema
200	OK	ApiResponseBoolean

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	boolean

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": true
}

2.8.8 Clone VM

API endpoint

POST  /NSphere/api/vm-resource/clone

API description

Clone VM

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"targetHostId": 0,
"id": 0,
"domainName": null,
"oldTitle": null,
"title": "",
"cloneMode": 0,
"cloneType": 0,
"diskFormat": null,
"diskMode": null,
"encryptPw": null,
"autoStartVm": true,
"storages": [
{
"src": "",
"dest": "",
"pool": "",
"dev": "vda"
}
],
"nets": [
{
"mac": "",
"profileName": null,
"name": "",
"networkPortGroupId": null,
"networkPortGroupName": null,
"sysIp": null,
"isBindIp": true,
"sysIpType": 0,
"sysMask": null,
"sysGateway": null,
"sysDns": null,
"secondaryDns": null,
"bindIpv4s": null,
"sysIpv6": null,
"isBindIpv6": true,
"sysIpv6Type": 0,
"ipv6Prefix": null,
"ipv6SysGateway": null,
"ipv6SysDns": null,
"ipv6SecondaryDns": null,
"bindIpv6s": null
}
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainCloneDTO	VM clone details	body	true	ApiDomainCloneDTO	ApiDomainCloneDTO
targetHostId	Destination host ID		true	integer(int64)
id	VM ID		true	integer(int64)
domainName	VM name		false	string
oldTitle	Source VM display name		false	string
title	VM display name		true	string
cloneMode	Clone mode. 0: normal clone, 1: quick clone, 2: full clone.		true	integer(int32)
cloneType	Clone type. 0: local clone, 1: remote clone.		true	integer(int32)
diskFormat	Disk format (raw/qcow2/luks)		false	string
diskMode	Disk pre-allocation mode. "0": lazy zeroed, "1": zeroed, "2": thin. If omitted or empty, unchanged. Migration acceleration cannot be enabled at the same time when changing pre-allocation.		false	string
encryptPw	Disk encryption password		false	string
autoStartVm	Whether to auto-start the VM after cloning. Default: do not start.		false	boolean
storages	VM storage mapping info		true	array	ApiDomainStoreDTO
src	Source storage file name, without path (required)		true	string
dest	Destination storage file name, without path (required). Only letters, digits, hyphen, underscore, and dot are allowed. The first character cannot be a hyphen or dot, and the value cannot be all digits.		true	string
pool	Destination storage pool name (required)		true	string
dev	Disk device name, e.g. "vda,vdb" (required)		true	string
nets	VM network basic info		true	array	ApiDomainNetInfoDTO
mac	Source VM MAC address		true	string
profileName	Network policy template name		false	string
name	vSwitch name. If the network mode is port group, provide the vSwitch name that the port group is bound to.		true	string
networkPortGroupId	Port group ID. If provided, the network is configured via port group. For detailed network configuration, leave empty.		false	integer(int64)
networkPortGroupName	Port group name		false	string
sysIp	System IPv4 address. Required when the allocation method is manual.		false	string
isBindIp	Whether to bind an IPv4 address		false	boolean
sysIpType	IPv4 address allocation mode. 0: default, 1: auto, 2: manual.		true	integer(int32)
sysMask	Subnet mask. Required when the allocation method is manual.		false	string
sysGateway	Default gateway		false	string
sysDns	Primary DNS server		false	string
secondaryDns	Secondary DNS server		false	string
bindIpv4s	Bound IPv4 address list		false	string
sysIpv6	System IPv6 address. Required when the allocation method is manual.		false	string
isBindIpv6	Whether to bind an IPv6 address		false	boolean
sysIpv6Type	IPv6 address allocation mode. 0: default, 1: auto, 2: manual.		true	integer(int32)
ipv6Prefix	IPv6 prefix. Required when the allocation method is manual.		false	string
ipv6SysGateway	IPv6 default gateway		false	string
ipv6SysDns	IPv6 primary DNS server		false	string
ipv6SecondaryDns	IPv6 secondary DNS server		false	string
bindIpv6s	Bound IPv6 address list		false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.9 Query VM CPU info

API endpoint

GET  /NSphere/api/vm-resource/cpu

API description

Query VM CPU info. At least one of vmId/vmUuid/vmName is required; they must not all be empty. If multiple are provided, they are used in the priority order vmId -> vmUuid -> vmName.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
vmName	VM name (domainName)	query	false	string
vmId	VM ID	query	false	integer(int64)
vmUuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiDomainCpuInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiDomainCpuInfoVO	ApiDomainCpuInfoVO
vmId	VM ID	integer(int64)
vmName	VM name	string
vmTitle	VM display name	string
vmUuid	VM UUID	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
cpuCores	VM CPU cores per socket	integer(int32)
cpuSockets	VM CPU socket count	integer(int32)
maxCpuNum	Maximum CPU cores (host CPU cores)	integer(int32)
cpuShares	VM CPU scheduling priority. High = 1024, Medium = 512, Low = 256.	integer(int32)
cpuMode	CPU working mode. custom: compatible mode; host-model: host-match mode; host-passthrough: passthrough mode; emc: EMC mode.	string
cpuArch	CPU architecture	string
cpuGurantee	CPU reservation (MHz). 0 means no reservation.	integer(int64)
cpuQuota	CPU limit value	number(double)
cpuQuotaUnit	CPU limit unit (MHz or GHz)	string
cpuMinRate	Minimum CPU cycle limit	integer(int64)
cpuMaxRate	Maximum CPU cycle limit	integer(int64)
bindcpuList	VM physical CPU binding configuration	array	ApiBindPhysicalCpuVO
vcpu	Bound vCPU	integer(int32)
pcpu	Bound physical CPU list	array	integer

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"vmId": null,
"vmName": null,
"vmTitle": null,
"vmUuid": null,
"protectModel": null,
"cpuCores": null,
"cpuSockets": null,
"maxCpuNum": null,
"cpuShares": null,
"cpuMode": null,
"cpuArch": null,
"cpuGurantee": null,
"cpuQuota": null,
"cpuQuotaUnit": null,
"cpuMinRate": null,
"cpuMaxRate": null,
"bindcpuList": [
{
"vcpu": null,
"pcpu": []
}
]
}
}

2.8.10 Modify VM CPU configuration

API endpoint

PUT  /NSphere/api/vm-resource/cpu

API description

When the VM is running or paused, changes to CPU count (for guest operating systems that support CPU hot-add, adding CPUs does not require a restart), CPU working mode, physical-CPU binding, or CPU reservation take effect only after restarting the VM. New API added in E0930.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"id": 1,
"uuid": null,
"cpuSockets": 2,
"cpuCores": 1,
"cpuMode": "custom",
"cpuModel": null,
"cpuArch": "x86_64",
"cpuShares": 512,
"cpuGurantee": 0,
"cpuQuota": null,
"cpuQuotaType": 0,
"rdt": "disabled",
"enableReduce": false,
"enableIncreaseCPU": null,
"bindcpuList": [
{
"vcpu": 0,
"pcpu": []
}
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainModifyCpuDTO	Modify-VM-CPU entity	body	true	ApiDomainModifyCpuDTO	ApiDomainModifyCpuDTO
id	VM ID. VM ID and VM UUID: at least one is required. If both are provided, VM ID takes precedence.		false	integer(int64)
uuid	VM UUID. VM ID and VM UUID: at least one is required. If both are provided, VM ID takes precedence.		false	string
cpuSockets	VM CPU socket count		true	integer(int32)
cpuCores	VM CPU cores per socket		true	integer(int32)
cpuMode	CPU working mode. custom: compatible mode; host-model: host-match mode; host-passthrough: passthrough mode; emc: EMC mode.		true	string
cpuModel	CPU model. 10: Intel@ Merom Generation, 20: Intel@ Penryn Generation, 30: Intel@ Nehalem Generation, 40: Intel@ Westmere Generation, 50: Intel@ SandyBridge Generation, 60: Intel@ IvyBridge Generation, 70: Intel@ Haswell Generation, 80: Intel@ Broadwell Generation, 90: Intel@ Skylake-Client Generation, 100: Intel@ Skylake-Server Generation, 110: Intel@ Cascadelake-Server Generation, 120: Intel@ Icelake-Client Generation, 130: Intel@ Icelake-Server Generation, 10010: AMD Opteron Generation 1, 10020: AMD Opteron Generation 2, 10030: AMD phenom Generation, 10040: AMD Opteron Generation 3, 10050: AMD Opteron Generation 4, 10060: AMD Opteron Generation 5, 10070: AMD EPYC Generation. Required when cpuMode is emc mode.		false	integer(int32)
cpuArch	CPU architecture. Required in compatible mode (cpuMode=custom); cpuArch must be x86_64, i686, or aarch64.		false	string
cpuShares	VM CPU scheduling priority. High = 1024, Medium = 512, Low = 256.		true	integer(int32)
cpuGurantee	CPU reservation (MHz). 0 means no reservation.		true	integer(int64)
cpuQuota	CPU limit value, in MHz. null means no limit.		false	integer(int64)
cpuQuotaType	CPU limit type. 0: per-CPU limit, 1: whole-VM limit. Default 0.		false	integer(int32)
rdt	RDT configuration. Effective only when noisy-neighbor prevention is enabled in the system configuration. enabled means on; anything else means off. Must be enabled or disabled.		false	string
enableReduce	Online shrink. Requires VM hardware version 2.7 or later. Default false. Ultra VMs cannot be shrunk online.		false	boolean
enableIncreaseCPU	Online increase. Defaults to null (no change).		false	boolean
bindcpuList	CPU binding list. When the VM already has auto binding, resource exclusive, or NUMA smart scheduling enabled, only an empty array or null is allowed. To unbind all CPUs manually, pass an empty array: []. To bind multiple vCPUs manually, pass multiple elements, e.g. [{"vcpu":0,"pcpu":[1,2]},{"vcpu":1,"pcpu":[3,4]}].		false	array	BindPhysicalCpuDTO
vcpu	vCPU number. When binding CPUs manually, must not be null and must be a non-negative integer (range [0, CPU count - 1]). Each vcpu number can appear at most once in bindcpuList.		false	integer(int32)
pcpu	Bound physical CPU number list. When binding CPUs manually, must not be empty (at least one physical CPU must be bound). Each element must not be null and must be >= 0.		false	array	integer

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.11 Batch query VM CPU info

API endpoint

GET  /NSphere/api/vm-resource/cpu/list

API description

Batch query VM CPU info by hpId/clusterId/hostId. If none is provided, all are queried. When multiple are provided, hostId takes precedence; without hostId, hpId and clusterId are combined.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
offset	Offset. Specifies the record from which results start. Default 0. New parameter added in E0930.	query	false	integer(int32)
limit	Maximum records returned per page. Default 10. New parameter added in E0930.	query	false	integer(int32)
sortDir	Sort type. 0: no sort, 1: ascending, 2: descending. Defaults to no sort when sortField is not empty. New parameter added in E0930.	query	false	integer(int32)
sortField	Sort field. Supported fields: name, title. New parameter added in E0930.	query	false	string
hpId	VM data center ID	query	false	integer(int64)
clusterId	VM cluster ID	query	false	integer(int64)
hostId	VM host ID	query	false	integer(int64)

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainCpuInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainCpuInfoVO
vmId	VM ID	integer(int64)
vmName	VM name	string
vmTitle	VM display name	string
vmUuid	VM UUID	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
cpuCores	VM CPU cores per socket	integer(int32)
cpuSockets	VM CPU socket count	integer(int32)
maxCpuNum	Maximum CPU cores (host CPU cores)	integer(int32)
cpuShares	VM CPU scheduling priority. High = 1024, Medium = 512, Low = 256.	integer(int32)
cpuMode	CPU working mode. custom: compatible mode; host-model: host-match mode; host-passthrough: passthrough mode; emc: EMC mode.	string
cpuArch	CPU architecture	string
cpuGurantee	CPU reservation (MHz). 0 means no reservation.	integer(int64)
cpuQuota	CPU limit value	number(double)
cpuQuotaUnit	CPU limit unit (MHz or GHz)	string
cpuMinRate	Minimum CPU cycle limit	integer(int64)
cpuMaxRate	Maximum CPU cycle limit	integer(int64)
bindcpuList	VM physical CPU binding configuration	array	ApiBindPhysicalCpuVO
vcpu	Bound vCPU	integer(int32)
pcpu	Bound physical CPU list	array	integer

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"vmId": null,
"vmName": null,
"vmTitle": null,
"vmUuid": null,
"protectModel": null,
"cpuCores": null,
"cpuSockets": null,
"maxCpuNum": null,
"cpuShares": null,
"cpuMode": null,
"cpuArch": null,
"cpuGurantee": null,
"cpuQuota": null,
"cpuQuotaUnit": null,
"cpuMinRate": null,
"cpuMaxRate": null,
"bindcpuList": [
{
"vcpu": null,
"pcpu": []
}
]
}
]
}

2.8.12 Batch query VM CPU info by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/cpu/list

API description

Batch query VM CPU info by ID/UUID list. The ID and UUID lists cannot both be empty. If both are provided, the ID list takes precedence.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"idList": [
1,
2,
3
],
"uuidList": [
"uuid-1",
"uuid-2"
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainBatchQueryDTO	VM ID/UUID list request entity	body	true	ApiDomainBatchQueryDTO	ApiDomainBatchQueryDTO
idList	VM ID list		false	array	integer(int64)
uuidList	VM UUID list		false	array	string

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainCpuInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainCpuInfoVO
vmId	VM ID	integer(int64)
vmName	VM name	string
vmTitle	VM display name	string
vmUuid	VM UUID	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
cpuCores	VM CPU cores per socket	integer(int32)
cpuSockets	VM CPU socket count	integer(int32)
maxCpuNum	Maximum CPU cores (host CPU cores)	integer(int32)
cpuShares	VM CPU scheduling priority. High = 1024, Medium = 512, Low = 256.	integer(int32)
cpuMode	CPU working mode. custom: compatible mode; host-model: host-match mode; host-passthrough: passthrough mode; emc: EMC mode.	string
cpuArch	CPU architecture	string
cpuGurantee	CPU reservation (MHz). 0 means no reservation.	integer(int64)
cpuQuota	CPU limit value	number(double)
cpuQuotaUnit	CPU limit unit (MHz or GHz)	string
cpuMinRate	Minimum CPU cycle limit	integer(int64)
cpuMaxRate	Maximum CPU cycle limit	integer(int64)
bindcpuList	VM physical CPU binding configuration	array	ApiBindPhysicalCpuVO
vcpu	Bound vCPU	integer(int32)
pcpu	Bound physical CPU list	array	integer

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"vmId": null,
"vmName": null,
"vmTitle": null,
"vmUuid": null,
"protectModel": null,
"cpuCores": null,
"cpuSockets": null,
"maxCpuNum": null,
"cpuShares": null,
"cpuMode": null,
"cpuArch": null,
"cpuGurantee": null,
"cpuQuota": null,
"cpuQuotaUnit": null,
"cpuMinRate": null,
"cpuMaxRate": null,
"bindcpuList": [
{
"vcpu": null,
"pcpu": []
}
]
}
]
}

2.8.13 Delete VM by ID/UUID

API endpoint

DELETE  /NSphere/api/vm-resource/delete

API description

Delete a VM by ID/UUID. At least one of VM ID / UUID is required; they cannot both be empty. When both are provided, the operation follows the priority order ID -> UUID.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
type	Delete type. 0: delete VM but keep storage files, 1: delete VM and storage files, 2: delete VM and low-format storage files, 3: move to recycle bin and keep storage files, 4: move to recycle bin and delete storage files, 5: move to recycle bin and low-format storage files.	query	true	integer(int32)
id	VM ID	query	false	integer(int64)
uuid	VM UUID	query	false	string
saveTime	Retention period in hours.	query	false	integer(int32)
delBackup	Whether to delete backup files	query	false	boolean

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.14 Deploy VM

API endpoint

POST  /NSphere/api/vm-resource/deploy

API description

Deploy a VM. Either the VM template ID or UUID is required. On success, returns the task ID. Advanced networks are not supported.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"id": null,
"uuid": null,
"title": "test_title",
"domainName": null,
"desc": null,
"deployMode": 0,
"destType": 2,
"targetHostId": null,
"targetClusterId": null,
"vmNum": 1,
"startNum": 1,
"cpuSocket": 1,
"cpuCore": 1,
"memory": 4096,
"diskFormat": null,
"diskPreMode": 2,
"vmView": {
"dirId": null,
"dirName": null
},
"autoStartVm": 0,
"secretLevel": 1,
"algorithm": "sm4",
"encryptPw": null,
"titleFrom": 0,
"titleList": [],
"vmDescList": [],
"encryptVm": false,
"compatibilityUpgrade": false,
"enableUltra": 0,
"cpuModeSrc": 1,
"storage": [
{
"dest": "dest_file",
"src": "src_file",
"pool": "defaultpool",
"name": "share_pool"
}
],
"network": [
{
"mac": "0c:da:41:1d:03:35",
"netInfos": [
{
"networkPortGroupId": 1,
"networkPortGroupName": "portGroupName",
"vsName": "vswitch0",
"profileName": "Default",
"portGroupUuid": null,
"netUuid": null,
"securityGroupId": null,
"vlanTrunkId": null,
"pvlanRuleId": null,
"sysIpType": 0,
"sysIp": "172.10.1.1",
"sysMask": "255.255.0.0",
"sysGateway": "172.10.0.1",
"sysDns": "4.4.4.4",
"secondaryDns": "8.8.8.8",
"bindIpv4s": "172.10.1.1",
"sysIpv6Type": 0,
"sysIpv6": "172:10:1::1",
"ipv6Prefix": 64,
"ipv6SysGateway": "172:10::1",
"ipv6SysDns": null,
"ipv6SecondaryDns": null,
"bindIpv6s": "172:10:1::1"
}
]
}
],
"sysConfig": false,
"initType": 0,
"osInfo": [
{
"sysName": "test-PC",
"regOrGroupType": 1,
"regValue": null,
"groupValue": "WORKGROUP",
"loginAccount": "",
"loginPassword": "",
"localGroup": "Administrators",
"timezone": null,
"adminPasswd": null,
"productKey": null,
"enableAutoLogon": true,
"passwdMode": null
}
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainDeployDTO	Deploy-VM parameter entity.	body	true	ApiDomainDeployDTO	ApiDomainDeployDTO
id	VM template ID.		false	integer(int64)
uuid	VM template UUID.		false	string
title	VM display name. Auto-generated. When deploying multiple VMs, this is the display-name prefix.		false	string
domainName	VM name. Auto-generated. When deploying multiple VMs, this is the name prefix. If unset, the display name is converted into the VM name. Chinese characters are not allowed; the only special character allowed is "-".		false	string
desc	Deploy VM description. Used when deploying a single VM.		false	string
deployMode	Deploy mode. 0: normal deploy, 1: quick deploy. Default 0. Encrypted VMs and Ultra-mode VMs do not support quick deploy.		true	integer(int32)
destType	Deploy target type. 1: cluster, 2: host.		true	integer(int32)
targetHostId	Destination host ID. Required when deploying to a host.		false	integer(int64)
targetClusterId	Destination cluster ID. Required when deploying to a cluster.		false	integer(int64)
vmNum	Number of VMs to deploy. Default 1.		true	integer(int32)
startNum	Starting index. Required when deploying multiple VMs with auto-generated display names. Default 1.		false	integer(int32)
cpuSocket	VM vCPU count. Defaults to the template. When provided, must be used together with cpuCore.		false	integer(int32)
cpuCore	VM CPU cores. Defaults to the template. When provided, must be used together with cpuSocket.		false	integer(int32)
memory	Memory, in MB. Defaults to the template. Must be a multiple of 4 MB.		false	integer(int32)
diskFormat	Disk format. qcow2: smart, raw: high-speed, luks: encrypted. The specified format takes effect only when the destination storage pool type is local file directory, shared file system, or NFS network file system. Must be luks for encrypted VMs. Must be raw when Ultra mode is enabled. Default: unchanged. Supported only in normal deploy mode.		false	string
diskPreMode	Disk pre-allocation. 0: lazy zeroed, 1: zeroed, 2: thin. Takes effect only when the destination storage pool type is local file directory, shared file system, or NFS network file system. Default 2. Not supported when Ultra mode is enabled. Supported only in normal deploy mode.		false	integer(int32)
vmView	VM group info entity.		false	ApiDomainViewParams	ApiDomainViewParams
dirId	Group ID.		false	integer(int64)
dirName	Group name.		false	string
autoStartVm	Whether to auto-start the VM. 0: no, 1: yes. Default 0.		false	integer(int32)
secretLevel	VM classification level. 4: top secret, 3: secret, 2: confidential, 1: internal.		false	integer(int32)
algorithm	Encryption algorithm. sm4: SM4, aes: AES.		false	string
encryptPw	Disk encryption key.		false	string
titleFrom	Display-name source. 0: auto-generated, 1: manual. Used for multi-VM deployment. Auto-generated: names are generated from the display-name prefix plus the starting index; e.g. prefix "test" and start 1 yields test_001, test_002, etc. Manual: custom display names and descriptions must be provided. Default 0.		false	integer(int32)
titleList	Manually configured VM names. Count must match the number of VMs to deploy. Used for multi-VM deployment. Required when the display-name source is manual and multiple VMs are deployed.		false	array	string
vmDescList	Manually configured VM descriptions. Either empty or its count must match the number of VMs to deploy. Used for multi-VM deployment when the display-name source is manual.		false	array	string
encryptVm	Whether this is an encrypted VM. encryptPw, secretLevel, algorithm, and diskFormat (luks) take effect only when this is true.		true	boolean
compatibilityUpgrade	Whether compatibility-upgrade handling is applied.		false	boolean
enableUltra	Whether Ultra mode is enabled on the VM. 1: enabled; 0 or empty: disabled. High-performance mode. Enabling it also enables huge pages by default. Only Ultra storage is supported when this mode is on.		false	integer(int32)
cpuModeSrc	Source of the CPU working mode for the VM to be deployed. 0: CPU mode configured on the cluster, 1: CPU mode from the template XML (default).		false	integer(int32)
storage	VM deployment storage info entity.		true	array	ApiStoreInDeploy
dest	Destination storage file name. Used for host deployment. Auto-generated when empty. Only letters, digits, hyphen, underscore, and dot are allowed. The first character must be a letter.		false	string
src	Source storage file name of the template VM. Used for host deployment.		false	string
pool	Destination storage pool name. Used for host deployment. The storage must be mounted on the host and active.		false	string
name	Storage pool name. Used for cluster deployment.		false	string
network	VM deployment network info entity.		true	array	ApiNetInDeploy
mac	Template vNIC MAC address.		true	string
netInfos	VM deployment network details entity. Details of every VM vNIC must be provided.		true	array	ApiNetInfo
networkPortGroupId	Port group ID. Port group usage is recommended.		false	integer(int64)
networkPortGroupName	Port group name.		false	string
vsName	vSwitch name. Not required when a port group is used.		false	string
profileName	Network policy template name. Not required when a port group is used.		false	string
portGroupUuid	VXLAN port group UUID. Not required when a port group is used. Otherwise required when using a VXLAN (SDN) forwarding-mode switch.		false	string
netUuid	VXLAN port group resource UUID. Not required when a port group is used. Otherwise required when using a VXLAN (SDN) forwarding-mode switch.		false	string
securityGroupId	Virtual firewall IDs. Multiple firewalls are supported, comma-separated. The last number is the VM firewall default action, applied to traffic not matched by any rule when the selected firewalls contain both blacklist and whitelist types. Examples: 1,2,3,-1 or 1,2,3,0. -1 means allow, 0 means deny. Not required when a port group is used. Otherwise provide as needed. Up to 10 firewalls are supported.		false	string
vlanTrunkId	VLAN trunk ID. Not required when a port group is used. Otherwise provide as needed.		false	string
pvlanRuleId	Private VLAN rule ID. Choose one of this field or vlanTrunkId. Not required when a port group is used. Otherwise provide as needed.		false	integer(int64)
sysIpType	IPv4 address allocation mode. 0: default, 1: auto, 2: manual.		true	integer(int32)
sysIp	IPv4 address. Used together with sysMask.		false	string
sysMask	IPv4 subnet mask. Used together with sysIp.		false	string
sysGateway	IPv4 default gateway.		false	string
sysDns	IPv4 primary DNS.		false	string
secondaryDns	IPv4 secondary DNS.		false	string
bindIpv4s	IPv4/MAC binding. IP/MAC binding maps an IP to a vNIC; if the VM vNIC IP does not match the bound IP, the vNIC cannot communicate normally. Multiple IPs are supported, separated by semicolons (;), e.g. 192.168.0.27;192.168.10.27.		false	string
sysIpv6Type	IPv6 address allocation mode. 0: default, 1: auto, 2: manual.		true	integer(int32)
sysIpv6	IPv6 address. Used together with ipv6Prefix.		false	string
ipv6Prefix	IPv6 prefix. Used together with sysIpv6.		false	integer(int32)
ipv6SysGateway	IPv6 default gateway.		false	string
ipv6SysDns	IPv6 primary DNS.		false	string
ipv6SecondaryDns	IPv6 secondary DNS.		false	string
bindIpv6s	IPv6/MAC binding. IP/MAC binding maps an IP to a vNIC; if the VM vNIC IP does not match the bound IP, the vNIC cannot communicate normally. Multiple IPs are supported, separated by semicolons (;).		false	string
sysConfig	Whether to configure the operating system. BSD-based VM templates do not support OS configuration.		true	boolean
initType	Initialization mode. 0: quick, 1: full. Quick initialization applies to Windows and Linux and requires NSpheretools to be pre-installed on the template. Full initialization applies to Windows and requires both NSpheretools and Windows sysprep on the template. Effective only when configuring the OS.		false	integer(int32)
osInfo	VM deployment system info entity. When non-empty, the OS is configured. BSD does not support OS configuration.		false	array	ApiDeployVmOsInfo
sysName	Computer name. Supported on Windows and Linux. Only letters, digits, and hyphen are allowed; hyphen cannot appear at the start or end.		true	string
regOrGroupType	Domain or workgroup. 1: domain, 2: workgroup. Used during Windows initialization.		false	integer(int32)
regValue	Domain name. Required when joining a domain. Used during Windows initialization. Only letters, digits, hyphen, underscore, and dot are allowed. The first character cannot be a hyphen or dot, and the value cannot be all digits.		false	string
groupValue	Workgroup value. Required when joining a workgroup. Used during Windows initialization. Only letters, digits, hyphen, underscore, and dot are allowed. The first character cannot be a hyphen or dot, and the value cannot be all digits.		false	string
loginAccount	Login account. Supported on Windows and Linux. Only letters, digits, hyphen, underscore, and dot are allowed. The first character cannot be a hyphen or dot, and the value cannot be all digits.		true	string
loginPassword	Login password. Supported on Windows and Linux. Ensure the password complies with the OS password policy; otherwise setting it may fail.		true	string
localGroup	Local group. Used during Windows initialization.		false	string
timezone	Time zone. Used during Windows initialization. Added parameter for full initialization. 30: (GMT -0600) Guadalajara, Mexico City, Monterrey; 85: (GMT) Dublin, Edinburgh, Lisbon, London; 90: (GMT) Monrovia, Reykjavik; 110: (GMT +0100) Amsterdam, Berlin, Bern, Rome, Stockholm; 105: (GMT +0100) Brussels, Copenhagen, Madrid, Paris; 100: (GMT +0100) Sarajevo, Skopje, Warsaw, Zagreb; 140: (GMT +0200) Harare, Pretoria; 145: (GMT +0300) Moscow, St. Petersburg, Volgograd; 185: (GMT +0500) Ashgabat, Tashkent; 186: (GMT +0500) Islamabad, Karachi; 195: (GMT +0600) Astana; 205: (GMT +0700) Bangkok, Hanoi, Jakarta; 210: (GMT +0800) Beijing, Chongqing, Hong Kong SAR, Urumqi; 215: (GMT +0800) Kuala Lumpur, Singapore; 235: (GMT +0900) Osaka, Sapporo, Tokyo; 230: (GMT +0900) Seoul.		false	string
adminPasswd	Default user password. The Administrator password; leave empty to skip setting it. Used during Windows initialization. Added parameter for full initialization. Required only when joining a domain.		false	string
productKey	Activation serial number. Format: XXXXX-XXXXX-XXXXX-XXXXX-XXXXX where X is 0-9 or A-Z. Used during Windows initialization. Added parameter for full initialization.		false	string
enableAutoLogon	Allow auto-login. Used during Windows initialization. Added parameter for full initialization.		false	boolean
passwdMode	Password mode. 0: never expires (noexpired). Used during Windows initialization.		false	integer(int32)

Response status

Response code	Description	schema
200	OK	ApiResponseLong

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	integer(int64)	integer(int64)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": null
}

2.8.15 Query VM details

API endpoint

GET  /NSphere/api/vm-resource/detail

API description

Query VM details. At least one of vmId/vmUuid/vmName is required; they must not all be empty. If multiple are provided, they are used in the priority order vmId -> vmUuid -> vmName. New return attributes added in E0930.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
vmName	VM name (domainName)	query	false	string
vmId	VM ID	query	false	integer(int64)
vmUuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiDomainDetailVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiDomainDetailVO	ApiDomainDetailVO
id	VM ID	integer(int64)
domainName	VM name	string
uuid	VM UUID	string
title	VM display name	string
desc	VM description. Maximum length 2048 characters.	string
hostId	VM host ID	integer(int64)
clusterId	VM cluster ID	integer(int64)
antivirusConfigured	Whether antivirus is configured	boolean
securityModeEnable	Whether CVM confidential mode is enabled. 0: disabled, 1: enabled.	string
clusterInSafeArea	Whether the cluster is in a security zone	boolean
manageExistVm	Whether the VM is managed by BigCloud. 0: not managed, 1: managed.	integer(int32)
vmType	VM type. Low-order 2 bytes: VM category. Default 1 (standard VM). 101-200 are VDI-defined. High-order 2 bytes: VM type; bits 0-31 from low to high, and the high 2 bytes span bits 16-31 with bits 17 and 16 used. 00: normal VM (shown as standard VM), 01: disaster-recovery source VM, 10: disaster-recovery target VM. Other bits unused.	integer(int32)
videoType	GPU type list. Allowed values: vga, qxl, virtio, cirrus. New attribute added in E0930.	array	string
kaasVm	Whether the VM is a K8s cluster node. 0: no, 1: yes.	integer(int32)
antivirusType	Antivirus vendor. 0: not installed, 1: Asiainfo, 2: Qi-Anxin (formerly 360).	integer(int32)
isEncrypt	Whether encrypted	boolean
secretLevel	Classification level. 4: top secret, 3: secret, 2: confidential, 1: internal.	integer(int32)
enableUltra	Whether Ultra mode is enabled on the VM. 1: enabled; 0 or empty: disabled. Ultra VMs do not support the storage serial or clustersize parameters; targetBus must be virtio, driveType must be raw, and numaBalance cannot be enabled.	integer(int32)
hostStatus	VM host status. 0: abnormal, 1: normal, 5: isolated mode.	integer(int32)
configVNC	Whether VNC proxy parameters are configured	boolean
summary	VM summary	ApiDomainSummaryInfoVO	ApiDomainSummaryInfoVO
cvkKernelType	CVK kernel type in hexadecimal. The rightmost digit indicates CPU (0: x86, 1: arm), the second digit indicates OS (0: ubuntu, 1: centos, 2: h3linux, 3: tencentos).	integer(int32)
manager	VM hypervisor	string
architecture	CPU architecture, e.g. X86_64, X86.	string
acpi	Whether ACPI is enabled	boolean
apic	Whether APIC is enabled	boolean
cpuTune	CPU scheduling priority: high, medium, low. New attribute added in E0930.	string
memoryTune	Memory resource priority: high, medium, low. New attribute added in E0930.	string
nspheretoolStatus	NSpheretools status. New attribute added in E0930.	integer(int32)
displayType	Console type: VNC, SPICE. New attribute added in E0930.	string
existPrealloc	Whether pre-allocation (zeroed or lazy zeroed) exists. New attribute added in E0930.	boolean
existRaw	Whether raw format exists. New attribute added in E0930.	boolean
hugepage	Whether huge pages are enabled. New attribute added in E0930.	boolean
ioTune	I/O priority: high, medium, low. New attribute added in E0930.	string
vncProxy	Whether VNC proxy is enabled. New attribute added in E0930.	string
vncport	VNC port. New attribute added in E0930.	integer(int32)
vnuma	Whether vNUMA is enabled. New attribute added in E0930.	boolean
pae	Whether PAE is enabled	boolean
osha	Blue-screen fault policy. 0: no action, 1: fault restart, 2: fault migration.	integer(int32)
osVersion	Operating system version	string
timeSync	Whether time sync is enabled	boolean
clockSetting	Clock configuration	string
ioWeight	I/O priority. 500: high, 300: medium, 200: low.	integer(int32)
autoMigrate	Whether auto-migration is enabled	boolean
autoTools	Whether tools are installed automatically	boolean
nspheretoolsType	NSpheretools type. Allowed values: virtio (Virtio serial), serial (plain serial).	string
enableIntegrityCheck	Whether integrity check is enabled	boolean
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	boolean
haManage	Whether managed by HA	boolean
priority	VM startup priority. -1: default, 0: low, 1: medium, 2: high.	integer(int32)
system	System type. 0: Windows, 1: Linux, 2: BSD.	integer(int32)
machineVersion	Hardware version	string
status	VM status	string
existController	Existing controller list	array	string
vmPriority	VM priority	integer(int32)
seccomp	VM escape protection. enable: on; null or disable: off.	string
autonuma	VM automatic NUMA binding. enable: on; disable or null: off.	string
cpuExclusive	VM CPU exclusive. numa: CPU exclusive enabled; disable: off.	string
numaBalance	VM NUMA smart scheduling. enable: on; disable or null: off.	string
emulator	Emulator path. New attribute added in E0930.	string
enableMultiQueue	Whether multi-queue acceleration is enabled. New attribute added in E0930.	boolean
cpu	CPU info	ApiDomainCPUInfoVO	ApiDomainCPUInfoVO
curValue	Current vCPU count	integer(int32)
cpuSocket	CPU socket count	integer(int32)
cpuCore	Cores per socket	integer(int32)
maxValue	Maximum vCPU count	integer(int32)
maxCpuSocket	Maximum CPU sockets	integer(int32)
rdt	RDT configuration	string
cpuFeature	When true and cpuMode=host-model, feature tags are added under cpu.	boolean
enableIncreaseCPU	Whether online CPU add/remove is allowed	boolean
hostValue	Host CPU count	integer(int32)
cpuShares	VM CPU scheduling priority. High = 1024, Medium = 512, Low = 256.	integer(int32)
cpuMode	CPU working mode. custom: compatible mode; host-model: host-match mode; host-passthrough: passthrough mode; emc: EMC mode.	string
cpuModel	CPU model. 10: Intel@ Merom Generation, 20: Intel@ Penryn Generation, 30: Intel@ Nehalem Generation, 40: Intel@ Westmere Generation, 50: Intel@ SandyBridge Generation, 60: Intel@ IvyBridge Generation, 70: Intel@ Haswell Generation, 80: Intel@ Broadwell Generation, 90: Intel@ Skylake-Client Generation, 100: Intel@ Skylake-Server Generation, 110: Intel@ Cascadelake-Server Generation, 120: Intel@ Icelake-Client Generation, 130: Intel@ Icelake-Server Generation, 10010: AMD Opteron Generation 1, 10020: AMD Opteron Generation 2, 10030: AMD phenom Generation, 10040: AMD Opteron Generation 3, 10050: AMD Opteron Generation 4, 10060: AMD Opteron Generation 5, 10070: AMD EPYC Generation.	integer(int32)
cpuArch	CPU architecture	string
cpuGuarantee	CPU reservation (MHz). 0 means no reservation.	integer(int64)
cpuGuaranMaxRate	Maximum CPU reservation	integer(int64)
cpuGuaranMinRate	Minimum CPU reservation	integer(int64)
cpuQuota	CPU limit value	number(double)
cpuQuotaUnit	CPU limit unit	string
cpuQuotaType	CPU limit type. 0: per-CPU limit, 1: whole-VM limit.	integer(int32)
cpuMinRate	Minimum CPU frequency	integer(int64)
cpuMaxRate	Maximum CPU frequency	integer(int64)
cpuMin	Minimum CPU cores	number(double)
cpuMax	Maximum CPU cores	number(double)
bindPhysicalCpu	CPU binding info	array	ApiBindCPUInfoVO
vcpu	vCPU number	integer(int32)
cpuset	Bound physical CPU set	string
mem	Memory info	ApiDomainMemoryDetailVO	ApiDomainMemoryDetailVO
curValue	Current memory size	number
curMemoryUnit	Current memory unit	string
maxValue	Maximum available memory (host memory size)	integer(int64)
maxMemory	Maximum allocatable memory. If the VM is online, the lesser of 16 times the original VM memory and host memory; if powered off, host memory.	integer(int64)
memoryLocked	Memory reservation percentage. 0-100.	integer(int32)
memoryPriority	Memory resource priority. 0: low, 50: medium, 100: high.	integer(int32)
memLimit	Memory limit	number(double)
memLimitUnit	Memory limit unit	string
autoMem	Whether memory overcommit is enabled	boolean
hotMem	Whether memory hot-add is enabled	boolean
hugepage	Whether huge pages are enabled	boolean
boot	Boot configuration	ApiDomainBootDetailVO	ApiDomainBootDetailVO
autoRun	Whether to auto-start. 0: no, 1: yes. Default 0.	boolean
bootFirmware	Boot firmware type. 0: BIOS (B), 1: EFI (E).	integer(int32)
bootList	Boot device info	array	ApiBootDevVO
bootdev	Boot device identifier	string
bootDevName	Boot device name	string
order	Boot order	integer(int32)
diskList	Disk info	array	ApiDomainDetailDiskInfoVO
diskIOMode	Disk I/O mode. Allowed values: native, threads, io_uring.	string
targetBus	Disk bus type. ide: IDE disk; usb: USB disk; virtio: high-speed disk; virtioScsi: high-speed SCSI disk.	string
dispName	Display name	string
diskSecret	Whether disk encryption is enabled	boolean
serial	Serial number	string
unmap	Whether UNMAP is enabled	boolean
enableRbd		boolean
srcPathAll	Full disk source path	string
srcPath	Disk source path. If the path exceeds 30 characters, the excess is truncated with an ellipsis.	string
backupBlock	Backup block info	string
enableModify	Whether modification is allowed	boolean
usage	Utilization (percentage)	number(double)
type	Storage volume type. file: file; block: block device; ultra: ubd. When the storage type is network, disk encryption is not supported, cache mode supports only none|directsync, ultra mode is not supported, existing files are not supported; driveType must be raw, mode must be 2, clustersize must be 262144, diskIOMode must be null, diskMode must be subordinate, and priority must be 2.	string
size	Disk size (MB)	number(double)
allocation	Used space (MB)	integer(int64)
minValue	Minimum configurable size (MB)	number(double)
maxValue	Maximum configurable size (MB)	number(double)
poolName	Storage pool name	string
poolType	Storage pool type. dir: local file directory / local file directory (high-speed); netfs: NFS network file system; fs: shared file system; cifs: Windows shared directory; logical: LVM logical volume; iscsi: iSCSI network storage; block: FC network storage; scsi: SCSI storage; glusterfs: GlusterFS file system.	string
showSize	Displayed size	number(double)
showUnit	Displayed unit	string
format	Disk format. qcow2: smart, raw: high-speed, luks: encrypted.	string
clustersize	Cluster size	string
enableEditDisk	Whether the disk can be edited	boolean
enableConverFmt	Whether format conversion is allowed	boolean
l2cache	Whether L2 cache is enabled	boolean
diskMode	Disk mode. subordinate: dependent; independent-persistent: independent-persistent.	string
enableEditDiskMode	Whether the disk mode can be modified	boolean
cacheModel	Disk cache mode. none: L1 virtual cache; writeback: L2 virtual cache; writethrough: L1 physical cache; directsync: direct I/O.	string
cacheFile	Cache file path	string
mode	Disk pre-allocation mode. 0: lazy zeroed, 1: zeroed, 2: thin.	integer(int32)
readBytesSec	Read bandwidth limit (KB/s)	integer(int64)
writeBytesSec	Write bandwidth limit (KB/s)	integer(int64)
readIopsSec	Read IOPS limit	integer(int64)
writeIopsSec	Write IOPS limit	integer(int64)
hotPluggable	Whether hot-plug is supported	boolean
iothreads	Whether I/O threads are used	boolean
readonly	Whether read-only	boolean
share	Whether the disk is shared	boolean
deviceName	Front-end device name	string
floppyList	Base storage device info	array	ApiDomainBasicStorageVO
srcPathAll	Full source path	string
srcPath	Source path. If the path exceeds 30 characters, the excess is truncated with an ellipsis.	string
deviceName	Device name	string
deviceBus	Device bus type. "ide" for CD-ROM, "fdc" for floppy.	string
cdromList	Base storage device info	array	ApiDomainBasicStorageVO
srcPathAll	Full source path	string
srcPath	Source path. If the path exceeds 30 characters, the excess is truncated with an ellipsis.	string
deviceName	Device name	string
deviceBus	Device bus type. "ide" for CD-ROM, "fdc" for floppy.	string
sriovNetworkList	SR-IOV vNIC info	array	ApiDomainSriovNicInfoVO
location	Physical location	string
ethName	vNIC name	string
driverType	SR-IOV driver type. When the network type is SR-IOV, the driver type is vfio.	string
mac	MAC address	string
oldMac	Old MAC address	string
vlan	VLAN	string
resPoolName	Resource pool name	string
resPoolId	Resource pool ID	integer(int64)
networkList	VM network info	array	ApiDomainNetworkInfoVO
domainId	VM ID	integer(int64)
title	VM display name. New attribute added in E0930.	string
vmUuid	VM UUID	string
mac	vNIC MAC address	string
ipAddr	vNIC IP address	string
ipv6	vNIC IPv6 address	string
vsName	vSwitch name	string
mode	VM vNIC forwarding mode. Allowed values: dvs (corresponds to vSwitch forwarding mode VXLAN (SDN)), veb.	string
maskAddr	Subnet mask	string
mtu	MTU value	integer(int64)
vlan	VLAN value	integer(int32)
netType	vNIC type. 0: bridge, 1: NAT, 2: no network, 3: physical passthrough, 4: SR-IOV. New attribute added in E0930.	integer(int32)
deviceModel	Driver model (rtl8139, virtio, e1000). New attribute added in E0930.	string
isKernelAccelerated	Kernel acceleration. Effective when the vNIC driver is virtio. 1: accelerated, 0: not. New attribute added in E0930.	integer(int32)
vsMode	vSwitch forwarding mode. 0: veb, 1: vepa, 2: multi-channel, 3: distributed. New attribute added in E0930.	integer(int32)
virtualport	Whether vport is configured. New attribute added in E0930.	boolean
inAvgBandwidth	Inbound average bandwidth, in Kbps	integer(int64)
inBurst	Inbound burst buffer size, in KBytes	integer(int64)
outAvgBandwidth	Outbound average bandwidth, in Kbps	integer(int64)
outBurst	Outbound burst buffer size, in KBytes	integer(int64)
limitInBound	Whether inbound traffic limit is enabled	boolean
limitOutBound	Whether outbound traffic limit is enabled	boolean
gateway	Gateway address	string
dns	Primary DNS server	string
secondDns	Secondary DNS server	string
ipv4Dhcp	Whether IPv4 DHCP is enabled	boolean
bindIp	Whether IPv4 is bound	boolean
ipv6PrefixLength	IPv6 prefix length	integer(int32)
ipv6Gateway	IPv6 default gateway	string
ipv6Dns	IPv6 primary DNS server	string
ipv6SecondDns	IPv6 secondary DNS server	string
ipv6Mode	IPv6 mode	string
ipv6Dhcp	Whether IPv6 DHCP is enabled	boolean
bindIpv6	Whether IPv6 is bound	boolean
profileId	Network policy template ID	integer(int64)
profileName	Network policy template name	string
portgroupUUID	VXLAN port group UUID	string
firewalls	Virtual firewall rule	array	ApiDomainFirewallVO
id	Rule ID	integer(int64)
title	Rule name	string
ruleAction	Firewall type. 0: blacklist, 1: whitelist.	integer(int32)
firewallDefaultAction	VM firewall default action. -1: allow, 0: deny.	integer(int32)
vlanTrunkId	VLAN policy ID	string
vlanTrunkName	VLAN policy name	string
isDpdk	Whether it is a DPDK switch. New attribute added in E0930.	boolean
tabletList	Tablet device	array	ApiDomainTabletVO
model	Cursor movement mode	string
bus	Bus type. Allowed values: usb.	string
mouseList	Mouse device	array	ApiDomainMouseVO
model	Mouse movement mode	string
bus	Bus type. Allowed values: ps2, usb.	string
displayList	Display device	array	ApiDomainDisplayDetailVO
type	Display type. Allowed values: "vnc", "spice".	string
address	Device address	string
port	Port number	string
portIpv6	IPv6 port	string
password	Access password	string
kayboardMap	Keyboard mapping	string
enableVncProxy	Whether VNC proxy is enabled	boolean
enableSpiceCompress	Whether SPICE compression is enabled	boolean
vncIp	VNC IP	string
vncUsername	VNC username	string
vncPwd	VNC password	string
vncPasswdMode	VNC password mode	string
videoList	Video device	array	ApiDomainVideoDetailVO
devType	Device type. Allowed values: Vga, Qxl, Virtio, Cirrus.	string
storage	Video memory size	integer(int32)
heads	Number of display heads	string
number	Device index	integer(int32)
pciView	PCI view info	string
soundList	Sound card device	array	ApiDomainSoundVO
type	Sound card type. Allowed values: ac97, ich6.	string
encryptCardList	Encryption card device	array	ApiDomainEncryptCardDetailVO
bus	Bus number	string
slot	Slot number	string
function	Function number	string
pciName	PCI name	string
address	PCI address	string
pciList	PCI device	array	ApiDomainPCIDetailVO
driver	Driver type. Allowed values: KVM, VFIO.	string
vendor	Vendor	string
product	Product	string
ethName	NIC name	string
productId	Product ID	string
vendorId	Vendor ID	string
bus	Bus number	string
slot	Slot number	string
function	Function number	string
pciName	PCI name	string
name	Device name	string
usbList	USB device	array	ApiDomainUSBDetailVO
product	Product name	string
name	Device name	string
vendor	Vendor name	string
productId	Product ID	string
vendorId	Vendor ID	string
bus	Bus number	string
device	Device number	string
usbController	USB controller version. 1: USB 1.0, 2: USB 2.0, 3: USB 3.0.	string
serialList	Serial device	array	ApiDomainSerialInfoVO
type	Serial type. Allowed values: pty, dev.	string
targetPort	Target port	integer(int32)
mode	Working mode	string
devPath	Device path	string
connHost	Connect host	string
connPort	Connect port	string
bindIp	Bound IP	string
bindPort	Bind port	string
monitor	Whether it is a monitoring channel	boolean
isSerialLog	Whether serial logging is enabled	boolean
numa	NUMA configuration	ApiDomainNumaDetailVO	ApiDomainNumaDetailVO
nodeSize	NUMA node count	integer(int32)
nodeSet	NUMA node set	string
associate	Whether associated with CPU	boolean
safety	Security policy info	ApiDomainSafetyInfoVO	ApiDomainSafetyInfoVO
spiceTls	Whether SPICE TLS is enabled	boolean
spiceChannels	SPICE channel list	array	string
redirUsb	USB redirection count	integer(int32)
ifSupSpice	Whether SPICE is supported	boolean
enableRedirectUsb	Whether USB redirection is enabled	boolean
enableAntivirus	Whether antivirus is enabled	boolean
secretLevel	Classification level. 4: top secret, 3: secret, 2: confidential, 1: internal.	integer(int32)
supportAntivirus	Whether antivirus is supported	boolean
antivirusType	Antivirus vendor. 0: not installed, 1: Asiainfo, 2: Qi-Anxin (formerly 360).	string
securityId	Security policy ID	integer(int32)
securityName	Security policy name	string
publicCloudId	Owning public-cloud ID	integer(int64)
vtpm	Virtual TPM configuration	string
tpm	TPM configuration	string
gpu	GPU configuration	ApiDomainGPUVO	ApiDomainGPUVO
resPoolId	GPU resource pool ID	integer(int64)
resPool	GPU resource pool name	string
businessTemId	Business template ID	integer(int64)
businessTem	Business template name	string
deviceDriver	GPU driver type	string
count	GPU count	integer(int32)
shared	Share ratio	integer(int32)
maxCount	Maximum available GPU count	integer(int32)
frl	Frame rate limit (FRL)	integer(int32)
watchdog	Watchdog configuration	ApiDomainWatchdogVO	ApiDomainWatchdogVO
model	Watchdog model	string
action	Action. Allowed values: "reset" (restart), "poweroff" (power off), "migrate" (migrate).	string
netUsbList	Network USB device	array	ApiDomainNetUsbDetailVO
host	Host IP	string
service	Service port	integer(int32)
port	Port number	integer(int32)
manufacturer	Vendor name	string
product	Product name	string
productId	Product ID	string
vendorId	Vendor ID	string
usbController	USB controller	string
path	Device path	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"id": null,
"domainName": null,
"uuid": null,
"title": null,
"desc": null,
"hostId": null,
"clusterId": null,
"antivirusConfigured": true,
"securityModeEnable": null,
"clusterInSafeArea": true,
"manageExistVm": null,
"vmType": null,
"videoType": [],
"kaasVm": null,
"antivirusType": null,
"isEncrypt": true,
"secretLevel": null,
"enableUltra": null,
"hostStatus": null,
"configVNC": true,
"summary": {
"cvkKernelType": null,
"manager": null,
"architecture": null,
"acpi": true,
"apic": true,
"cpuTune": null,
"memoryTune": null,
"nspheretoolStatus": null,
"displayType": null,
"existPrealloc": true,
"existRaw": true,
"hugepage": true,
"ioTune": null,
"vncProxy": null,
"vncport": null,
"vnuma": true,
"pae": true,
"osha": null,
"osVersion": null,
"timeSync": true,
"clockSetting": null,
"ioWeight": null,
"autoMigrate": true,
"autoTools": true,
"nspheretoolsType": null,
"enableIntegrityCheck": true,
"protectModel": true,
"haManage": true,
"priority": null,
"system": null,
"machineVersion": null,
"status": null,
"existController": [],
"vmPriority": null,
"seccomp": null,
"autonuma": null,
"cpuExclusive": null,
"numaBalance": null,
"emulator": null,
"enableMultiQueue": true
},
"cpu": {
"curValue": null,
"cpuSocket": null,
"cpuCore": null,
"maxValue": null,
"maxCpuSocket": null,
"rdt": null,
"cpuFeature": true,
"enableIncreaseCPU": true,
"hostValue": null,
"cpuShares": null,
"cpuMode": null,
"cpuModel": null,
"cpuArch": null,
"cpuGuarantee": null,
"cpuGuaranMaxRate": null,
"cpuGuaranMinRate": null,
"cpuQuota": null,
"cpuQuotaUnit": null,
"cpuQuotaType": null,
"cpuMinRate": null,
"cpuMaxRate": null,
"cpuMin": null,
"cpuMax": null,
"bindPhysicalCpu": [
{
"vcpu": null,
"cpuset": null
}
]
},
"mem": {
"curValue": null,
"curMemoryUnit": null,
"maxValue": null,
"maxMemory": null,
"memoryLocked": null,
"memoryPriority": null,
"memLimit": null,
"memLimitUnit": null,
"autoMem": true,
"hotMem": true,
"hugepage": true
},
"boot": {
"autoRun": true,
"bootFirmware": null,
"bootList": [
{
"bootdev": null,
"bootDevName": null,
"order": null
}
]
},
"diskList": [
{
"diskIOMode": null,
"targetBus": null,
"dispName": null,
"diskSecret": true,
"serial": null,
"unmap": true,
"enableRbd": true,
"srcPathAll": null,
"srcPath": null,
"backupBlock": null,
"enableModify": true,
"usage": null,
"type": null,
"size": null,
"allocation": null,
"minValue": null,
"maxValue": null,
"poolName": null,
"poolType": null,
"showSize": null,
"showUnit": null,
"format": null,
"clustersize": null,
"enableEditDisk": true,
"enableConverFmt": true,
"l2cache": true,
"diskMode": null,
"enableEditDiskMode": true,
"cacheModel": null,
"cacheFile": null,
"mode": null,
"readBytesSec": null,
"writeBytesSec": null,
"readIopsSec": null,
"writeIopsSec": null,
"hotPluggable": true,
"iothreads": true,
"readonly": true,
"share": true,
"deviceName": null
}
],
"floppyList": [
{
"srcPathAll": null,
"srcPath": null,
"deviceName": null,
"deviceBus": null
}
],
"cdromList": [
{
"srcPathAll": null,
"srcPath": null,
"deviceName": null,
"deviceBus": null
}
],
"sriovNetworkList": [
{
"location": null,
"ethName": null,
"driverType": null,
"mac": null,
"oldMac": null,
"vlan": null,
"resPoolName": null,
"resPoolId": null
}
],
"networkList": [
{
"domainId": null,
"title": null,
"vmUuid": null,
"mac": null,
"ipAddr": null,
"ipv6": null,
"vsName": null,
"mode": null,
"maskAddr": null,
"mtu": null,
"vlan": null,
"netType": null,
"deviceModel": null,
"isKernelAccelerated": null,
"vsMode": null,
"virtualport": true,
"inAvgBandwidth": null,
"inBurst": null,
"outAvgBandwidth": null,
"outBurst": null,
"limitInBound": true,
"limitOutBound": true,
"gateway": null,
"dns": null,
"secondDns": null,
"ipv4Dhcp": true,
"bindIp": true,
"ipv6PrefixLength": null,
"ipv6Gateway": null,
"ipv6Dns": null,
"ipv6SecondDns": null,
"ipv6Mode": null,
"ipv6Dhcp": true,
"bindIpv6": true,
"profileId": null,
"profileName": null,
"portgroupUUID": null,
"firewalls": [
{
"id": null,
"title": null,
"ruleAction": null
}
],
"firewallDefaultAction": null,
"vlanTrunkId": null,
"vlanTrunkName": null,
"isDpdk": true
}
],
"tabletList": [
{
"model": null,
"bus": null
}
],
"mouseList": [
{
"model": null,
"bus": null
}
],
"displayList": [
{
"type": null,
"address": null,
"port": null,
"portIpv6": null,
"password": null,
"kayboardMap": null,
"enableVncProxy": true,
"enableSpiceCompress": true,
"vncIp": null,
"vncUsername": null,
"vncPwd": null,
"vncPasswdMode": null
}
],
"videoList": [
{
"devType": null,
"storage": null,
"heads": null,
"number": null,
"pciView": null
}
],
"soundList": [
{
"type": null
}
],
"encryptCardList": [
{
"bus": null,
"slot": null,
"function": null,
"pciName": null,
"address": null
}
],
"pciList": [
{
"driver": null,
"vendor": null,
"product": null,
"ethName": null,
"productId": null,
"vendorId": null,
"bus": null,
"slot": null,
"function": null,
"pciName": null,
"name": null
}
],
"usbList": [
{
"product": null,
"name": null,
"vendor": null,
"productId": null,
"vendorId": null,
"bus": null,
"device": null,
"usbController": null
}
],
"serialList": [
{
"type": null,
"targetPort": null,
"mode": null,
"devPath": null,
"connHost": null,
"connPort": null,
"bindIp": null,
"bindPort": null,
"monitor": true,
"isSerialLog": true
}
],
"numa": {
"nodeSize": null,
"nodeSet": null,
"associate": true
},
"safety": {
"spiceTls": true,
"spiceChannels": [],
"redirUsb": null,
"ifSupSpice": true,
"enableRedirectUsb": true,
"enableAntivirus": true,
"secretLevel": null,
"supportAntivirus": true,
"antivirusType": null,
"securityId": null,
"securityName": null,
"publicCloudId": null
},
"vtpm": null,
"tpm": null,
"gpu": {
"resPoolId": null,
"resPool": null,
"businessTemId": null,
"businessTem": null,
"deviceDriver": null,
"count": null,
"shared": null,
"maxCount": null,
"frl": null
},
"watchdog": {
"model": null,
"action": null
},
"netUsbList": [
{
"host": null,
"service": null,
"port": null,
"manufacturer": null,
"product": null,
"productId": null,
"vendorId": null,
"usbController": null,
"path": null
}
]
}
}

2.8.16 Batch query VM details

API endpoint

GET  /NSphere/api/vm-resource/detail/list

API description

Batch query VM details by hpId/clusterId/hostId. If none is provided, all are queried. When multiple are provided, hostId takes precedence; without hostId, hpId and clusterId are combined.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
offset	Offset. Specifies the record from which results start. Default 0. New parameter added in E0930.	query	false	integer(int32)
limit	Maximum records returned per page. Default 10. New parameter added in E0930.	query	false	integer(int32)
sortDir	Sort type. 0: no sort, 1: ascending, 2: descending. Defaults to no sort when sortField is not empty. New parameter added in E0930.	query	false	integer(int32)
sortField	Sort field. Supported fields: name, title, desc, mem, system. New parameter added in E0930.	query	false	string
hpId	VM data center ID	query	false	integer(int64)
clusterId	VM cluster ID	query	false	integer(int64)
hostId	VM host ID	query	false	integer(int64)

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainDetailVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainDetailVO
id	VM ID	integer(int64)
domainName	VM name	string
uuid	VM UUID	string
title	VM display name	string
desc	VM description. Maximum length 2048 characters.	string
hostId	VM host ID	integer(int64)
clusterId	VM cluster ID	integer(int64)
antivirusConfigured	Whether antivirus is configured	boolean
securityModeEnable	Whether CVM confidential mode is enabled. 0: disabled, 1: enabled.	string
clusterInSafeArea	Whether the cluster is in a security zone	boolean
manageExistVm	Whether the VM is managed by BigCloud. 0: not managed, 1: managed.	integer(int32)
vmType	VM type. Low-order 2 bytes: VM category. Default 1 (standard VM). 101-200 are VDI-defined. High-order 2 bytes: VM type; bits 0-31 from low to high, and the high 2 bytes span bits 16-31 with bits 17 and 16 used. 00: normal VM (shown as standard VM), 01: disaster-recovery source VM, 10: disaster-recovery target VM. Other bits unused.	integer(int32)
videoType	GPU type list. Allowed values: vga, qxl, virtio, cirrus. New attribute added in E0930.	array	string
kaasVm	Whether the VM is a K8s cluster node. 0: no, 1: yes.	integer(int32)
antivirusType	Antivirus vendor. 0: not installed, 1: Asiainfo, 2: Qi-Anxin (formerly 360).	integer(int32)
isEncrypt	Whether encrypted	boolean
secretLevel	Classification level. 4: top secret, 3: secret, 2: confidential, 1: internal.	integer(int32)
enableUltra	Whether Ultra mode is enabled on the VM. 1: enabled; 0 or empty: disabled. Ultra VMs do not support the storage serial or clustersize parameters; targetBus must be virtio, driveType must be raw, and numaBalance cannot be enabled.	integer(int32)
hostStatus	VM host status. 0: abnormal, 1: normal, 5: isolated mode.	integer(int32)
configVNC	Whether VNC proxy parameters are configured	boolean
summary	VM summary	ApiDomainSummaryInfoVO	ApiDomainSummaryInfoVO
cvkKernelType	CVK kernel type in hexadecimal. The rightmost digit indicates CPU (0: x86, 1: arm), the second digit indicates OS (0: ubuntu, 1: centos, 2: h3linux, 3: tencentos).	integer(int32)
manager	VM hypervisor	string
architecture	CPU architecture, e.g. X86_64, X86.	string
acpi	Whether ACPI is enabled	boolean
apic	Whether APIC is enabled	boolean
cpuTune	CPU scheduling priority: high, medium, low. New attribute added in E0930.	string
memoryTune	Memory resource priority: high, medium, low. New attribute added in E0930.	string
nspheretoolStatus	NSpheretools status. New attribute added in E0930.	integer(int32)
displayType	Console type: VNC, SPICE. New attribute added in E0930.	string
existPrealloc	Whether pre-allocation (zeroed or lazy zeroed) exists. New attribute added in E0930.	boolean
existRaw	Whether raw format exists. New attribute added in E0930.	boolean
hugepage	Whether huge pages are enabled. New attribute added in E0930.	boolean
ioTune	I/O priority: high, medium, low. New attribute added in E0930.	string
vncProxy	Whether VNC proxy is enabled. New attribute added in E0930.	string
vncport	VNC port. New attribute added in E0930.	integer(int32)
vnuma	Whether vNUMA is enabled. New attribute added in E0930.	boolean
pae	Whether PAE is enabled	boolean
osha	Blue-screen fault policy. 0: no action, 1: fault restart, 2: fault migration.	integer(int32)
osVersion	Operating system version	string
timeSync	Whether time sync is enabled	boolean
clockSetting	Clock configuration	string
ioWeight	I/O priority. 500: high, 300: medium, 200: low.	integer(int32)
autoMigrate	Whether auto-migration is enabled	boolean
autoTools	Whether tools are installed automatically	boolean
nspheretoolsType	NSpheretools type. Allowed values: virtio (Virtio serial), serial (plain serial).	string
enableIntegrityCheck	Whether integrity check is enabled	boolean
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	boolean
haManage	Whether managed by HA	boolean
priority	VM startup priority. -1: default, 0: low, 1: medium, 2: high.	integer(int32)
system	System type. 0: Windows, 1: Linux, 2: BSD.	integer(int32)
machineVersion	Hardware version	string
status	VM status	string
existController	Existing controller list	array	string
vmPriority	VM priority	integer(int32)
seccomp	VM escape protection. enable: on; null or disable: off.	string
autonuma	VM automatic NUMA binding. enable: on; disable or null: off.	string
cpuExclusive	VM CPU exclusive. numa: CPU exclusive enabled; disable: off.	string
numaBalance	VM NUMA smart scheduling. enable: on; disable or null: off.	string
emulator	Emulator path. New attribute added in E0930.	string
enableMultiQueue	Whether multi-queue acceleration is enabled. New attribute added in E0930.	boolean
cpu	CPU info	ApiDomainCPUInfoVO	ApiDomainCPUInfoVO
curValue	Current vCPU count	integer(int32)
cpuSocket	CPU socket count	integer(int32)
cpuCore	Cores per socket	integer(int32)
maxValue	Maximum vCPU count	integer(int32)
maxCpuSocket	Maximum CPU sockets	integer(int32)
rdt	RDT configuration	string
cpuFeature	When true and cpuMode=host-model, feature tags are added under cpu.	boolean
enableIncreaseCPU	Whether online CPU add/remove is allowed	boolean
hostValue	Host CPU count	integer(int32)
cpuShares	VM CPU scheduling priority. High = 1024, Medium = 512, Low = 256.	integer(int32)
cpuMode	CPU working mode. custom: compatible mode; host-model: host-match mode; host-passthrough: passthrough mode; emc: EMC mode.	string
cpuModel	CPU model. 10: Intel@ Merom Generation, 20: Intel@ Penryn Generation, 30: Intel@ Nehalem Generation, 40: Intel@ Westmere Generation, 50: Intel@ SandyBridge Generation, 60: Intel@ IvyBridge Generation, 70: Intel@ Haswell Generation, 80: Intel@ Broadwell Generation, 90: Intel@ Skylake-Client Generation, 100: Intel@ Skylake-Server Generation, 110: Intel@ Cascadelake-Server Generation, 120: Intel@ Icelake-Client Generation, 130: Intel@ Icelake-Server Generation, 10010: AMD Opteron Generation 1, 10020: AMD Opteron Generation 2, 10030: AMD phenom Generation, 10040: AMD Opteron Generation 3, 10050: AMD Opteron Generation 4, 10060: AMD Opteron Generation 5, 10070: AMD EPYC Generation.	integer(int32)
cpuArch	CPU architecture	string
cpuGuarantee	CPU reservation (MHz). 0 means no reservation.	integer(int64)
cpuGuaranMaxRate	Maximum CPU reservation	integer(int64)
cpuGuaranMinRate	Minimum CPU reservation	integer(int64)
cpuQuota	CPU limit value	number(double)
cpuQuotaUnit	CPU limit unit	string
cpuQuotaType	CPU limit type. 0: per-CPU limit, 1: whole-VM limit.	integer(int32)
cpuMinRate	Minimum CPU frequency	integer(int64)
cpuMaxRate	Maximum CPU frequency	integer(int64)
cpuMin	Minimum CPU cores	number(double)
cpuMax	Maximum CPU cores	number(double)
bindPhysicalCpu	CPU binding info	array	ApiBindCPUInfoVO
vcpu	vCPU number	integer(int32)
cpuset	Bound physical CPU set	string
mem	Memory info	ApiDomainMemoryDetailVO	ApiDomainMemoryDetailVO
curValue	Current memory size	number
curMemoryUnit	Current memory unit	string
maxValue	Maximum available memory (host memory size)	integer(int64)
maxMemory	Maximum allocatable memory. If the VM is online, the lesser of 16 times the original VM memory and host memory; if powered off, host memory.	integer(int64)
memoryLocked	Memory reservation percentage. 0-100.	integer(int32)
memoryPriority	Memory resource priority. 0: low, 50: medium, 100: high.	integer(int32)
memLimit	Memory limit	number(double)
memLimitUnit	Memory limit unit	string
autoMem	Whether memory overcommit is enabled	boolean
hotMem	Whether memory hot-add is enabled	boolean
hugepage	Whether huge pages are enabled	boolean
boot	Boot configuration	ApiDomainBootDetailVO	ApiDomainBootDetailVO
autoRun	Whether to auto-start. 0: no, 1: yes. Default 0.	boolean
bootFirmware	Boot firmware type. 0: BIOS (B), 1: EFI (E).	integer(int32)
bootList	Boot device info	array	ApiBootDevVO
bootdev	Boot device identifier	string
bootDevName	Boot device name	string
order	Boot order	integer(int32)
diskList	Disk info	array	ApiDomainDetailDiskInfoVO
diskIOMode	Disk I/O mode. Allowed values: native, threads, io_uring.	string
targetBus	Disk bus type. ide: IDE disk; usb: USB disk; virtio: high-speed disk; virtioScsi: high-speed SCSI disk.	string
dispName	Display name	string
diskSecret	Whether disk encryption is enabled	boolean
serial	Serial number	string
unmap	Whether UNMAP is enabled	boolean
enableRbd		boolean
srcPathAll	Full disk source path	string
srcPath	Disk source path. If the path exceeds 30 characters, the excess is truncated with an ellipsis.	string
backupBlock	Backup block info	string
enableModify	Whether modification is allowed	boolean
usage	Utilization (percentage)	number(double)
type	Storage volume type. file: file; block: block device; ultra: ubd. When the storage type is network, disk encryption is not supported, cache mode supports only none|directsync, ultra mode is not supported, existing files are not supported; driveType must be raw, mode must be 2, clustersize must be 262144, diskIOMode must be null, diskMode must be subordinate, and priority must be 2.	string
size	Disk size (MB)	number(double)
allocation	Used space (MB)	integer(int64)
minValue	Minimum configurable size (MB)	number(double)
maxValue	Maximum configurable size (MB)	number(double)
poolName	Storage pool name	string
poolType	Storage pool type. dir: local file directory / local file directory (high-speed); netfs: NFS network file system; fs: shared file system; cifs: Windows shared directory; logical: LVM logical volume; iscsi: iSCSI network storage; block: FC network storage; scsi: SCSI storage; glusterfs: GlusterFS file system.	string
showSize	Displayed size	number(double)
showUnit	Displayed unit	string
format	Disk format. qcow2: smart, raw: high-speed, luks: encrypted.	string
clustersize	Cluster size	string
enableEditDisk	Whether the disk can be edited	boolean
enableConverFmt	Whether format conversion is allowed	boolean
l2cache	Whether L2 cache is enabled	boolean
diskMode	Disk mode. subordinate: dependent; independent-persistent: independent-persistent.	string
enableEditDiskMode	Whether the disk mode can be modified	boolean
cacheModel	Disk cache mode. none: L1 virtual cache; writeback: L2 virtual cache; writethrough: L1 physical cache; directsync: direct I/O.	string
cacheFile	Cache file path	string
mode	Disk pre-allocation mode. 0: lazy zeroed, 1: zeroed, 2: thin.	integer(int32)
readBytesSec	Read bandwidth limit (KB/s)	integer(int64)
writeBytesSec	Write bandwidth limit (KB/s)	integer(int64)
readIopsSec	Read IOPS limit	integer(int64)
writeIopsSec	Write IOPS limit	integer(int64)
hotPluggable	Whether hot-plug is supported	boolean
iothreads	Whether I/O threads are used	boolean
readonly	Whether read-only	boolean
share	Whether the disk is shared	boolean
deviceName	Front-end device name	string
floppyList	Base storage device info	array	ApiDomainBasicStorageVO
srcPathAll	Full source path	string
srcPath	Source path. If the path exceeds 30 characters, the excess is truncated with an ellipsis.	string
deviceName	Device name	string
deviceBus	Device bus type. "ide" for CD-ROM, "fdc" for floppy.	string
cdromList	Base storage device info	array	ApiDomainBasicStorageVO
srcPathAll	Full source path	string
srcPath	Source path. If the path exceeds 30 characters, the excess is truncated with an ellipsis.	string
deviceName	Device name	string
deviceBus	Device bus type. "ide" for CD-ROM, "fdc" for floppy.	string
sriovNetworkList	SR-IOV vNIC info	array	ApiDomainSriovNicInfoVO
location	Physical location	string
ethName	vNIC name	string
driverType	SR-IOV driver type. When the network type is SR-IOV, the driver type is vfio.	string
mac	MAC address	string
oldMac	Old MAC address	string
vlan	VLAN	string
resPoolName	Resource pool name	string
resPoolId	Resource pool ID	integer(int64)
networkList	VM network info	array	ApiDomainNetworkInfoVO
domainId	VM ID	integer(int64)
title	VM display name. New attribute added in E0930.	string
vmUuid	VM UUID	string
mac	vNIC MAC address	string
ipAddr	vNIC IP address	string
ipv6	vNIC IPv6 address	string
vsName	vSwitch name	string
mode	VM vNIC forwarding mode. Allowed values: dvs (corresponds to vSwitch forwarding mode VXLAN (SDN)), veb.	string
maskAddr	Subnet mask	string
mtu	MTU value	integer(int64)
vlan	VLAN value	integer(int32)
netType	vNIC type. 0: bridge, 1: NAT, 2: no network, 3: physical passthrough, 4: SR-IOV. New attribute added in E0930.	integer(int32)
deviceModel	Driver model (rtl8139, virtio, e1000). New attribute added in E0930.	string
isKernelAccelerated	Kernel acceleration. Effective when the vNIC driver is virtio. 1: accelerated, 0: not. New attribute added in E0930.	integer(int32)
vsMode	vSwitch forwarding mode. 0: veb, 1: vepa, 2: multi-channel, 3: distributed. New attribute added in E0930.	integer(int32)
virtualport	Whether vport is configured. New attribute added in E0930.	boolean
inAvgBandwidth	Inbound average bandwidth, in Kbps	integer(int64)
inBurst	Inbound burst buffer size, in KBytes	integer(int64)
outAvgBandwidth	Outbound average bandwidth, in Kbps	integer(int64)
outBurst	Outbound burst buffer size, in KBytes	integer(int64)
limitInBound	Whether inbound traffic limit is enabled	boolean
limitOutBound	Whether outbound traffic limit is enabled	boolean
gateway	Gateway address	string
dns	Primary DNS server	string
secondDns	Secondary DNS server	string
ipv4Dhcp	Whether IPv4 DHCP is enabled	boolean
bindIp	Whether IPv4 is bound	boolean
ipv6PrefixLength	IPv6 prefix length	integer(int32)
ipv6Gateway	IPv6 default gateway	string
ipv6Dns	IPv6 primary DNS server	string
ipv6SecondDns	IPv6 secondary DNS server	string
ipv6Mode	IPv6 mode	string
ipv6Dhcp	Whether IPv6 DHCP is enabled	boolean
bindIpv6	Whether IPv6 is bound	boolean
profileId	Network policy template ID	integer(int64)
profileName	Network policy template name	string
portgroupUUID	VXLAN port group UUID	string
firewalls	Virtual firewall rule	array	ApiDomainFirewallVO
id	Rule ID	integer(int64)
title	Rule name	string
ruleAction	Firewall type. 0: blacklist, 1: whitelist.	integer(int32)
firewallDefaultAction	VM firewall default action. -1: allow, 0: deny.	integer(int32)
vlanTrunkId	VLAN policy ID	string
vlanTrunkName	VLAN policy name	string
isDpdk	Whether it is a DPDK switch. New attribute added in E0930.	boolean
tabletList	Tablet device	array	ApiDomainTabletVO
model	Cursor movement mode	string
bus	Bus type. Allowed values: usb.	string
mouseList	Mouse device	array	ApiDomainMouseVO
model	Mouse movement mode	string
bus	Bus type. Allowed values: ps2, usb.	string
displayList	Display device	array	ApiDomainDisplayDetailVO
type	Display type. Allowed values: "vnc", "spice".	string
address	Device address	string
port	Port number	string
portIpv6	IPv6 port	string
password	Access password	string
kayboardMap	Keyboard mapping	string
enableVncProxy	Whether VNC proxy is enabled	boolean
enableSpiceCompress	Whether SPICE compression is enabled	boolean
vncIp	VNC IP	string
vncUsername	VNC username	string
vncPwd	VNC password	string
vncPasswdMode	VNC password mode	string
videoList	Video device	array	ApiDomainVideoDetailVO
devType	Device type. Allowed values: Vga, Qxl, Virtio, Cirrus.	string
storage	Video memory size	integer(int32)
heads	Number of display heads	string
number	Device index	integer(int32)
pciView	PCI view info	string
soundList	Sound card device	array	ApiDomainSoundVO
type	Sound card type. Allowed values: ac97, ich6.	string
encryptCardList	Encryption card device	array	ApiDomainEncryptCardDetailVO
bus	Bus number	string
slot	Slot number	string
function	Function number	string
pciName	PCI name	string
address	PCI address	string
pciList	PCI device	array	ApiDomainPCIDetailVO
driver	Driver type. Allowed values: KVM, VFIO.	string
vendor	Vendor	string
product	Product	string
ethName	NIC name	string
productId	Product ID	string
vendorId	Vendor ID	string
bus	Bus number	string
slot	Slot number	string
function	Function number	string
pciName	PCI name	string
name	Device name	string
usbList	USB device	array	ApiDomainUSBDetailVO
product	Product name	string
name	Device name	string
vendor	Vendor name	string
productId	Product ID	string
vendorId	Vendor ID	string
bus	Bus number	string
device	Device number	string
usbController	USB controller version. 1: USB 1.0, 2: USB 2.0, 3: USB 3.0.	string
serialList	Serial device	array	ApiDomainSerialInfoVO
type	Serial type. Allowed values: pty, dev.	string
targetPort	Target port	integer(int32)
mode	Working mode	string
devPath	Device path	string
connHost	Connect host	string
connPort	Connect port	string
bindIp	Bound IP	string
bindPort	Bind port	string
monitor	Whether it is a monitoring channel	boolean
isSerialLog	Whether serial logging is enabled	boolean
numa	NUMA configuration	ApiDomainNumaDetailVO	ApiDomainNumaDetailVO
nodeSize	NUMA node count	integer(int32)
nodeSet	NUMA node set	string
associate	Whether associated with CPU	boolean
safety	Security policy info	ApiDomainSafetyInfoVO	ApiDomainSafetyInfoVO
spiceTls	Whether SPICE TLS is enabled	boolean
spiceChannels	SPICE channel list	array	string
redirUsb	USB redirection count	integer(int32)
ifSupSpice	Whether SPICE is supported	boolean
enableRedirectUsb	Whether USB redirection is enabled	boolean
enableAntivirus	Whether antivirus is enabled	boolean
secretLevel	Classification level. 4: top secret, 3: secret, 2: confidential, 1: internal.	integer(int32)
supportAntivirus	Whether antivirus is supported	boolean
antivirusType	Antivirus vendor. 0: not installed, 1: Asiainfo, 2: Qi-Anxin (formerly 360).	string
securityId	Security policy ID	integer(int32)
securityName	Security policy name	string
publicCloudId	Owning public-cloud ID	integer(int64)
vtpm	Virtual TPM configuration	string
tpm	TPM configuration	string
gpu	GPU configuration	ApiDomainGPUVO	ApiDomainGPUVO
resPoolId	GPU resource pool ID	integer(int64)
resPool	GPU resource pool name	string
businessTemId	Business template ID	integer(int64)
businessTem	Business template name	string
deviceDriver	GPU driver type	string
count	GPU count	integer(int32)
shared	Share ratio	integer(int32)
maxCount	Maximum available GPU count	integer(int32)
frl	Frame rate limit (FRL)	integer(int32)
watchdog	Watchdog configuration	ApiDomainWatchdogVO	ApiDomainWatchdogVO
model	Watchdog model	string
action	Action. Allowed values: "reset" (restart), "poweroff" (power off), "migrate" (migrate).	string
netUsbList	Network USB device	array	ApiDomainNetUsbDetailVO
host	Host IP	string
service	Service port	integer(int32)
port	Port number	integer(int32)
manufacturer	Vendor name	string
product	Product name	string
productId	Product ID	string
vendorId	Vendor ID	string
usbController	USB controller	string
path	Device path	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"id": null,
"domainName": null,
"uuid": null,
"title": null,
"desc": null,
"hostId": null,
"clusterId": null,
"antivirusConfigured": true,
"securityModeEnable": null,
"clusterInSafeArea": true,
"manageExistVm": null,
"vmType": null,
"videoType": [],
"kaasVm": null,
"antivirusType": null,
"isEncrypt": true,
"secretLevel": null,
"enableUltra": null,
"hostStatus": null,
"configVNC": true,
"summary": {
"cvkKernelType": null,
"manager": null,
"architecture": null,
"acpi": true,
"apic": true,
"cpuTune": null,
"memoryTune": null,
"nspheretoolStatus": null,
"displayType": null,
"existPrealloc": true,
"existRaw": true,
"hugepage": true,
"ioTune": null,
"vncProxy": null,
"vncport": null,
"vnuma": true,
"pae": true,
"osha": null,
"osVersion": null,
"timeSync": true,
"clockSetting": null,
"ioWeight": null,
"autoMigrate": true,
"autoTools": true,
"nspheretoolsType": null,
"enableIntegrityCheck": true,
"protectModel": true,
"haManage": true,
"priority": null,
"system": null,
"machineVersion": null,
"status": null,
"existController": [],
"vmPriority": null,
"seccomp": null,
"autonuma": null,
"cpuExclusive": null,
"numaBalance": null,
"emulator": null,
"enableMultiQueue": true
},
"cpu": {
"curValue": null,
"cpuSocket": null,
"cpuCore": null,
"maxValue": null,
"maxCpuSocket": null,
"rdt": null,
"cpuFeature": true,
"enableIncreaseCPU": true,
"hostValue": null,
"cpuShares": null,
"cpuMode": null,
"cpuModel": null,
"cpuArch": null,
"cpuGuarantee": null,
"cpuGuaranMaxRate": null,
"cpuGuaranMinRate": null,
"cpuQuota": null,
"cpuQuotaUnit": null,
"cpuQuotaType": null,
"cpuMinRate": null,
"cpuMaxRate": null,
"cpuMin": null,
"cpuMax": null,
"bindPhysicalCpu": [
{
"vcpu": null,
"cpuset": null
}
]
},
"mem": {
"curValue": null,
"curMemoryUnit": null,
"maxValue": null,
"maxMemory": null,
"memoryLocked": null,
"memoryPriority": null,
"memLimit": null,
"memLimitUnit": null,
"autoMem": true,
"hotMem": true,
"hugepage": true
},
"boot": {
"autoRun": true,
"bootFirmware": null,
"bootList": [
{
"bootdev": null,
"bootDevName": null,
"order": null
}
]
},
"diskList": [
{
"diskIOMode": null,
"targetBus": null,
"dispName": null,
"diskSecret": true,
"serial": null,
"unmap": true,
"enableRbd": true,
"srcPathAll": null,
"srcPath": null,
"backupBlock": null,
"enableModify": true,
"usage": null,
"type": null,
"size": null,
"allocation": null,
"minValue": null,
"maxValue": null,
"poolName": null,
"poolType": null,
"showSize": null,
"showUnit": null,
"format": null,
"clustersize": null,
"enableEditDisk": true,
"enableConverFmt": true,
"l2cache": true,
"diskMode": null,
"enableEditDiskMode": true,
"cacheModel": null,
"cacheFile": null,
"mode": null,
"readBytesSec": null,
"writeBytesSec": null,
"readIopsSec": null,
"writeIopsSec": null,
"hotPluggable": true,
"iothreads": true,
"readonly": true,
"share": true,
"deviceName": null
}
],
"floppyList": [
{
"srcPathAll": null,
"srcPath": null,
"deviceName": null,
"deviceBus": null
}
],
"cdromList": [
{
"srcPathAll": null,
"srcPath": null,
"deviceName": null,
"deviceBus": null
}
],
"sriovNetworkList": [
{
"location": null,
"ethName": null,
"driverType": null,
"mac": null,
"oldMac": null,
"vlan": null,
"resPoolName": null,
"resPoolId": null
}
],
"networkList": [
{
"domainId": null,
"title": null,
"vmUuid": null,
"mac": null,
"ipAddr": null,
"ipv6": null,
"vsName": null,
"mode": null,
"maskAddr": null,
"mtu": null,
"vlan": null,
"netType": null,
"deviceModel": null,
"isKernelAccelerated": null,
"vsMode": null,
"virtualport": true,
"inAvgBandwidth": null,
"inBurst": null,
"outAvgBandwidth": null,
"outBurst": null,
"limitInBound": true,
"limitOutBound": true,
"gateway": null,
"dns": null,
"secondDns": null,
"ipv4Dhcp": true,
"bindIp": true,
"ipv6PrefixLength": null,
"ipv6Gateway": null,
"ipv6Dns": null,
"ipv6SecondDns": null,
"ipv6Mode": null,
"ipv6Dhcp": true,
"bindIpv6": true,
"profileId": null,
"profileName": null,
"portgroupUUID": null,
"firewalls": [
{
"id": null,
"title": null,
"ruleAction": null
}
],
"firewallDefaultAction": null,
"vlanTrunkId": null,
"vlanTrunkName": null,
"isDpdk": true
}
],
"tabletList": [
{
"model": null,
"bus": null
}
],
"mouseList": [
{
"model": null,
"bus": null
}
],
"displayList": [
{
"type": null,
"address": null,
"port": null,
"portIpv6": null,
"password": null,
"kayboardMap": null,
"enableVncProxy": true,
"enableSpiceCompress": true,
"vncIp": null,
"vncUsername": null,
"vncPwd": null,
"vncPasswdMode": null
}
],
"videoList": [
{
"devType": null,
"storage": null,
"heads": null,
"number": null,
"pciView": null
}
],
"soundList": [
{
"type": null
}
],
"encryptCardList": [
{
"bus": null,
"slot": null,
"function": null,
"pciName": null,
"address": null
}
],
"pciList": [
{
"driver": null,
"vendor": null,
"product": null,
"ethName": null,
"productId": null,
"vendorId": null,
"bus": null,
"slot": null,
"function": null,
"pciName": null,
"name": null
}
],
"usbList": [
{
"product": null,
"name": null,
"vendor": null,
"productId": null,
"vendorId": null,
"bus": null,
"device": null,
"usbController": null
}
],
"serialList": [
{
"type": null,
"targetPort": null,
"mode": null,
"devPath": null,
"connHost": null,
"connPort": null,
"bindIp": null,
"bindPort": null,
"monitor": true,
"isSerialLog": true
}
],
"numa": {
"nodeSize": null,
"nodeSet": null,
"associate": true
},
"safety": {
"spiceTls": true,
"spiceChannels": [],
"redirUsb": null,
"ifSupSpice": true,
"enableRedirectUsb": true,
"enableAntivirus": true,
"secretLevel": null,
"supportAntivirus": true,
"antivirusType": null,
"securityId": null,
"securityName": null,
"publicCloudId": null
},
"vtpm": null,
"tpm": null,
"gpu": {
"resPoolId": null,
"resPool": null,
"businessTemId": null,
"businessTem": null,
"deviceDriver": null,
"count": null,
"shared": null,
"maxCount": null,
"frl": null
},
"watchdog": {
"model": null,
"action": null
},
"netUsbList": [
{
"host": null,
"service": null,
"port": null,
"manufacturer": null,
"product": null,
"productId": null,
"vendorId": null,
"usbController": null,
"path": null
}
]
}
]
}

2.8.17 Batch query VM details by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/detail/list

API description

Batch query VM details by ID/UUID list. The ID and UUID lists cannot both be empty. If both are provided, the ID list takes precedence.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"idList": [
1,
2,
3
],
"uuidList": [
"uuid-1",
"uuid-2"
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainBatchQueryDTO	VM ID/UUID list request entity	body	true	ApiDomainBatchQueryDTO	ApiDomainBatchQueryDTO
idList	VM ID list		false	array	integer(int64)
uuidList	VM UUID list		false	array	string

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainDetailVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainDetailVO
id	VM ID	integer(int64)
domainName	VM name	string
uuid	VM UUID	string
title	VM display name	string
desc	VM description. Maximum length 2048 characters.	string
hostId	VM host ID	integer(int64)
clusterId	VM cluster ID	integer(int64)
antivirusConfigured	Whether antivirus is configured	boolean
securityModeEnable	Whether CVM confidential mode is enabled. 0: disabled, 1: enabled.	string
clusterInSafeArea	Whether the cluster is in a security zone	boolean
manageExistVm	Whether the VM is managed by BigCloud. 0: not managed, 1: managed.	integer(int32)
vmType	VM type. Low-order 2 bytes: VM category. Default 1 (standard VM). 101-200 are VDI-defined. High-order 2 bytes: VM type; bits 0-31 from low to high, and the high 2 bytes span bits 16-31 with bits 17 and 16 used. 00: normal VM (shown as standard VM), 01: disaster-recovery source VM, 10: disaster-recovery target VM. Other bits unused.	integer(int32)
videoType	GPU type list. Allowed values: vga, qxl, virtio, cirrus. New attribute added in E0930.	array	string
kaasVm	Whether the VM is a K8s cluster node. 0: no, 1: yes.	integer(int32)
antivirusType	Antivirus vendor. 0: not installed, 1: Asiainfo, 2: Qi-Anxin (formerly 360).	integer(int32)
isEncrypt	Whether encrypted	boolean
secretLevel	Classification level. 4: top secret, 3: secret, 2: confidential, 1: internal.	integer(int32)
enableUltra	Whether Ultra mode is enabled on the VM. 1: enabled; 0 or empty: disabled. Ultra VMs do not support the storage serial or clustersize parameters; targetBus must be virtio, driveType must be raw, and numaBalance cannot be enabled.	integer(int32)
hostStatus	VM host status. 0: abnormal, 1: normal, 5: isolated mode.	integer(int32)
configVNC	Whether VNC proxy parameters are configured	boolean
summary	VM summary	ApiDomainSummaryInfoVO	ApiDomainSummaryInfoVO
cvkKernelType	CVK kernel type in hexadecimal. The rightmost digit indicates CPU (0: x86, 1: arm), the second digit indicates OS (0: ubuntu, 1: centos, 2: h3linux, 3: tencentos).	integer(int32)
manager	VM hypervisor	string
architecture	CPU architecture, e.g. X86_64, X86.	string
acpi	Whether ACPI is enabled	boolean
apic	Whether APIC is enabled	boolean
cpuTune	CPU scheduling priority: high, medium, low. New attribute added in E0930.	string
memoryTune	Memory resource priority: high, medium, low. New attribute added in E0930.	string
nspheretoolStatus	NSpheretools status. New attribute added in E0930.	integer(int32)
displayType	Console type: VNC, SPICE. New attribute added in E0930.	string
existPrealloc	Whether pre-allocation (zeroed or lazy zeroed) exists. New attribute added in E0930.	boolean
existRaw	Whether raw format exists. New attribute added in E0930.	boolean
hugepage	Whether huge pages are enabled. New attribute added in E0930.	boolean
ioTune	I/O priority: high, medium, low. New attribute added in E0930.	string
vncProxy	Whether VNC proxy is enabled. New attribute added in E0930.	string
vncport	VNC port. New attribute added in E0930.	integer(int32)
vnuma	Whether vNUMA is enabled. New attribute added in E0930.	boolean
pae	Whether PAE is enabled	boolean
osha	Blue-screen fault policy. 0: no action, 1: fault restart, 2: fault migration.	integer(int32)
osVersion	Operating system version	string
timeSync	Whether time sync is enabled	boolean
clockSetting	Clock configuration	string
ioWeight	I/O priority. 500: high, 300: medium, 200: low.	integer(int32)
autoMigrate	Whether auto-migration is enabled	boolean
autoTools	Whether tools are installed automatically	boolean
nspheretoolsType	NSpheretools type. Allowed values: virtio (Virtio serial), serial (plain serial).	string
enableIntegrityCheck	Whether integrity check is enabled	boolean
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	boolean
haManage	Whether managed by HA	boolean
priority	VM startup priority. -1: default, 0: low, 1: medium, 2: high.	integer(int32)
system	System type. 0: Windows, 1: Linux, 2: BSD.	integer(int32)
machineVersion	Hardware version	string
status	VM status	string
existController	Existing controller list	array	string
vmPriority	VM priority	integer(int32)
seccomp	VM escape protection. enable: on; null or disable: off.	string
autonuma	VM automatic NUMA binding. enable: on; disable or null: off.	string
cpuExclusive	VM CPU exclusive. numa: CPU exclusive enabled; disable: off.	string
numaBalance	VM NUMA smart scheduling. enable: on; disable or null: off.	string
emulator	Emulator path. New attribute added in E0930.	string
enableMultiQueue	Whether multi-queue acceleration is enabled. New attribute added in E0930.	boolean
cpu	CPU info	ApiDomainCPUInfoVO	ApiDomainCPUInfoVO
curValue	Current vCPU count	integer(int32)
cpuSocket	CPU socket count	integer(int32)
cpuCore	Cores per socket	integer(int32)
maxValue	Maximum vCPU count	integer(int32)
maxCpuSocket	Maximum CPU sockets	integer(int32)
rdt	RDT configuration	string
cpuFeature	When true and cpuMode=host-model, feature tags are added under cpu.	boolean
enableIncreaseCPU	Whether online CPU add/remove is allowed	boolean
hostValue	Host CPU count	integer(int32)
cpuShares	VM CPU scheduling priority. High = 1024, Medium = 512, Low = 256.	integer(int32)
cpuMode	CPU working mode. custom: compatible mode; host-model: host-match mode; host-passthrough: passthrough mode; emc: EMC mode.	string
cpuModel	CPU model. 10: Intel@ Merom Generation, 20: Intel@ Penryn Generation, 30: Intel@ Nehalem Generation, 40: Intel@ Westmere Generation, 50: Intel@ SandyBridge Generation, 60: Intel@ IvyBridge Generation, 70: Intel@ Haswell Generation, 80: Intel@ Broadwell Generation, 90: Intel@ Skylake-Client Generation, 100: Intel@ Skylake-Server Generation, 110: Intel@ Cascadelake-Server Generation, 120: Intel@ Icelake-Client Generation, 130: Intel@ Icelake-Server Generation, 10010: AMD Opteron Generation 1, 10020: AMD Opteron Generation 2, 10030: AMD phenom Generation, 10040: AMD Opteron Generation 3, 10050: AMD Opteron Generation 4, 10060: AMD Opteron Generation 5, 10070: AMD EPYC Generation.	integer(int32)
cpuArch	CPU architecture	string
cpuGuarantee	CPU reservation (MHz). 0 means no reservation.	integer(int64)
cpuGuaranMaxRate	Maximum CPU reservation	integer(int64)
cpuGuaranMinRate	Minimum CPU reservation	integer(int64)
cpuQuota	CPU limit value	number(double)
cpuQuotaUnit	CPU limit unit	string
cpuQuotaType	CPU limit type. 0: per-CPU limit, 1: whole-VM limit.	integer(int32)
cpuMinRate	Minimum CPU frequency	integer(int64)
cpuMaxRate	Maximum CPU frequency	integer(int64)
cpuMin	Minimum CPU cores	number(double)
cpuMax	Maximum CPU cores	number(double)
bindPhysicalCpu	CPU binding info	array	ApiBindCPUInfoVO
vcpu	vCPU number	integer(int32)
cpuset	Bound physical CPU set	string
mem	Memory info	ApiDomainMemoryDetailVO	ApiDomainMemoryDetailVO
curValue	Current memory size	number
curMemoryUnit	Current memory unit	string
maxValue	Maximum available memory (host memory size)	integer(int64)
maxMemory	Maximum allocatable memory. If the VM is online, the lesser of 16 times the original VM memory and host memory; if powered off, host memory.	integer(int64)
memoryLocked	Memory reservation percentage. 0-100.	integer(int32)
memoryPriority	Memory resource priority. 0: low, 50: medium, 100: high.	integer(int32)
memLimit	Memory limit	number(double)
memLimitUnit	Memory limit unit	string
autoMem	Whether memory overcommit is enabled	boolean
hotMem	Whether memory hot-add is enabled	boolean
hugepage	Whether huge pages are enabled	boolean
boot	Boot configuration	ApiDomainBootDetailVO	ApiDomainBootDetailVO
autoRun	Whether to auto-start. 0: no, 1: yes. Default 0.	boolean
bootFirmware	Boot firmware type. 0: BIOS (B), 1: EFI (E).	integer(int32)
bootList	Boot device info	array	ApiBootDevVO
bootdev	Boot device identifier	string
bootDevName	Boot device name	string
order	Boot order	integer(int32)
diskList	Disk info	array	ApiDomainDetailDiskInfoVO
diskIOMode	Disk I/O mode. Allowed values: native, threads, io_uring.	string
targetBus	Disk bus type. ide: IDE disk; usb: USB disk; virtio: high-speed disk; virtioScsi: high-speed SCSI disk.	string
dispName	Display name	string
diskSecret	Whether disk encryption is enabled	boolean
serial	Serial number	string
unmap	Whether UNMAP is enabled	boolean
enableRbd		boolean
srcPathAll	Full disk source path	string
srcPath	Disk source path. If the path exceeds 30 characters, the excess is truncated with an ellipsis.	string
backupBlock	Backup block info	string
enableModify	Whether modification is allowed	boolean
usage	Utilization (percentage)	number(double)
type	Storage volume type. file: file; block: block device; ultra: ubd. When the storage type is network, disk encryption is not supported, cache mode supports only none|directsync, ultra mode is not supported, existing files are not supported; driveType must be raw, mode must be 2, clustersize must be 262144, diskIOMode must be null, diskMode must be subordinate, and priority must be 2.	string
size	Disk size (MB)	number(double)
allocation	Used space (MB)	integer(int64)
minValue	Minimum configurable size (MB)	number(double)
maxValue	Maximum configurable size (MB)	number(double)
poolName	Storage pool name	string
poolType	Storage pool type. dir: local file directory / local file directory (high-speed); netfs: NFS network file system; fs: shared file system; cifs: Windows shared directory; logical: LVM logical volume; iscsi: iSCSI network storage; block: FC network storage; scsi: SCSI storage; glusterfs: GlusterFS file system.	string
showSize	Displayed size	number(double)
showUnit	Displayed unit	string
format	Disk format. qcow2: smart, raw: high-speed, luks: encrypted.	string
clustersize	Cluster size	string
enableEditDisk	Whether the disk can be edited	boolean
enableConverFmt	Whether format conversion is allowed	boolean
l2cache	Whether L2 cache is enabled	boolean
diskMode	Disk mode. subordinate: dependent; independent-persistent: independent-persistent.	string
enableEditDiskMode	Whether the disk mode can be modified	boolean
cacheModel	Disk cache mode. none: L1 virtual cache; writeback: L2 virtual cache; writethrough: L1 physical cache; directsync: direct I/O.	string
cacheFile	Cache file path	string
mode	Disk pre-allocation mode. 0: lazy zeroed, 1: zeroed, 2: thin.	integer(int32)
readBytesSec	Read bandwidth limit (KB/s)	integer(int64)
writeBytesSec	Write bandwidth limit (KB/s)	integer(int64)
readIopsSec	Read IOPS limit	integer(int64)
writeIopsSec	Write IOPS limit	integer(int64)
hotPluggable	Whether hot-plug is supported	boolean
iothreads	Whether I/O threads are used	boolean
readonly	Whether read-only	boolean
share	Whether the disk is shared	boolean
deviceName	Front-end device name	string
floppyList	Base storage device info	array	ApiDomainBasicStorageVO
srcPathAll	Full source path	string
srcPath	Source path. If the path exceeds 30 characters, the excess is truncated with an ellipsis.	string
deviceName	Device name	string
deviceBus	Device bus type. "ide" for CD-ROM, "fdc" for floppy.	string
cdromList	Base storage device info	array	ApiDomainBasicStorageVO
srcPathAll	Full source path	string
srcPath	Source path. If the path exceeds 30 characters, the excess is truncated with an ellipsis.	string
deviceName	Device name	string
deviceBus	Device bus type. "ide" for CD-ROM, "fdc" for floppy.	string
sriovNetworkList	SR-IOV vNIC info	array	ApiDomainSriovNicInfoVO
location	Physical location	string
ethName	vNIC name	string
driverType	SR-IOV driver type. When the network type is SR-IOV, the driver type is vfio.	string
mac	MAC address	string
oldMac	Old MAC address	string
vlan	VLAN	string
resPoolName	Resource pool name	string
resPoolId	Resource pool ID	integer(int64)
networkList	VM network info	array	ApiDomainNetworkInfoVO
domainId	VM ID	integer(int64)
title	VM display name. New attribute added in E0930.	string
vmUuid	VM UUID	string
mac	vNIC MAC address	string
ipAddr	vNIC IP address	string
ipv6	vNIC IPv6 address	string
vsName	vSwitch name	string
mode	VM vNIC forwarding mode. Allowed values: dvs (corresponds to vSwitch forwarding mode VXLAN (SDN)), veb.	string
maskAddr	Subnet mask	string
mtu	MTU value	integer(int64)
vlan	VLAN value	integer(int32)
netType	vNIC type. 0: bridge, 1: NAT, 2: no network, 3: physical passthrough, 4: SR-IOV. New attribute added in E0930.	integer(int32)
deviceModel	Driver model (rtl8139, virtio, e1000). New attribute added in E0930.	string
isKernelAccelerated	Kernel acceleration. Effective when the vNIC driver is virtio. 1: accelerated, 0: not. New attribute added in E0930.	integer(int32)
vsMode	vSwitch forwarding mode. 0: veb, 1: vepa, 2: multi-channel, 3: distributed. New attribute added in E0930.	integer(int32)
virtualport	Whether vport is configured. New attribute added in E0930.	boolean
inAvgBandwidth	Inbound average bandwidth, in Kbps	integer(int64)
inBurst	Inbound burst buffer size, in KBytes	integer(int64)
outAvgBandwidth	Outbound average bandwidth, in Kbps	integer(int64)
outBurst	Outbound burst buffer size, in KBytes	integer(int64)
limitInBound	Whether inbound traffic limit is enabled	boolean
limitOutBound	Whether outbound traffic limit is enabled	boolean
gateway	Gateway address	string
dns	Primary DNS server	string
secondDns	Secondary DNS server	string
ipv4Dhcp	Whether IPv4 DHCP is enabled	boolean
bindIp	Whether IPv4 is bound	boolean
ipv6PrefixLength	IPv6 prefix length	integer(int32)
ipv6Gateway	IPv6 default gateway	string
ipv6Dns	IPv6 primary DNS server	string
ipv6SecondDns	IPv6 secondary DNS server	string
ipv6Mode	IPv6 mode	string
ipv6Dhcp	Whether IPv6 DHCP is enabled	boolean
bindIpv6	Whether IPv6 is bound	boolean
profileId	Network policy template ID	integer(int64)
profileName	Network policy template name	string
portgroupUUID	VXLAN port group UUID	string
firewalls	Virtual firewall rule	array	ApiDomainFirewallVO
id	Rule ID	integer(int64)
title	Rule name	string
ruleAction	Firewall type. 0: blacklist, 1: whitelist.	integer(int32)
firewallDefaultAction	VM firewall default action. -1: allow, 0: deny.	integer(int32)
vlanTrunkId	VLAN policy ID	string
vlanTrunkName	VLAN policy name	string
isDpdk	Whether it is a DPDK switch. New attribute added in E0930.	boolean
tabletList	Tablet device	array	ApiDomainTabletVO
model	Cursor movement mode	string
bus	Bus type. Allowed values: usb.	string
mouseList	Mouse device	array	ApiDomainMouseVO
model	Mouse movement mode	string
bus	Bus type. Allowed values: ps2, usb.	string
displayList	Display device	array	ApiDomainDisplayDetailVO
type	Display type. Allowed values: "vnc", "spice".	string
address	Device address	string
port	Port number	string
portIpv6	IPv6 port	string
password	Access password	string
kayboardMap	Keyboard mapping	string
enableVncProxy	Whether VNC proxy is enabled	boolean
enableSpiceCompress	Whether SPICE compression is enabled	boolean
vncIp	VNC IP	string
vncUsername	VNC username	string
vncPwd	VNC password	string
vncPasswdMode	VNC password mode	string
videoList	Video device	array	ApiDomainVideoDetailVO
devType	Device type. Allowed values: Vga, Qxl, Virtio, Cirrus.	string
storage	Video memory size	integer(int32)
heads	Number of display heads	string
number	Device index	integer(int32)
pciView	PCI view info	string
soundList	Sound card device	array	ApiDomainSoundVO
type	Sound card type. Allowed values: ac97, ich6.	string
encryptCardList	Encryption card device	array	ApiDomainEncryptCardDetailVO
bus	Bus number	string
slot	Slot number	string
function	Function number	string
pciName	PCI name	string
address	PCI address	string
pciList	PCI device	array	ApiDomainPCIDetailVO
driver	Driver type. Allowed values: KVM, VFIO.	string
vendor	Vendor	string
product	Product	string
ethName	NIC name	string
productId	Product ID	string
vendorId	Vendor ID	string
bus	Bus number	string
slot	Slot number	string
function	Function number	string
pciName	PCI name	string
name	Device name	string
usbList	USB device	array	ApiDomainUSBDetailVO
product	Product name	string
name	Device name	string
vendor	Vendor name	string
productId	Product ID	string
vendorId	Vendor ID	string
bus	Bus number	string
device	Device number	string
usbController	USB controller version. 1: USB 1.0, 2: USB 2.0, 3: USB 3.0.	string
serialList	Serial device	array	ApiDomainSerialInfoVO
type	Serial type. Allowed values: pty, dev.	string
targetPort	Target port	integer(int32)
mode	Working mode	string
devPath	Device path	string
connHost	Connect host	string
connPort	Connect port	string
bindIp	Bound IP	string
bindPort	Bind port	string
monitor	Whether it is a monitoring channel	boolean
isSerialLog	Whether serial logging is enabled	boolean
numa	NUMA configuration	ApiDomainNumaDetailVO	ApiDomainNumaDetailVO
nodeSize	NUMA node count	integer(int32)
nodeSet	NUMA node set	string
associate	Whether associated with CPU	boolean
safety	Security policy info	ApiDomainSafetyInfoVO	ApiDomainSafetyInfoVO
spiceTls	Whether SPICE TLS is enabled	boolean
spiceChannels	SPICE channel list	array	string
redirUsb	USB redirection count	integer(int32)
ifSupSpice	Whether SPICE is supported	boolean
enableRedirectUsb	Whether USB redirection is enabled	boolean
enableAntivirus	Whether antivirus is enabled	boolean
secretLevel	Classification level. 4: top secret, 3: secret, 2: confidential, 1: internal.	integer(int32)
supportAntivirus	Whether antivirus is supported	boolean
antivirusType	Antivirus vendor. 0: not installed, 1: Asiainfo, 2: Qi-Anxin (formerly 360).	string
securityId	Security policy ID	integer(int32)
securityName	Security policy name	string
publicCloudId	Owning public-cloud ID	integer(int64)
vtpm	Virtual TPM configuration	string
tpm	TPM configuration	string
gpu	GPU configuration	ApiDomainGPUVO	ApiDomainGPUVO
resPoolId	GPU resource pool ID	integer(int64)
resPool	GPU resource pool name	string
businessTemId	Business template ID	integer(int64)
businessTem	Business template name	string
deviceDriver	GPU driver type	string
count	GPU count	integer(int32)
shared	Share ratio	integer(int32)
maxCount	Maximum available GPU count	integer(int32)
frl	Frame rate limit (FRL)	integer(int32)
watchdog	Watchdog configuration	ApiDomainWatchdogVO	ApiDomainWatchdogVO
model	Watchdog model	string
action	Action. Allowed values: "reset" (restart), "poweroff" (power off), "migrate" (migrate).	string
netUsbList	Network USB device	array	ApiDomainNetUsbDetailVO
host	Host IP	string
service	Service port	integer(int32)
port	Port number	integer(int32)
manufacturer	Vendor name	string
product	Product name	string
productId	Product ID	string
vendorId	Vendor ID	string
usbController	USB controller	string
path	Device path	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"id": null,
"domainName": null,
"uuid": null,
"title": null,
"desc": null,
"hostId": null,
"clusterId": null,
"antivirusConfigured": true,
"securityModeEnable": null,
"clusterInSafeArea": true,
"manageExistVm": null,
"vmType": null,
"videoType": [],
"kaasVm": null,
"antivirusType": null,
"isEncrypt": true,
"secretLevel": null,
"enableUltra": null,
"hostStatus": null,
"configVNC": true,
"summary": {
"cvkKernelType": null,
"manager": null,
"architecture": null,
"acpi": true,
"apic": true,
"cpuTune": null,
"memoryTune": null,
"nspheretoolStatus": null,
"displayType": null,
"existPrealloc": true,
"existRaw": true,
"hugepage": true,
"ioTune": null,
"vncProxy": null,
"vncport": null,
"vnuma": true,
"pae": true,
"osha": null,
"osVersion": null,
"timeSync": true,
"clockSetting": null,
"ioWeight": null,
"autoMigrate": true,
"autoTools": true,
"nspheretoolsType": null,
"enableIntegrityCheck": true,
"protectModel": true,
"haManage": true,
"priority": null,
"system": null,
"machineVersion": null,
"status": null,
"existController": [],
"vmPriority": null,
"seccomp": null,
"autonuma": null,
"cpuExclusive": null,
"numaBalance": null,
"emulator": null,
"enableMultiQueue": true
},
"cpu": {
"curValue": null,
"cpuSocket": null,
"cpuCore": null,
"maxValue": null,
"maxCpuSocket": null,
"rdt": null,
"cpuFeature": true,
"enableIncreaseCPU": true,
"hostValue": null,
"cpuShares": null,
"cpuMode": null,
"cpuModel": null,
"cpuArch": null,
"cpuGuarantee": null,
"cpuGuaranMaxRate": null,
"cpuGuaranMinRate": null,
"cpuQuota": null,
"cpuQuotaUnit": null,
"cpuQuotaType": null,
"cpuMinRate": null,
"cpuMaxRate": null,
"cpuMin": null,
"cpuMax": null,
"bindPhysicalCpu": [
{
"vcpu": null,
"cpuset": null
}
]
},
"mem": {
"curValue": null,
"curMemoryUnit": null,
"maxValue": null,
"maxMemory": null,
"memoryLocked": null,
"memoryPriority": null,
"memLimit": null,
"memLimitUnit": null,
"autoMem": true,
"hotMem": true,
"hugepage": true
},
"boot": {
"autoRun": true,
"bootFirmware": null,
"bootList": [
{
"bootdev": null,
"bootDevName": null,
"order": null
}
]
},
"diskList": [
{
"diskIOMode": null,
"targetBus": null,
"dispName": null,
"diskSecret": true,
"serial": null,
"unmap": true,
"enableRbd": true,
"srcPathAll": null,
"srcPath": null,
"backupBlock": null,
"enableModify": true,
"usage": null,
"type": null,
"size": null,
"allocation": null,
"minValue": null,
"maxValue": null,
"poolName": null,
"poolType": null,
"showSize": null,
"showUnit": null,
"format": null,
"clustersize": null,
"enableEditDisk": true,
"enableConverFmt": true,
"l2cache": true,
"diskMode": null,
"enableEditDiskMode": true,
"cacheModel": null,
"cacheFile": null,
"mode": null,
"readBytesSec": null,
"writeBytesSec": null,
"readIopsSec": null,
"writeIopsSec": null,
"hotPluggable": true,
"iothreads": true,
"readonly": true,
"share": true,
"deviceName": null
}
],
"floppyList": [
{
"srcPathAll": null,
"srcPath": null,
"deviceName": null,
"deviceBus": null
}
],
"cdromList": [
{
"srcPathAll": null,
"srcPath": null,
"deviceName": null,
"deviceBus": null
}
],
"sriovNetworkList": [
{
"location": null,
"ethName": null,
"driverType": null,
"mac": null,
"oldMac": null,
"vlan": null,
"resPoolName": null,
"resPoolId": null
}
],
"networkList": [
{
"domainId": null,
"title": null,
"vmUuid": null,
"mac": null,
"ipAddr": null,
"ipv6": null,
"vsName": null,
"mode": null,
"maskAddr": null,
"mtu": null,
"vlan": null,
"netType": null,
"deviceModel": null,
"isKernelAccelerated": null,
"vsMode": null,
"virtualport": true,
"inAvgBandwidth": null,
"inBurst": null,
"outAvgBandwidth": null,
"outBurst": null,
"limitInBound": true,
"limitOutBound": true,
"gateway": null,
"dns": null,
"secondDns": null,
"ipv4Dhcp": true,
"bindIp": true,
"ipv6PrefixLength": null,
"ipv6Gateway": null,
"ipv6Dns": null,
"ipv6SecondDns": null,
"ipv6Mode": null,
"ipv6Dhcp": true,
"bindIpv6": true,
"profileId": null,
"profileName": null,
"portgroupUUID": null,
"firewalls": [
{
"id": null,
"title": null,
"ruleAction": null
}
],
"firewallDefaultAction": null,
"vlanTrunkId": null,
"vlanTrunkName": null,
"isDpdk": true
}
],
"tabletList": [
{
"model": null,
"bus": null
}
],
"mouseList": [
{
"model": null,
"bus": null
}
],
"displayList": [
{
"type": null,
"address": null,
"port": null,
"portIpv6": null,
"password": null,
"kayboardMap": null,
"enableVncProxy": true,
"enableSpiceCompress": true,
"vncIp": null,
"vncUsername": null,
"vncPwd": null,
"vncPasswdMode": null
}
],
"videoList": [
{
"devType": null,
"storage": null,
"heads": null,
"number": null,
"pciView": null
}
],
"soundList": [
{
"type": null
}
],
"encryptCardList": [
{
"bus": null,
"slot": null,
"function": null,
"pciName": null,
"address": null
}
],
"pciList": [
{
"driver": null,
"vendor": null,
"product": null,
"ethName": null,
"productId": null,
"vendorId": null,
"bus": null,
"slot": null,
"function": null,
"pciName": null,
"name": null
}
],
"usbList": [
{
"product": null,
"name": null,
"vendor": null,
"productId": null,
"vendorId": null,
"bus": null,
"device": null,
"usbController": null
}
],
"serialList": [
{
"type": null,
"targetPort": null,
"mode": null,
"devPath": null,
"connHost": null,
"connPort": null,
"bindIp": null,
"bindPort": null,
"monitor": true,
"isSerialLog": true
}
],
"numa": {
"nodeSize": null,
"nodeSet": null,
"associate": true
},
"safety": {
"spiceTls": true,
"spiceChannels": [],
"redirUsb": null,
"ifSupSpice": true,
"enableRedirectUsb": true,
"enableAntivirus": true,
"secretLevel": null,
"supportAntivirus": true,
"antivirusType": null,
"securityId": null,
"securityName": null,
"publicCloudId": null
},
"vtpm": null,
"tpm": null,
"gpu": {
"resPoolId": null,
"resPool": null,
"businessTemId": null,
"businessTem": null,
"deviceDriver": null,
"count": null,
"shared": null,
"maxCount": null,
"frl": null
},
"watchdog": {
"model": null,
"action": null
},
"netUsbList": [
{
"host": null,
"service": null,
"port": null,
"manufacturer": null,
"product": null,
"productId": null,
"vendorId": null,
"usbController": null,
"path": null
}
]
}
]
}

2.8.18 Query VM disk info

API endpoint

GET  /NSphere/api/vm-resource/disk

API description

Query VM disk info. At least one of vmId/vmUuid/vmName is required; they must not all be empty. If multiple are provided, they are used in the priority order vmId -> vmUuid -> vmName. New return attributes added in E0930.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
vmName	VM name (domainName)	query	false	string
vmId	VM ID	query	false	integer(int64)
vmUuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiDomainDiskInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiDomainDiskInfoVO	ApiDomainDiskInfoVO
vmId	VM ID	integer(int64)
vmName	VM name	string
vmUuid	VM UUID	string
vmTitle	VM display name	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
domainStatus	VM status	integer(int32)
domainHAStatus	HA status. 0: normal, 1: not joined to HA, 2: joined to HA but config file out of sync.	integer(int32)
hostId	VM host ID	integer(int64)
hostName	VM host name	string
diskList	VM disk details	array	ApiDomainDiskDetailVO
dispName	Device display name.	string
diskIOMode	Disk I/O mode. Allowed values: native, threads, io_uring.	string
targetBus	Disk bus type. ide: IDE disk; usb: USB disk; virtio: high-speed disk; virtioScsi: high-speed SCSI disk.	string
diskSecret	Whether disk encryption is enabled	boolean
serial	Serial number	string
serialId	Disk serial number	string
unmap	Whether space reclaim is enabled. Only takes effect for thin-provisioned high-speed iSCSI disks.	boolean
enableRbd		boolean
diskPath	Disk path	string
backupBlock	CBT backup block-device binding. Used for VM external-snapshot CBT backup. Supported only on FC network storage or on iSCSI network storage whose storage-pool path is prefixed with "/dev/disk/by-id/".	string
enableModify	Whether modification is allowed	boolean
usage	Utilization (percentage)	number(double)
type	Storage volume type. file: file; block: block device; ultra: ubd. When the storage type is network, disk encryption is not supported, cache mode supports only none|directsync, ultra mode is not supported, existing files are not supported; driveType must be raw, mode must be 2, clustersize must be 262144, diskIOMode must be null, diskMode must be subordinate, and priority must be 2.	string
size	Storage volume capacity (MB)	number(double)
capacity	Storage volume capacity (with unit)	string
allocation	Used space (MB)	number(double)
distribute	Used space (with unit)	string
remainStorage	Available capacity (with unit)	string
minValue	Minimum value	number(double)
maxValue	Maximum value	number(double)
showSize	Displayed capacity value	number(double)
showUnit	Displayed capacity unit	string
poolName	Storage pool name	string
poolType	Storage pool type. dir: local file directory / local file directory (high-speed); netfs: NFS network file system; fs: shared file system; cifs: Windows shared directory; logical: LVM logical volume; iscsi: iSCSI network storage; block: FC network storage; scsi: SCSI storage; glusterfs: GlusterFS file system.	string
poolPath	Storage pool path	string
format	Storage volume format	string
clusterSize	Cluster size. Allowed: 65536|131072|262144|524288|1048576|2097152. Unit: bytes. Encrypted disks cannot set this field.	string
enableEditDisk	Whether the disk can be edited	boolean
enableConverFmt	Whether format conversion is allowed	boolean
l2cache	Whether L2 cache is enabled	boolean
diskMode	Disk mode. subordinate: dependent; independent-persistent: independent-persistent.	string
enableEditDiskMode	Whether the disk mode can be edited	boolean
cacheModel	Disk cache mode. none: L1 virtual cache; writeback: L2 virtual cache; writethrough: L1 physical cache; directsync: direct I/O.	string
cacheFile	Cache file path	string
mode	Disk pre-allocation mode. 0: lazy zeroed, 1: zeroed, 2: thin.	integer(int32)
readBytesSec	Read bandwidth limit (KB/s)	integer(int64)
writeBytesSec	Write bandwidth limit (KB/s)	integer(int64)
readIopsSec	Read IOPS limit	integer(int64)
writeIopsSec	Write IOPS limit	integer(int64)
hotPluggable	Whether hot-plug is supported. Only high-speed disks support this parameter.	boolean
iothreads	Whether I/O threads are enabled	boolean
readonly	Whether read-only	boolean
share	Whether the disk is shared	boolean
deviceName	Device name (on host)	string
deviceBus	Device bus type	string
osDeviceUuid	Cloud disk UUID	string
snapShot	Whether snapshots are included. 1: yes, 0: no.	integer(int32)
backingFile	Base image file	string
deviceType	Device type. New attribute added in E0930.	string
device	Device driver type. Same meaning as deviceType; retained for backward compatibility. New attribute added in E0930.	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"vmId": null,
"vmName": null,
"vmUuid": null,
"vmTitle": null,
"protectModel": null,
"domainStatus": null,
"domainHAStatus": null,
"hostId": null,
"hostName": null,
"diskList": [
{
"dispName": null,
"diskIOMode": null,
"targetBus": null,
"diskSecret": true,
"serial": null,
"serialId": null,
"unmap": true,
"enableRbd": true,
"diskPath": null,
"backupBlock": null,
"enableModify": true,
"usage": null,
"type": null,
"size": null,
"capacity": null,
"allocation": null,
"distribute": null,
"remainStorage": null,
"minValue": null,
"maxValue": null,
"showSize": null,
"showUnit": null,
"poolName": null,
"poolType": null,
"poolPath": null,
"format": null,
"clusterSize": null,
"enableEditDisk": true,
"enableConverFmt": true,
"l2cache": true,
"diskMode": null,
"enableEditDiskMode": true,
"cacheModel": null,
"cacheFile": null,
"mode": null,
"readBytesSec": null,
"writeBytesSec": null,
"readIopsSec": null,
"writeIopsSec": null,
"hotPluggable": true,
"iothreads": true,
"readonly": true,
"share": true,
"deviceName": null,
"deviceBus": null,
"osDeviceUuid": null,
"snapShot": null,
"backingFile": null,
"deviceType": null,
"device": null
}
]
}
}

2.8.19 Modify VM disk device

API endpoint

PUT  /NSphere/api/vm-resource/disk

API description

When the VM is running or paused, changes to storage size (for guest OSes that support Virtio disk online expansion, no restart is needed after expansion), serial number, or hot-plug take effect only after restarting the VM. Note: this API does not support modifying CD-ROM or floppy devices; only device=disk is supported. New API added in E0930.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"id": 1,
"uuid": null,
"deviceName": "vda",
"format": "qcow2",
"size": 81920,
"cacheType": "none",
"diskIOMode": "native",
"diskMode": "subordinate",
"mode": 2,
"clusterSize": "262144",
"algorithm": null,
"kmsClusterId": null,
"encryptionType": null,
"encryptPw": null,
"readBytesSec": null,
"readIopsSec": null,
"writeBytesSec": null,
"writeIopsSec": null,
"hotPluggable": true,
"serial": null,
"backupBlock": null,
"unmap": false
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainModifyStorageDTO	Modify-VM-disk entity	body	true	ApiDomainModifyStorageDTO	ApiDomainModifyStorageDTO
id	VM ID. VM ID and VM UUID: at least one is required. If both are provided, VM ID takes precedence.		false	integer(int64)
uuid	VM UUID. VM ID and VM UUID: at least one is required. If both are provided, VM ID takes precedence.		false	string
deviceName	Device name, e.g. vda		true	string
format	Disk format. qcow2: smart, raw: high-speed, luks: encrypted.		true	string
size	Storage capacity (MB)		true	integer(int64)
cacheType	Disk cache mode. none: L1 virtual cache; writeback: L2 virtual cache; writethrough: L1 physical cache; directsync: direct I/O.		true	string
diskIOMode	Disk I/O mode (native; threads). When cacheType is writethrough or writeback, diskIOMode must be threads. Passing null means no change.		false	string
diskMode	Disk mode. subordinate: dependent, independent-persistent: independent-persistent. Required when the disk type is file. Passing null means no change.		false	string
mode	Disk pre-allocation mode. 0: lazy zeroed, 1: zeroed, 2: thin. Passing null means no change.		false	integer(int32)
clusterSize	Cluster size. Allowed: 65536|131072|262144|524288|1048576|2097152. Unit: bytes. Encrypted disks cannot set this field. Passing null means no change.		false	string
algorithm	Disk encryption algorithm (sm4|aes). Required when format is luks.		false	string
kmsClusterId	KMS server ID. Required when encryptionType is 1.		false	integer(int64)
encryptionType	Encryption mode. 0: local encryption, 1: KMS-server encryption. Empty means no encryption. Required when format is luks.		false	integer(int32)
encryptPw	Encryption key. Length 1-64 characters, cannot be all spaces. Required when format is luks and encryptionType is 0.		false	string
readBytesSec	Read bandwidth limit (KB/s)		false	integer(int64)
readIopsSec	Read IOPS limit		false	integer(int64)
writeBytesSec	Write bandwidth limit (KB/s)		false	integer(int64)
writeIopsSec	Write IOPS limit		false	integer(int64)
hotPluggable	Whether hot-plug is supported. Only high-speed disks support this parameter.		false	boolean
serial	Serial number		false	string
backupBlock	CBT backup block-device binding. Used for VM external-snapshot CBT backup. Supported only on FC network storage or on iSCSI network storage whose storage-pool path is prefixed with "/dev/disk/by-id/".		false	string
unmap	Whether space reclaim is enabled. Only takes effect for thin-provisioned high-speed iSCSI disks.		false	boolean

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.20 Delete VM disk

API endpoint

DELETE  /NSphere/api/vm-resource/disk

API description

Delete a VM disk. New API added in E0930.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"id": 0,
"name": null,
"title": null,
"storage": {
"deviceName": "",
"delType": null
}
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainDeleteDiskDTO	Delete VM disk	body	true	ApiDomainDeleteDiskDTO	ApiDomainDeleteDiskDTO
id	VM ID		true	integer(int64)
name	VM name		false	string
title	VM display name		false	string
storage	VM disk info		true	StorageInfo	StorageInfo
deviceName	Device name, e.g. vda		true	string
delType	Disk delete mode. Defaults to 1 when not provided. 1: delete VM disk only; 2: delete VM disk and VM files; 3: delete VM disk and low-format VM files.		false	integer(int32)

Response status

Response code	Description	schema
200	OK	ApiResponseLong

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	integer(int64)	integer(int64)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": null
}

2.8.21 Query VM disk partition info

API endpoint

GET  /NSphere/api/vm-resource/disk-partition

API description

Query VM disk partition info. At least one of vmId/vmUuid/vmName is required; they must not all be empty. If multiple are provided, they are used in the priority order vmId -> vmUuid -> vmName. New return attributes added in E0930.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
vmName	VM name (domainName)	query	false	string
vmId	VM ID	query	false	integer(int64)
vmUuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiDomainDiskPartitionVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiDomainDiskPartitionVO	ApiDomainDiskPartitionVO
domainName	VM name	string
domainTitle	VM display name	string
domainUuid	VM UUID	string
domainId	VM ID	integer(int64)
domainStatus	VM status	string
diskPartitionList	VM disk partition details	array	ApiDomainDiskPartitionDetailVO
partitionId	Partition ID. New attribute added in E0930.	integer(int64)
partitionName	Partition name	string
partitionType	Partition type	string
utilization	Usage rate	number(double)
size	Capacity	number(double)
used	Used	number(double)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"domainName": null,
"domainTitle": null,
"domainUuid": null,
"domainId": null,
"domainStatus": null,
"diskPartitionList": [
{
"partitionId": null,
"partitionName": null,
"partitionType": null,
"utilization": null,
"size": null,
"used": null
}
]
}
}

2.8.22 Batch query VM disk partition info

API endpoint

GET  /NSphere/api/vm-resource/disk-partition/list

API description

Batch query VM disk partition info by hpId/clusterId/hostId. If none is provided, all are queried. When multiple are provided, hostId takes precedence; without hostId, hpId and clusterId are combined.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
offset	Offset. Specifies the record from which results start. Default 0. New parameter added in E0930.	query	false	integer(int32)
limit	Maximum records returned per page. Default 10. New parameter added in E0930.	query	false	integer(int32)
sortDir	Sort type. 0: no sort, 1: ascending, 2: descending. Defaults to no sort when sortField is not empty. New parameter added in E0930.	query	false	integer(int32)
sortField	Sort field. Supported fields: name, title. New parameter added in E0930.	query	false	string
hpId	VM data center ID	query	false	integer(int64)
clusterId	VM cluster ID	query	false	integer(int64)
hostId	VM host ID	query	false	integer(int64)

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainDiskPartitionVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainDiskPartitionVO
domainName	VM name	string
domainTitle	VM display name	string
domainUuid	VM UUID	string
domainId	VM ID	integer(int64)
domainStatus	VM status	string
diskPartitionList	VM disk partition details	array	ApiDomainDiskPartitionDetailVO
partitionId	Partition ID. New attribute added in E0930.	integer(int64)
partitionName	Partition name	string
partitionType	Partition type	string
utilization	Usage rate	number(double)
size	Capacity	number(double)
used	Used	number(double)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"domainName": null,
"domainTitle": null,
"domainUuid": null,
"domainId": null,
"domainStatus": null,
"diskPartitionList": [
{
"partitionId": null,
"partitionName": null,
"partitionType": null,
"utilization": null,
"size": null,
"used": null
}
]
}
]
}

2.8.23 Batch query VM disk info

API endpoint

GET  /NSphere/api/vm-resource/disk/list

API description

Batch query VM disk info by hpId/clusterId/hostId. If none is provided, all are queried. When multiple are provided, hostId takes precedence; without hostId, hpId and clusterId are combined. Changed in E0930: returns basic CD-ROM and floppy info in addition.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
offset	Offset. Specifies the record from which results start. Default 0. New parameter added in E0930.	query	false	integer(int32)
limit	Maximum records returned per page. Default 10. New parameter added in E0930.	query	false	integer(int32)
sortDir	Sort type. 0: no sort, 1: ascending, 2: descending. Defaults to no sort when sortField is not empty. New parameter added in E0930.	query	false	integer(int32)
sortField	Sort field. Supported fields: name, title. New parameter added in E0930.	query	false	string
hpId	VM data center ID	query	false	integer(int64)
clusterId	VM cluster ID	query	false	integer(int64)
hostId	VM host ID	query	false	integer(int64)

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainDiskInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainDiskInfoVO
vmId	VM ID	integer(int64)
vmName	VM name	string
vmUuid	VM UUID	string
vmTitle	VM display name	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
domainStatus	VM status	integer(int32)
domainHAStatus	HA status. 0: normal, 1: not joined to HA, 2: joined to HA but config file out of sync.	integer(int32)
hostId	VM host ID	integer(int64)
hostName	VM host name	string
diskList	VM disk details	array	ApiDomainDiskDetailVO
dispName	Device display name.	string
diskIOMode	Disk I/O mode. Allowed values: native, threads, io_uring.	string
targetBus	Disk bus type. ide: IDE disk; usb: USB disk; virtio: high-speed disk; virtioScsi: high-speed SCSI disk.	string
diskSecret	Whether disk encryption is enabled	boolean
serial	Serial number	string
serialId	Disk serial number	string
unmap	Whether space reclaim is enabled. Only takes effect for thin-provisioned high-speed iSCSI disks.	boolean
enableRbd		boolean
diskPath	Disk path	string
backupBlock	CBT backup block-device binding. Used for VM external-snapshot CBT backup. Supported only on FC network storage or on iSCSI network storage whose storage-pool path is prefixed with "/dev/disk/by-id/".	string
enableModify	Whether modification is allowed	boolean
usage	Utilization (percentage)	number(double)
type	Storage volume type. file: file; block: block device; ultra: ubd. When the storage type is network, disk encryption is not supported, cache mode supports only none|directsync, ultra mode is not supported, existing files are not supported; driveType must be raw, mode must be 2, clustersize must be 262144, diskIOMode must be null, diskMode must be subordinate, and priority must be 2.	string
size	Storage volume capacity (MB)	number(double)
capacity	Storage volume capacity (with unit)	string
allocation	Used space (MB)	number(double)
distribute	Used space (with unit)	string
remainStorage	Available capacity (with unit)	string
minValue	Minimum value	number(double)
maxValue	Maximum value	number(double)
showSize	Displayed capacity value	number(double)
showUnit	Displayed capacity unit	string
poolName	Storage pool name	string
poolType	Storage pool type. dir: local file directory / local file directory (high-speed); netfs: NFS network file system; fs: shared file system; cifs: Windows shared directory; logical: LVM logical volume; iscsi: iSCSI network storage; block: FC network storage; scsi: SCSI storage; glusterfs: GlusterFS file system.	string
poolPath	Storage pool path	string
format	Storage volume format	string
clusterSize	Cluster size. Allowed: 65536|131072|262144|524288|1048576|2097152. Unit: bytes. Encrypted disks cannot set this field.	string
enableEditDisk	Whether the disk can be edited	boolean
enableConverFmt	Whether format conversion is allowed	boolean
l2cache	Whether L2 cache is enabled	boolean
diskMode	Disk mode. subordinate: dependent; independent-persistent: independent-persistent.	string
enableEditDiskMode	Whether the disk mode can be edited	boolean
cacheModel	Disk cache mode. none: L1 virtual cache; writeback: L2 virtual cache; writethrough: L1 physical cache; directsync: direct I/O.	string
cacheFile	Cache file path	string
mode	Disk pre-allocation mode. 0: lazy zeroed, 1: zeroed, 2: thin.	integer(int32)
readBytesSec	Read bandwidth limit (KB/s)	integer(int64)
writeBytesSec	Write bandwidth limit (KB/s)	integer(int64)
readIopsSec	Read IOPS limit	integer(int64)
writeIopsSec	Write IOPS limit	integer(int64)
hotPluggable	Whether hot-plug is supported. Only high-speed disks support this parameter.	boolean
iothreads	Whether I/O threads are enabled	boolean
readonly	Whether read-only	boolean
share	Whether the disk is shared	boolean
deviceName	Device name (on host)	string
deviceBus	Device bus type	string
osDeviceUuid	Cloud disk UUID	string
snapShot	Whether snapshots are included. 1: yes, 0: no.	integer(int32)
backingFile	Base image file	string
deviceType	Device type. New attribute added in E0930.	string
device	Device driver type. Same meaning as deviceType; retained for backward compatibility. New attribute added in E0930.	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"vmId": null,
"vmName": null,
"vmUuid": null,
"vmTitle": null,
"protectModel": null,
"domainStatus": null,
"domainHAStatus": null,
"hostId": null,
"hostName": null,
"diskList": [
{
"dispName": null,
"diskIOMode": null,
"targetBus": null,
"diskSecret": true,
"serial": null,
"serialId": null,
"unmap": true,
"enableRbd": true,
"diskPath": null,
"backupBlock": null,
"enableModify": true,
"usage": null,
"type": null,
"size": null,
"capacity": null,
"allocation": null,
"distribute": null,
"remainStorage": null,
"minValue": null,
"maxValue": null,
"showSize": null,
"showUnit": null,
"poolName": null,
"poolType": null,
"poolPath": null,
"format": null,
"clusterSize": null,
"enableEditDisk": true,
"enableConverFmt": true,
"l2cache": true,
"diskMode": null,
"enableEditDiskMode": true,
"cacheModel": null,
"cacheFile": null,
"mode": null,
"readBytesSec": null,
"writeBytesSec": null,
"readIopsSec": null,
"writeIopsSec": null,
"hotPluggable": true,
"iothreads": true,
"readonly": true,
"share": true,
"deviceName": null,
"deviceBus": null,
"osDeviceUuid": null,
"snapShot": null,
"backingFile": null,
"deviceType": null,
"device": null
}
]
}
]
}

2.8.24 Batch query VM disk info by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/disk/list

API description

Batch query VM disk info by ID/UUID list. The ID and UUID lists cannot both be empty. If both are provided, the ID list takes precedence.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"idList": [
1,
2,
3
],
"uuidList": [
"uuid-1",
"uuid-2"
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainBatchQueryDTO	VM ID/UUID list request entity	body	true	ApiDomainBatchQueryDTO	ApiDomainBatchQueryDTO
idList	VM ID list		false	array	integer(int64)
uuidList	VM UUID list		false	array	string

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainDiskInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainDiskInfoVO
vmId	VM ID	integer(int64)
vmName	VM name	string
vmUuid	VM UUID	string
vmTitle	VM display name	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
domainStatus	VM status	integer(int32)
domainHAStatus	HA status. 0: normal, 1: not joined to HA, 2: joined to HA but config file out of sync.	integer(int32)
hostId	VM host ID	integer(int64)
hostName	VM host name	string
diskList	VM disk details	array	ApiDomainDiskDetailVO
dispName	Device display name.	string
diskIOMode	Disk I/O mode. Allowed values: native, threads, io_uring.	string
targetBus	Disk bus type. ide: IDE disk; usb: USB disk; virtio: high-speed disk; virtioScsi: high-speed SCSI disk.	string
diskSecret	Whether disk encryption is enabled	boolean
serial	Serial number	string
serialId	Disk serial number	string
unmap	Whether space reclaim is enabled. Only takes effect for thin-provisioned high-speed iSCSI disks.	boolean
enableRbd		boolean
diskPath	Disk path	string
backupBlock	CBT backup block-device binding. Used for VM external-snapshot CBT backup. Supported only on FC network storage or on iSCSI network storage whose storage-pool path is prefixed with "/dev/disk/by-id/".	string
enableModify	Whether modification is allowed	boolean
usage	Utilization (percentage)	number(double)
type	Storage volume type. file: file; block: block device; ultra: ubd. When the storage type is network, disk encryption is not supported, cache mode supports only none|directsync, ultra mode is not supported, existing files are not supported; driveType must be raw, mode must be 2, clustersize must be 262144, diskIOMode must be null, diskMode must be subordinate, and priority must be 2.	string
size	Storage volume capacity (MB)	number(double)
capacity	Storage volume capacity (with unit)	string
allocation	Used space (MB)	number(double)
distribute	Used space (with unit)	string
remainStorage	Available capacity (with unit)	string
minValue	Minimum value	number(double)
maxValue	Maximum value	number(double)
showSize	Displayed capacity value	number(double)
showUnit	Displayed capacity unit	string
poolName	Storage pool name	string
poolType	Storage pool type. dir: local file directory / local file directory (high-speed); netfs: NFS network file system; fs: shared file system; cifs: Windows shared directory; logical: LVM logical volume; iscsi: iSCSI network storage; block: FC network storage; scsi: SCSI storage; glusterfs: GlusterFS file system.	string
poolPath	Storage pool path	string
format	Storage volume format	string
clusterSize	Cluster size. Allowed: 65536|131072|262144|524288|1048576|2097152. Unit: bytes. Encrypted disks cannot set this field.	string
enableEditDisk	Whether the disk can be edited	boolean
enableConverFmt	Whether format conversion is allowed	boolean
l2cache	Whether L2 cache is enabled	boolean
diskMode	Disk mode. subordinate: dependent; independent-persistent: independent-persistent.	string
enableEditDiskMode	Whether the disk mode can be edited	boolean
cacheModel	Disk cache mode. none: L1 virtual cache; writeback: L2 virtual cache; writethrough: L1 physical cache; directsync: direct I/O.	string
cacheFile	Cache file path	string
mode	Disk pre-allocation mode. 0: lazy zeroed, 1: zeroed, 2: thin.	integer(int32)
readBytesSec	Read bandwidth limit (KB/s)	integer(int64)
writeBytesSec	Write bandwidth limit (KB/s)	integer(int64)
readIopsSec	Read IOPS limit	integer(int64)
writeIopsSec	Write IOPS limit	integer(int64)
hotPluggable	Whether hot-plug is supported. Only high-speed disks support this parameter.	boolean
iothreads	Whether I/O threads are enabled	boolean
readonly	Whether read-only	boolean
share	Whether the disk is shared	boolean
deviceName	Device name (on host)	string
deviceBus	Device bus type	string
osDeviceUuid	Cloud disk UUID	string
snapShot	Whether snapshots are included. 1: yes, 0: no.	integer(int32)
backingFile	Base image file	string
deviceType	Device type. New attribute added in E0930.	string
device	Device driver type. Same meaning as deviceType; retained for backward compatibility. New attribute added in E0930.	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"vmId": null,
"vmName": null,
"vmUuid": null,
"vmTitle": null,
"protectModel": null,
"domainStatus": null,
"domainHAStatus": null,
"hostId": null,
"hostName": null,
"diskList": [
{
"dispName": null,
"diskIOMode": null,
"targetBus": null,
"diskSecret": true,
"serial": null,
"serialId": null,
"unmap": true,
"enableRbd": true,
"diskPath": null,
"backupBlock": null,
"enableModify": true,
"usage": null,
"type": null,
"size": null,
"capacity": null,
"allocation": null,
"distribute": null,
"remainStorage": null,
"minValue": null,
"maxValue": null,
"showSize": null,
"showUnit": null,
"poolName": null,
"poolType": null,
"poolPath": null,
"format": null,
"clusterSize": null,
"enableEditDisk": true,
"enableConverFmt": true,
"l2cache": true,
"diskMode": null,
"enableEditDiskMode": true,
"cacheModel": null,
"cacheFile": null,
"mode": null,
"readBytesSec": null,
"writeBytesSec": null,
"readIopsSec": null,
"writeIopsSec": null,
"hotPluggable": true,
"iothreads": true,
"readonly": true,
"share": true,
"deviceName": null,
"deviceBus": null,
"osDeviceUuid": null,
"snapShot": null,
"backingFile": null,
"deviceType": null,
"device": null
}
]
}
]
}

2.8.25 VM disk performance data

API endpoint

GET  /NSphere/api/vm-resource/disk/stat

API description

VM disk performance data. Provide one of hpId, clusterId, vmId. If multiple are provided, the query uses the union of them. If none is provided, all VMs on the management platform are queried. New API added in E0930.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
hpId	VM data center ID	query	false	integer(int64)
clusterId	VM cluster ID	query	false	integer(int64)
hostId	VM host ID	query	false	integer(int64)
vmId	VM ID	query	false	integer(int64)

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainDiskStatVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainDiskStatVO
device	Disk device name.	string
time	Sample time, in ms.	integer(int64)
ioStat	Disk I/O throughput, in KBps.	number(double)
readStat	Disk read I/O throughput, in KBps.	number(double)
writeStat	Disk write I/O throughput, in KBps.	number(double)
readReqest	Disk read requests, in IOPS.	number(double)
writeReqest	Disk write requests, in IOPS.	number(double)
readLatency	Disk read I/O latency, in ms.	number(double)
writeLatency	Disk write I/O latency, in ms.	number(double)
domainTitle	VM display name	string
domainId	VM ID	integer(int64)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"device": null,
"time": null,
"ioStat": null,
"readStat": null,
"writeStat": null,
"readReqest": null,
"writeReqest": null,
"readLatency": null,
"writeLatency": null,
"domainTitle": null,
"domainId": null
}
]
}

2.8.26 Query VM graphics device info

API endpoint

GET  /NSphere/api/vm-resource/graphics

API description

Query VM graphics device info. At least one of vmId/vmUuid/vmName is required; they must not all be empty. If multiple are provided, they are used in the priority order vmId -> vmUuid -> vmName.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
vmName	VM name (domainName)	query	false	string
vmId	VM ID	query	false	integer(int64)
vmUuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiDomainGraphicsInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiDomainGraphicsInfoVO	ApiDomainGraphicsInfoVO
id	VM ID	integer(int64)
name	VM name	string
vmUuid	VM UUID	string
title	VM display name	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
graphicses	VM graphics access configuration	array	ApiDomainGraphicsVO
type	Graphics access type (vnc, spice)	string
port	Graphics access port	integer(int32)
address	Graphics access address	string
kayboardMap	Keyboard mapping	string
enableVncProxy	Whether VNC proxy is enabled. 1: enabled, 0: disabled.	integer(int32)
tlsPort	SPICE TLS port	integer(int32)
spiceTlsChannel	SPICE TLS channel list	array	string
videos	VM video device info	array	ApiDomainVideoVO
type	Video device type	string
pciView	PCI view	string
vram	Video memory size (KB)	integer(int32)
vgamem	VGA video memory size (MB)	integer(int32)
ram	Device memory size (MB)	integer(int32)
heads	Number of display outputs (monitors)	integer(int32)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"id": null,
"name": null,
"vmUuid": null,
"title": null,
"protectModel": null,
"graphicses": [
{
"type": null,
"port": null,
"address": null,
"kayboardMap": null,
"enableVncProxy": null,
"tlsPort": null,
"spiceTlsChannel": []
}
],
"videos": [
{
"type": null,
"pciView": null,
"vram": null,
"vgamem": null,
"ram": null,
"heads": null
}
]
}
}

2.8.27 Batch query VM graphics device info

API endpoint

GET  /NSphere/api/vm-resource/graphics/list

API description

Batch query VM graphics device info by hpId/clusterId/hostId. If none is provided, all are queried. When multiple are provided, hostId takes precedence; without hostId, hpId and clusterId are combined.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
offset	Offset. Specifies the record from which results start. Default 0. New parameter added in E0930.	query	false	integer(int32)
limit	Maximum records returned per page. Default 10. New parameter added in E0930.	query	false	integer(int32)
sortDir	Sort type. 0: no sort, 1: ascending, 2: descending. Defaults to no sort when sortField is not empty. New parameter added in E0930.	query	false	integer(int32)
sortField	Sort field. Supported fields: name, title. New parameter added in E0930.	query	false	string
hpId	VM data center ID	query	false	integer(int64)
clusterId	VM cluster ID	query	false	integer(int64)
hostId	VM host ID	query	false	integer(int64)

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainGraphicsInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainGraphicsInfoVO
id	VM ID	integer(int64)
name	VM name	string
vmUuid	VM UUID	string
title	VM display name	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
graphicses	VM graphics access configuration	array	ApiDomainGraphicsVO
type	Graphics access type (vnc, spice)	string
port	Graphics access port	integer(int32)
address	Graphics access address	string
kayboardMap	Keyboard mapping	string
enableVncProxy	Whether VNC proxy is enabled. 1: enabled, 0: disabled.	integer(int32)
tlsPort	SPICE TLS port	integer(int32)
spiceTlsChannel	SPICE TLS channel list	array	string
videos	VM video device info	array	ApiDomainVideoVO
type	Video device type	string
pciView	PCI view	string
vram	Video memory size (KB)	integer(int32)
vgamem	VGA video memory size (MB)	integer(int32)
ram	Device memory size (MB)	integer(int32)
heads	Number of display outputs (monitors)	integer(int32)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"id": null,
"name": null,
"vmUuid": null,
"title": null,
"protectModel": null,
"graphicses": [
{
"type": null,
"port": null,
"address": null,
"kayboardMap": null,
"enableVncProxy": null,
"tlsPort": null,
"spiceTlsChannel": []
}
],
"videos": [
{
"type": null,
"pciView": null,
"vram": null,
"vgamem": null,
"ram": null,
"heads": null
}
]
}
]
}

2.8.28 Batch query VM graphics device info by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/graphics/list

API description

Batch query VM graphics device info by ID/UUID list. The ID and UUID lists cannot both be empty. If both are provided, the ID list takes precedence.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"idList": [
1,
2,
3
],
"uuidList": [
"uuid-1",
"uuid-2"
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainBatchQueryDTO	VM ID/UUID list request entity	body	true	ApiDomainBatchQueryDTO	ApiDomainBatchQueryDTO
idList	VM ID list		false	array	integer(int64)
uuidList	VM UUID list		false	array	string

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainGraphicsInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainGraphicsInfoVO
id	VM ID	integer(int64)
name	VM name	string
vmUuid	VM UUID	string
title	VM display name	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
graphicses	VM graphics access configuration	array	ApiDomainGraphicsVO
type	Graphics access type (vnc, spice)	string
port	Graphics access port	integer(int32)
address	Graphics access address	string
kayboardMap	Keyboard mapping	string
enableVncProxy	Whether VNC proxy is enabled. 1: enabled, 0: disabled.	integer(int32)
tlsPort	SPICE TLS port	integer(int32)
spiceTlsChannel	SPICE TLS channel list	array	string
videos	VM video device info	array	ApiDomainVideoVO
type	Video device type	string
pciView	PCI view	string
vram	Video memory size (KB)	integer(int32)
vgamem	VGA video memory size (MB)	integer(int32)
ram	Device memory size (MB)	integer(int32)
heads	Number of display outputs (monitors)	integer(int32)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"id": null,
"name": null,
"vmUuid": null,
"title": null,
"protectModel": null,
"graphicses": [
{
"type": null,
"port": null,
"address": null,
"kayboardMap": null,
"enableVncProxy": null,
"tlsPort": null,
"spiceTlsChannel": []
}
],
"videos": [
{
"type": null,
"pciView": null,
"vram": null,
"vgamem": null,
"ram": null,
"heads": null
}
]
}
]
}

2.8.29 Query VM memory info

API endpoint

GET  /NSphere/api/vm-resource/memory

API description

Query VM memory info. At least one of vmId/vmUuid/vmName is required; they must not all be empty. If multiple are provided, they are used in the priority order vmId -> vmUuid -> vmName.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
vmName	VM name (domainName)	query	false	string
vmId	VM ID	query	false	integer(int64)
vmUuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiDomainMemoryInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiDomainMemoryInfoVO	ApiDomainMemoryInfoVO
vmId	VM ID	integer(int64)
vmName	VM name	string
vmTitle	VM display name	string
vmUuid	VM UUID	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
memoryInitFormat	VM allocated memory (with unit)	string
sizeFormat	VM actual allocated memory (with unit)	string
hostMemoryFormat	Host memory (with unit)	string
maxMemoryFormat	Maximum allocatable memory (with unit)	string
memoryBacking	Memory reservation percentage. 0-100.	integer(int32)
memoryPriority	Memory resource priority. 0: low, 50: medium, 100: high.	integer(int32)
memoryLimit	Memory limit value	number(double)
memoryLimitUnit	Memory limit unit	string
autoMem	Whether memory overcommit is enabled	boolean
hugepage	Whether huge pages are enabled	boolean
hotMem	Whether memory hot-add is enabled	boolean

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"vmId": null,
"vmName": null,
"vmTitle": null,
"vmUuid": null,
"protectModel": null,
"memoryInitFormat": null,
"sizeFormat": null,
"hostMemoryFormat": null,
"maxMemoryFormat": null,
"memoryBacking": null,
"memoryPriority": null,
"memoryLimit": null,
"memoryLimitUnit": null,
"autoMem": true,
"hugepage": true,
"hotMem": true
}
}

2.8.30 Modify VM memory info

API endpoint

PUT  /NSphere/api/vm-resource/memory

API description

Modify VM memory info. New API added in E0930.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"id": 1,
"uuid": null,
"size": 4096,
"memoryBacking": 0,
"memoryPriority": 0,
"memoryLimit": null,
"autoMem": 0,
"hugepage": false
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainModifyMemoryDTO	Modify-VM-memory entity	body	true	ApiDomainModifyMemoryDTO	ApiDomainModifyMemoryDTO
id	VM ID. VM ID and VM UUID: at least one is required. If both are provided, VM ID takes precedence.		false	integer(int64)
uuid	VM UUID. VM ID and VM UUID: at least one is required. If both are provided, VM ID takes precedence.		false	string
size	Memory size (MB). Minimum 512, must be a multiple of 4. Online memory changes must be larger than the original memory. When hot-adding memory, the added amount must be a multiple of 512 MB. For a powered-off VM, the maximum allocatable memory is the host memory; for an online VM, the maximum is 16 times the VM initial memory and cannot exceed host memory.		true	integer(int64)
memoryBacking	Memory reservation percentage. 0-100.		true	integer(int32)
memoryPriority	Memory resource priority. 0: low, 50: medium, 100: high. Default 0.		false	integer(int32)
memoryLimit	Memory limit (MB). Minimum 512, must be a multiple of 4. Cannot exceed the configured memory size, and when memory reservation is greater than 0, cannot be less than the minimum computed from the reservation (size * (memoryBacking / 100) + 10). Defaults to null (no limit).		false	integer(int64)
autoMem	Whether memory overcommit is enabled. 0: off, 1: on. Default 0. NSpheretools must be installed when memory overcommit is enabled.		false	integer(int32)
hugepage	Whether huge pages are enabled. null means no change. When huge pages are enabled, memory resource priority cannot be modified, memory reservation must be 0, memory limit must be null, and memory overcommit must be off (memoryBacking=0, memoryLimit=null, autoMem=0).		false	boolean

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.31 Batch query VM memory info

API endpoint

GET  /NSphere/api/vm-resource/memory/list

API description

Batch query VM memory info by hpId/clusterId/hostId. If none is provided, all are queried. When multiple are provided, hostId takes precedence; without hostId, hpId and clusterId are combined.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
offset	Offset. Specifies the record from which results start. Default 0. New parameter added in E0930.	query	false	integer(int32)
limit	Maximum records returned per page. Default 10. New parameter added in E0930.	query	false	integer(int32)
sortDir	Sort type. 0: no sort, 1: ascending, 2: descending. Defaults to no sort when sortField is not empty. New parameter added in E0930.	query	false	integer(int32)
sortField	Sort field. Supported fields: name, title. New parameter added in E0930.	query	false	string
hpId	VM data center ID	query	false	integer(int64)
clusterId	VM cluster ID	query	false	integer(int64)
hostId	VM host ID	query	false	integer(int64)

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainMemoryInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainMemoryInfoVO
vmId	VM ID	integer(int64)
vmName	VM name	string
vmTitle	VM display name	string
vmUuid	VM UUID	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
memoryInitFormat	VM allocated memory (with unit)	string
sizeFormat	VM actual allocated memory (with unit)	string
hostMemoryFormat	Host memory (with unit)	string
maxMemoryFormat	Maximum allocatable memory (with unit)	string
memoryBacking	Memory reservation percentage. 0-100.	integer(int32)
memoryPriority	Memory resource priority. 0: low, 50: medium, 100: high.	integer(int32)
memoryLimit	Memory limit value	number(double)
memoryLimitUnit	Memory limit unit	string
autoMem	Whether memory overcommit is enabled	boolean
hugepage	Whether huge pages are enabled	boolean
hotMem	Whether memory hot-add is enabled	boolean

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"vmId": null,
"vmName": null,
"vmTitle": null,
"vmUuid": null,
"protectModel": null,
"memoryInitFormat": null,
"sizeFormat": null,
"hostMemoryFormat": null,
"maxMemoryFormat": null,
"memoryBacking": null,
"memoryPriority": null,
"memoryLimit": null,
"memoryLimitUnit": null,
"autoMem": true,
"hugepage": true,
"hotMem": true
}
]
}

2.8.32 Batch query VM memory info by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/memory/list

API description

Batch query VM memory info by ID/UUID list. The ID and UUID lists cannot both be empty. If both are provided, the ID list takes precedence.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"idList": [
1,
2,
3
],
"uuidList": [
"uuid-1",
"uuid-2"
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainBatchQueryDTO	VM ID/UUID list request entity	body	true	ApiDomainBatchQueryDTO	ApiDomainBatchQueryDTO
idList	VM ID list		false	array	integer(int64)
uuidList	VM UUID list		false	array	string

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainMemoryInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainMemoryInfoVO
vmId	VM ID	integer(int64)
vmName	VM name	string
vmTitle	VM display name	string
vmUuid	VM UUID	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
memoryInitFormat	VM allocated memory (with unit)	string
sizeFormat	VM actual allocated memory (with unit)	string
hostMemoryFormat	Host memory (with unit)	string
maxMemoryFormat	Maximum allocatable memory (with unit)	string
memoryBacking	Memory reservation percentage. 0-100.	integer(int32)
memoryPriority	Memory resource priority. 0: low, 50: medium, 100: high.	integer(int32)
memoryLimit	Memory limit value	number(double)
memoryLimitUnit	Memory limit unit	string
autoMem	Whether memory overcommit is enabled	boolean
hugepage	Whether huge pages are enabled	boolean
hotMem	Whether memory hot-add is enabled	boolean

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"vmId": null,
"vmName": null,
"vmTitle": null,
"vmUuid": null,
"protectModel": null,
"memoryInitFormat": null,
"sizeFormat": null,
"hostMemoryFormat": null,
"maxMemoryFormat": null,
"memoryBacking": null,
"memoryPriority": null,
"memoryLimit": null,
"memoryLimitUnit": null,
"autoMem": true,
"hugepage": true,
"hotMem": true
}
]
}

2.8.33 Migrate VM (host only)

API endpoint

PUT  /NSphere/api/vm-resource/migrate/host

API description

Migrate a VM (host only). On success, returns the task ID.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"id": 0,
"targetHostId": 0,
"enablePostcopy": false,
"autoConverge": false,
"encrypt": false,
"changeEmc": false,
"migrateParallel": false,
"migrateParallelMaxSpeed": 1100,
"networkInfoSet": [
{
"mac": "",
"targetPortGroupId": 0,
"targetPortGroupName": null
}
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainMigrateHostDTO	VM migration (host) parameter entity.	body	true	ApiDomainMigrateHostDTO	ApiDomainMigrateHostDTO
id	VM ID		true	integer(int64)
targetHostId	Destination host ID.		true	integer(int64)
enablePostcopy	Whether memory post-copy is enabled. Ignored on hosts of version 730 or 760. Effective when the VM is running or paused. When enabled, migration to the destination host is faster, but sufficient migration bandwidth must be ensured; 10Gb or higher migration network is recommended. Mutually exclusive with concurrent migration. If the network is interrupted or the destination host fails during post-copy migration, VM services are disrupted.		false	boolean
autoConverge	Whether to actively throttle CPU. Effective when the VM is running or paused. When enabled, lowers the VM CPU scheduling frequency during migration, reducing the amount of migrated data so the migration finishes faster.		false	boolean
encrypt	Whether to encrypt. Effective when the VM is paused or running. Provides more secure data transfer. Mutually exclusive with concurrent migration.		false	boolean
changeEmc	Whether to switch EMC mode. Used when a VM already in EMC mode is migrated across clusters to an EMC cluster, to keep CPU modes compatible.		false	boolean
migrateParallel	Whether to enable concurrency. Ignored on hosts of version 730 or 760. Concurrency requires 10Gb or higher network and low CPU utilization on both source and destination hosts; use with caution. Mutually exclusive with memory post-copy and encryption. The business-priority migration policy cannot be used when concurrency is enabled.		false	boolean
migrateParallelMaxSpeed	Maximum rate for concurrent migration, in MB/s. Effective when concurrency is enabled. Range: 300 to a dynamic upper bound determined by network bandwidth. Ignored on hosts of version 730 or 760.		false	integer(int64)
networkInfoSet	Destination network port group configuration.		false	array	ApiMigrateNetworkInfoDTO
mac	MAC address.		true	string
targetPortGroupId	Destination network port group ID. Verify that the selected destination host can actually use this port group; otherwise the request will fail.		true	integer(int64)
targetPortGroupName	Destination network port group name. Used as an echo name in some error scenarios.		false	string

Response status

Response code	Description	schema
200	OK	ApiResponseLong

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	integer(int64)	integer(int64)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": null
}

2.8.34 Migrate VM (host and storage)

API endpoint

PUT  /NSphere/api/vm-resource/migrate/host-storage

API description

Migrate a VM (host and storage). On success, returns the task ID.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"diskFormat": "qcow2",
"diskMode": null,
"migrateRateType": 0,
"migrateRateLimitType": 0,
"migrateSpeed": "noLimit",
"rateLimitValue": 150,
"migrateTimeOut": null,
"storageInfoSet": [
{
"srcFile": "",
"srcPool": null,
"srcPoolTitle": null,
"srcDev": "",
"targetPath": null,
"targetPool": null,
"targetPoolTitle": null
}
],
"id": 0,
"targetHostId": 0,
"autoConverge": false,
"encrypt": false,
"enablePostcopy": false,
"changeEmc": false,
"migrateParallel": false,
"migrateParallelMaxSpeed": null,
"networkInfoSet": [
{
"mac": "",
"targetPortGroupId": 0,
"targetPortGroupName": null
}
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainMigrateHostStorageDTO	VM migration (host and storage) parameter entity.	body	true	ApiDomainMigrateHostStorageDTO	ApiDomainMigrateHostStorageDTO
diskFormat	Specified format. qcow2: smart, raw: high-speed. If omitted or empty, unchanged. Migration acceleration cannot be enabled at the same time when changing the storage format. The specified format takes effect only when the destination storage pool type is local file directory, shared file system, or NFS network file system.		false	string
diskMode	Disk pre-allocation. 0: lazy zeroed, 1: zeroed, 2: thin. If omitted or empty, unchanged. Migration acceleration cannot be enabled at the same time when changing pre-allocation. Ignored on hosts of version 730 or 760.		false	integer(int32)
migrateRateType	Migration policy. 0: migration priority, 1: business priority. Ignored on hosts of version 730 or 760. Migration priority applies to online VMs; when configured on an offline VM, the actual migration behaves as business priority + custom rate limit + no limit. Business priority is mutually exclusive with migration acceleration.		true	integer(int32)
migrateRateLimitType	Migration rate-limit policy. 0: auto rate limit, 1: manual rate limit. Effective when the migration policy is business priority. Auto rate limit applies to online VMs; on an offline VM configured with business priority + auto rate limit, actual migration behaves as custom rate limit + moderate. Ignored on hosts of version 730 or 760.		false	integer(int32)
migrateSpeed	Migration rate. noLimit: unlimited, normal: moderate, fast: fast, limitMax: capped at maximum. Ignored on hosts of version 730 or 760. Effective when the migration rate-limit policy is custom rate limit. When auto rate limit is configured and the VM migrates offline, the rate adapts to fast.		false	string
rateLimitValue	Maximum rate limit, in MB/s. Range: 1-12500. Effective when the migration rate is limitMax. Ignored on hosts of version 730 or 760.		false	integer(int64)
migrateTimeOut	Migration timeout, in minutes. Range: 5-1440. Migration is cancelled automatically when the timeout expires. Ignored on hosts of version 730 or 760. Effective when the VM is running or paused; if the VM goes offline during migration, this attribute is ignored. If an orchestration end time is also set, whichever cancels first triggers cancellation, and the later one cancels again if the migration task was not stopped.		false	integer(int64)
storageInfoSet	VM migration storage info.		true	array	ApiMigrateStorageInfoDTO
srcFile	Full path of the source VM storage volume.		true	string
srcPool	Source storage pool. Note: local disks (e.g. /dev/disk/by-path/pci-0000:18:00.0-scsi-0:1:0:0) have no storage pool.		false	string
srcPoolTitle	Display name of the storage pool holding the source file. Note: local disks (e.g. /dev/disk/by-path/pci-0000:18:00.0-scsi-0:1:0:0) have no storage pool.		false	string
srcDev	Source storage device name, e.g. vda.		true	string
targetPath	Destination storage path. Leave empty to indicate a special storage volume (local disk, iSCSI, FC block storage pool, logical volume). Otherwise it is required.		false	string
targetPool	Destination storage pool name. Leave empty to indicate a special storage volume (local disk, iSCSI, FC block storage pool, logical volume). Otherwise it is required.		false	string
targetPoolTitle	Destination storage pool display name.		false	string
id	VM ID		true	integer(int64)
targetHostId	Destination host ID.		true	integer(int64)
autoConverge	Whether to actively throttle CPU. Effective when the VM is running or paused. When enabled, lowers the VM CPU scheduling frequency during migration, reducing the amount of migrated data so the migration finishes faster.		false	boolean
encrypt	Whether to encrypt. Effective when the VM is paused or running. Provides more secure data transfer. Mutually exclusive with concurrent migration.		false	boolean
enablePostcopy	Whether memory post-copy is enabled. Ignored on hosts of version 730 or 760. Effective when the VM is running or paused. When enabled, migration to the destination host is faster, but sufficient migration bandwidth must be ensured; 10Gb or higher migration network is recommended. Mutually exclusive with concurrent migration. If the network is interrupted or the destination host fails during post-copy migration, VM services are disrupted.		false	boolean
changeEmc	Whether to switch EMC mode. Used when a VM already in EMC mode is migrated across clusters to an EMC cluster, to keep CPU modes compatible.		false	boolean
migrateParallel	Whether to enable concurrency. Ignored on hosts of version 730 or 760. Concurrency requires 10Gb or higher network and low CPU utilization on both source and destination hosts; use with caution. Mutually exclusive with memory post-copy and encryption. The business-priority migration policy cannot be used when concurrency is enabled.		false	boolean
migrateParallelMaxSpeed	Maximum rate for concurrent migration, in MB/s. Effective when concurrency is enabled. Range: 300 to a dynamic upper bound determined by network bandwidth. Ignored on hosts of version 730 or 760.		false	integer(int64)
networkInfoSet	Destination network port group configuration.		false	array	ApiMigrateNetworkInfoDTO
mac	MAC address.		true	string
targetPortGroupId	Destination network port group ID. Verify that the selected destination host can actually use this port group; otherwise the request will fail.		true	integer(int64)
targetPortGroupName	Destination network port group name. Used as an echo name in some error scenarios.		false	string

Response status

Response code	Description	schema
200	OK	ApiResponseLong

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	integer(int64)	integer(int64)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": null
}

2.8.35 Migrate VM (storage only)

API endpoint

PUT  /NSphere/api/vm-resource/migrate/storage

API description

Migrate a VM (storage only). On success, returns the task ID.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"diskFormat": "qcow2",
"diskMode": null,
"migrateRateType": 0,
"migrateRateLimitType": 0,
"migrateSpeed": "noLimit",
"rateLimitValue": 150,
"migrateTimeOut": null,
"storageInfoSet": [
{
"srcFile": "",
"srcPool": null,
"srcPoolTitle": null,
"srcDev": "",
"targetPath": null,
"targetPool": null,
"targetPoolTitle": null
}
],
"id": 0,
"migrateAcceleration": 0
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainMigrateStorageDTO	VM migration (storage) parameter entity.	body	true	ApiDomainMigrateStorageDTO	ApiDomainMigrateStorageDTO
diskFormat	Specified format. qcow2: smart, raw: high-speed. If omitted or empty, unchanged. Migration acceleration cannot be enabled at the same time when changing the storage format. The specified format takes effect only when the destination storage pool type is local file directory, shared file system, or NFS network file system.		false	string
diskMode	Disk pre-allocation. 0: lazy zeroed, 1: zeroed, 2: thin. If omitted or empty, unchanged. Migration acceleration cannot be enabled at the same time when changing pre-allocation. Ignored on hosts of version 730 or 760.		false	integer(int32)
migrateRateType	Migration policy. 0: migration priority, 1: business priority. Ignored on hosts of version 730 or 760. Migration priority applies to online VMs; when configured on an offline VM, the actual migration behaves as business priority + custom rate limit + no limit. Business priority is mutually exclusive with migration acceleration.		true	integer(int32)
migrateRateLimitType	Migration rate-limit policy. 0: auto rate limit, 1: manual rate limit. Effective when the migration policy is business priority. Auto rate limit applies to online VMs; on an offline VM configured with business priority + auto rate limit, actual migration behaves as custom rate limit + moderate. Ignored on hosts of version 730 or 760.		false	integer(int32)
migrateSpeed	Migration rate. noLimit: unlimited, normal: moderate, fast: fast, limitMax: capped at maximum. Ignored on hosts of version 730 or 760. Effective when the migration rate-limit policy is custom rate limit. When auto rate limit is configured and the VM migrates offline, the rate adapts to fast.		false	string
rateLimitValue	Maximum rate limit, in MB/s. Range: 1-12500. Effective when the migration rate is limitMax. Ignored on hosts of version 730 or 760.		false	integer(int64)
migrateTimeOut	Migration timeout, in minutes. Range: 5-1440. Migration is cancelled automatically when the timeout expires. Ignored on hosts of version 730 or 760. Effective when the VM is running or paused; if the VM goes offline during migration, this attribute is ignored. If an orchestration end time is also set, whichever cancels first triggers cancellation, and the later one cancels again if the migration task was not stopped.		false	integer(int64)
storageInfoSet	VM migration storage info.		true	array	ApiMigrateStorageInfoDTO
srcFile	Full path of the source VM storage volume.		true	string
srcPool	Source storage pool. Note: local disks (e.g. /dev/disk/by-path/pci-0000:18:00.0-scsi-0:1:0:0) have no storage pool.		false	string
srcPoolTitle	Display name of the storage pool holding the source file. Note: local disks (e.g. /dev/disk/by-path/pci-0000:18:00.0-scsi-0:1:0:0) have no storage pool.		false	string
srcDev	Source storage device name, e.g. vda.		true	string
targetPath	Destination storage path. Leave empty to indicate a special storage volume (local disk, iSCSI, FC block storage pool, logical volume). Otherwise it is required.		false	string
targetPool	Destination storage pool name. Leave empty to indicate a special storage volume (local disk, iSCSI, FC block storage pool, logical volume). Otherwise it is required.		false	string
targetPoolTitle	Destination storage pool display name.		false	string
id	VM ID		true	integer(int64)
migrateAcceleration	Migration acceleration. 0: off, 1: on. When enabled, storage format and pre-allocation must be left unchanged. Mutually exclusive with business priority. Ignored on hosts of version 730 or 760. Requires storage xcopy support; suited for copying data between LUNs on the same physical storage. Involves write amplification; recommended for VMs whose services are not latency-sensitive.		false	integer(int32)

Response status

Response code	Description	schema
200	OK	ApiResponseLong

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	integer(int64)	integer(int64)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": null
}

2.8.36 Modify VM name

API endpoint

PUT  /NSphere/api/vm-resource/name

API description

Modify VM name. At least one of VM ID and UUID must be provided. If both are provided, VM ID takes precedence.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"id": null,
"uuid": null,
"title": ""
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainModifyNameDTO	Modify-VM-name parameter entity.	body	true	ApiDomainModifyNameDTO	ApiDomainModifyNameDTO
id	VM ID		false	integer(int64)
uuid	VM UUID		false	string
title	New VM name		true	string

Response status

Response code	Description	schema
200	OK	ApiResponseVoid

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {}
}

2.8.37 Query VM network info

API endpoint

GET  /NSphere/api/vm-resource/network

API description

Query VM network info. At least one of vmId/vmUuid/vmName is required; they must not all be empty. If multiple are provided, they are used in the priority order vmId -> vmUuid -> vmName. New return attributes added in E0930.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
vmName	VM name (domainName)	query	false	string
vmId	VM ID	query	false	integer(int64)
vmUuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainNetworkInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainNetworkInfoVO
domainId	VM ID	integer(int64)
title	VM display name. New attribute added in E0930.	string
vmUuid	VM UUID	string
mac	vNIC MAC address	string
ipAddr	vNIC IP address	string
ipv6	vNIC IPv6 address	string
vsName	vSwitch name	string
mode	VM vNIC forwarding mode. Allowed values: dvs (corresponds to vSwitch forwarding mode VXLAN (SDN)), veb.	string
maskAddr	Subnet mask	string
mtu	MTU value	integer(int64)
vlan	VLAN value	integer(int32)
netType	vNIC type. 0: bridge, 1: NAT, 2: no network, 3: physical passthrough, 4: SR-IOV. New attribute added in E0930.	integer(int32)
deviceModel	Driver model (rtl8139, virtio, e1000). New attribute added in E0930.	string
isKernelAccelerated	Kernel acceleration. Effective when the vNIC driver is virtio. 1: accelerated, 0: not. New attribute added in E0930.	integer(int32)
vsMode	vSwitch forwarding mode. 0: veb, 1: vepa, 2: multi-channel, 3: distributed. New attribute added in E0930.	integer(int32)
virtualport	Whether vport is configured. New attribute added in E0930.	boolean
inAvgBandwidth	Inbound average bandwidth, in Kbps	integer(int64)
inBurst	Inbound burst buffer size, in KBytes	integer(int64)
outAvgBandwidth	Outbound average bandwidth, in Kbps	integer(int64)
outBurst	Outbound burst buffer size, in KBytes	integer(int64)
limitInBound	Whether inbound traffic limit is enabled	boolean
limitOutBound	Whether outbound traffic limit is enabled	boolean
gateway	Gateway address	string
dns	Primary DNS server	string
secondDns	Secondary DNS server	string
ipv4Dhcp	Whether IPv4 DHCP is enabled	boolean
bindIp	Whether IPv4 is bound	boolean
ipv6PrefixLength	IPv6 prefix length	integer(int32)
ipv6Gateway	IPv6 default gateway	string
ipv6Dns	IPv6 primary DNS server	string
ipv6SecondDns	IPv6 secondary DNS server	string
ipv6Mode	IPv6 mode	string
ipv6Dhcp	Whether IPv6 DHCP is enabled	boolean
bindIpv6	Whether IPv6 is bound	boolean
profileId	Network policy template ID	integer(int64)
profileName	Network policy template name	string
portgroupUUID	VXLAN port group UUID	string
firewalls	Virtual firewall rule	array	ApiDomainFirewallVO
id	Rule ID	integer(int64)
title	Rule name	string
ruleAction	Firewall type. 0: blacklist, 1: whitelist.	integer(int32)
firewallDefaultAction	VM firewall default action. -1: allow, 0: deny.	integer(int32)
vlanTrunkId	VLAN policy ID	string
vlanTrunkName	VLAN policy name	string
isDpdk	Whether it is a DPDK switch. New attribute added in E0930.	boolean

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"domainId": null,
"title": null,
"vmUuid": null,
"mac": null,
"ipAddr": null,
"ipv6": null,
"vsName": null,
"mode": null,
"maskAddr": null,
"mtu": null,
"vlan": null,
"netType": null,
"deviceModel": null,
"isKernelAccelerated": null,
"vsMode": null,
"virtualport": true,
"inAvgBandwidth": null,
"inBurst": null,
"outAvgBandwidth": null,
"outBurst": null,
"limitInBound": true,
"limitOutBound": true,
"gateway": null,
"dns": null,
"secondDns": null,
"ipv4Dhcp": true,
"bindIp": true,
"ipv6PrefixLength": null,
"ipv6Gateway": null,
"ipv6Dns": null,
"ipv6SecondDns": null,
"ipv6Mode": null,
"ipv6Dhcp": true,
"bindIpv6": true,
"profileId": null,
"profileName": null,
"portgroupUUID": null,
"firewalls": [
{
"id": null,
"title": null,
"ruleAction": null
}
],
"firewallDefaultAction": null,
"vlanTrunkId": null,
"vlanTrunkName": null,
"isDpdk": true
}
]
}

2.8.38 Modify VM network info

API endpoint

PUT  /NSphere/api/vm-resource/network

API description

Modify VM network info. Port groups, advanced networks, passthrough vNICs, and VXLAN vSwitches are not supported. New API added in E0930.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"id": 7,
"uuid": null,
"mac": "0c:da:41:1d:60:b0",
"newMac": "00:11:22:33:44:66",
"netType": 0,
"ipAddr": "192.168.1.10",
"maskAddr": "255.255.255.0",
"gateway": "192.168.1.1",
"dns": "8.8.8.8",
"secondDns": "8.8.4.4",
"ipv4Dhcp": false,
"ipv6": "2001:db8::10",
"ipv6PrefixLength": 64,
"ipv6Gateway": "2001:db8::1",
"ipv6Dns": "2001:4860:4860::8888",
"ipv6SecondDns": "2001:4860:4860::8844",
"ipv6Mode": "static",
"ipv6Dhcp": false,
"vlan": 100,
"mtu": 1500,
"location": null,
"bindIp": false,
"bindIpv6": false,
"vfNum": 1,
"resPoolId": 1,
"resPoolName": null,
"linkStatus": true,
"vsId": 3,
"vsName": "vs_bussiness",
"type": null,
"vsMode": null,
"deviceModel": "virtio",
"isKernelAccelerated": null,
"queues": null,
"inAvgBandwidth": null,
"inBurst": null,
"outAvgBandwidth": null,
"outBurst": null,
"mode": "veb",
"vsiId": null,
"virtualport": true,
"profileUUID": null,
"securityUUID": null,
"netUUID": null,
"portgroupUUID": null,
"ethName": null,
"driverType": null,
"hotPluggable": true,
"securityGroupId": null,
"vlanTrunkId": null,
"pvlanRuleId": null,
"tcpCheckSum": true,
"bindIpv4s": null,
"bindIpv6s": null,
"queueSize": null,
"inbound": false,
"outbound": false,
"profile": {
"id": 1,
"name": "",
"vsiEnable": true,
"vsiMngId": null,
"vsiTypeId": null,
"vsiTypeVer": null,
"vsiNetResId": null,
"vlanId": null,
"vsiIdFormat": null,
"netLimitId": 1
}
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainModifyNetworkDTO	ApiDomainModifyNetworkDTO	body	true	ApiDomainModifyNetworkDTO	ApiDomainModifyNetworkDTO
id	VM ID. VM ID and VM UUID: at least one is required. If both are provided, VM ID takes precedence.		false	integer(int64)
uuid	VM UUID. VM ID and VM UUID: at least one is required. If both are provided, VM ID takes precedence.		false	string
mac	MAC address		true	string
newMac	New MAC address, used to change the MAC address		false	string
netType	vNIC type. 0: bridge, 1: NAT, 2: no network.		false	integer(int32)
ipAddr	IPv4 address		false	string
maskAddr	Subnet mask		false	string
gateway	Gateway		false	string
dns	Primary DNS server		false	string
secondDns	Secondary DNS server		false	string
ipv4Dhcp	Whether IPv4 DHCP is enabled (true: on, false: off)		false	boolean
ipv6	IPv6 address		false	string
ipv6PrefixLength	IPv6 prefix length		false	integer(int32)
ipv6Gateway	IPv6 default gateway		false	string
ipv6Dns	IPv6 primary DNS server		false	string
ipv6SecondDns	IPv6 secondary DNS server		false	string
ipv6Mode	IPv6 mode		false	string
ipv6Dhcp	Whether IPv6 DHCP is enabled (true: on, false: off)		false	boolean
vlan	VLAN value		false	integer(int32)
mtu	vNIC MTU		false	integer(int64)
location	PCI address of the passthrough vNIC		false	string
bindIp	Whether IP is bound (true: bound, false: not)		false	boolean
bindIpv6	Whether IPv6 is bound (true: bound, false: not)		false	boolean
vfNum	Number of VFs on the vNIC		false	integer(int32)
resPoolId	Resource pool ID		false	integer(int64)
resPoolName	Resource pool name		false	string
linkStatus	Network interface link state (true: up, false: down)		false	boolean
vsId	ID of the vSwitch the vNIC is bound to		true	integer(int64)
vsName	vSwitch name		true	string
type	Network type IPv4 or IPv6		false	string
vsMode	vSwitch forwarding mode. 0: veb, 1: vepa, 2: multi-channel, 3: distributed.		false	integer(int32)
deviceModel	Driver model (rtl8139, virtio, e1000, smart).		true	string
isKernelAccelerated	Kernel acceleration. Effective when the vNIC driver is virtio. 1: accelerated, 0: not.		false	integer(int32)
queues	Queue count. Sets the number of queues for the VM vNIC. Multi-queue improves data-processing performance. Maximum is vCPU count x cores.		false	integer(int32)
inAvgBandwidth	Inbound average bandwidth (Kbps)		false	integer(int64)
inBurst	Inbound burst buffer size (KBytes)		false	integer(int64)
outAvgBandwidth	Outbound average bandwidth (Kbps)		false	integer(int64)
outBurst	Outbound burst buffer size (KBytes)		false	integer(int64)
mode	VM vNIC forwarding mode. Allowed values: vepa, dvs, veb.		true	string
vsiId	VSI ID		false	string
virtualport	Whether vport is configured. When configured, the VM can switch to a multi-channel vSwitch. true: configured, false: not.		false	boolean
profileUUID	Bound VCF policy template UUID		false	string
securityUUID	Bound VCF security policy UUID		false	string
netUUID	Bound VCF network UUID		false	string
portgroupUUID	Bound VCF port group UUID		false	string
ethName	Passthrough vNIC name		false	string
driverType	SR-IOV driver type. When the network type is SR-IOV, the driver type is vfio.		false	string
hotPluggable	Virtio-type hot-plug lookup (true: supported, false: not supported)		false	boolean
securityGroupId	Security group. Composed of security group ID plus action; action must be 0 or -1. Example: (1,-1).		false	string
vlanTrunkId	VLAN trunk ID		false	string
pvlanRuleId	Private VLAN rule ID		false	integer(int64)
tcpCheckSum	Whether TCP checksum is enabled (true: on, false: off)		false	boolean
bindIpv4s	Bound IPv4 address list. Multiple IPs are supported, separated by semicolons.		false	string
bindIpv6s	Bound IPv6 address list. Multiple IPs are supported, separated by semicolons.		false	string
queueSize	Queue depth (low: 256, high: 1024)		false	integer(int32)
inbound	Whether to limit inbound traffic (true: limit, false: no limit)		false	boolean
outbound	Whether to limit outbound traffic (true: limit, false: no limit)		false	boolean
profile			true	ApiProfile	ApiProfile
id	Network policy template ID		true	integer(int64)
name	Network policy template name		true	string
vsiEnable	Whether VSI is enabled (true: enabled, false: disabled)		false	boolean
vsiMngId	VSI manager ID		false	string
vsiTypeId	VSI type ID		false	integer(int64)
vsiTypeVer	VSI type version		false	integer(int64)
vsiNetResId	VSI network resource ID		false	integer(int64)
vlanId	VLAN ID		false	integer(int32)
vsiIdFormat	VSI ID format		false	string
netLimitId	Rate-limit policy ID		false	integer(int64)

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.39 Delete VM network

API endpoint

DELETE  /NSphere/api/vm-resource/network

API description

Delete a VM network. New API added in E0930.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"id": 0,
"name": null,
"title": null,
"network": {
"mac": ""
}
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainDeleteNetworkDTO	Delete VM network	body	true	ApiDomainDeleteNetworkDTO	ApiDomainDeleteNetworkDTO
id	VM ID		true	integer(int64)
name	VM name		false	string
title	VM display name		false	string
network	VM network info		true	NetworkInfo	NetworkInfo
mac	vNIC MAC address		true	string

Response status

Response code	Description	schema
200	OK	ApiResponseLong

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	integer(int64)	integer(int64)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": null
}

2.8.40 Set VM MAC binding

API endpoint

PUT  /NSphere/api/vm-resource/network/configIP

API description

Set VM MAC binding. New API added in E0930.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"id": 0,
"interList": [
{
"mac": "",
"fixedIp": {
"ips": []
},
"vip": {
"ips": []
},
"gateway": null,
"masterDns": null,
"slaveDns": null,
"gatewayV6": null,
"masterDnsV6": null,
"slaveDnsV6": null
}
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainConfigMultiIpNetDTO	VM network IP info	body	true	ApiDomainConfigMultiIpNetDTO	ApiDomainConfigMultiIpNetDTO
id	VM ID		true	integer(int64)
interList	Network info		true	array	ApiDomainMultiIpInfoDTO
mac	vNIC MAC address		true	string
fixedIp	IP info		false	ApiDomainIPInfoDTO	ApiDomainIPInfoDTO
ips	IP list		false	array	string
vip	IP info		false	ApiDomainIPInfoDTO	ApiDomainIPInfoDTO
ips	IP list		false	array	string
gateway	Gateway address		false	string
masterDns	Primary DNS server		false	string
slaveDns	Secondary DNS server		false	string
gatewayV6	IPv6 gateway		false	string
masterDnsV6	IPv6 primary DNS server		false	string
slaveDnsV6	IPv6 secondary DNS server		false	string

Response status

Response code	Description	schema
200	OK	ApiResponseLong

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	integer(int64)	integer(int64)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": null
}

2.8.41 Batch query VM network info

API endpoint

GET  /NSphere/api/vm-resource/network/list

API description

Batch query VM network info by hpId/clusterId/hostId. If none is provided, all are queried. When multiple are provided, hostId takes precedence; without hostId, hpId and clusterId are combined. New return attributes added in E0930 and E0930P01.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
offset	Offset. Specifies the record from which results start. Default 0. New parameter added in E0930.	query	false	integer(int32)
limit	Maximum records returned per page. Default 10. New parameter added in E0930.	query	false	integer(int32)
sortDir	Sort type. 0: no sort, 1: ascending, 2: descending. Defaults to no sort when sortField is not empty. New parameter added in E0930.	query	false	integer(int32)
sortField	Sort field. Supported fields: name, title. New parameter added in E0930.	query	false	string
hpId	VM data center ID	query	false	integer(int64)
clusterId	VM cluster ID	query	false	integer(int64)
hostId	VM host ID	query	false	integer(int64)

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainNetworkBatchInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainNetworkBatchInfoVO
id	VM ID	integer(int64)
vmUuid	VM UUID	string
title	VM display name	string
name	VM name	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
networks	VM network info	array	ApiBatchDomainNetworkVO
ipAddr	vNIC IP address	string
ipv6	vNIC IPv6 address	string
maskAddr	Subnet mask	string
vsName	vSwitch name	string
profileId	Network policy template ID	integer(int64)
profileName	Network policy template name	string
bindIp	Whether IPv4 is bound	boolean
bindIpv6	Whether IPv6 is bound	boolean
mac	vNIC MAC address	string
gateway	Gateway address	string
dns	Primary DNS server	string
secondDns	Secondary DNS server	string
ipv4Dhcp	Whether IPv4 DHCP is enabled	boolean
ipv6PrefixLength	IPv6 prefix length	integer(int32)
ipv6Gateway	IPv6 default gateway	string
ipv6Dns	IPv6 primary DNS server	string
ipv6SecondDns	IPv6 secondary DNS server	string
ipv6Mode	IPv6 mode	string
ipv6Dhcp	Whether IPv6 DHCP is enabled	boolean
mtu	MTU value	integer(int64)
portgroupUUID	VXLAN port group UUID	string
vlan	VLAN value	integer(int32)
mode	VM vNIC forwarding mode. Allowed values: dvs (corresponds to vSwitch forwarding mode VXLAN (SDN)), veb.	string
queues	Queue count	integer(int32)
netUUID	Bound VCF network	string
netType	vNIC type. 0: bridge, 1: NAT, 2: no network, 3: physical passthrough, 4: SR-IOV.	integer(int32)
location	Location	string
ethName	Host NIC name corresponding to SR-IOV	string
driverType	SR-IOV driver type. When the network type is SR-IOV, the driver type is vfio.	string
isKernelAccelerated	Kernel acceleration. Effective when the vNIC driver is virtio. 1: accelerated, 0: not.	integer(int32)
deviceModel	Driver model (rtl8139, virtio, e1000)	string
vsId	vSwitch ID	integer(int64)
vsMode	vSwitch forwarding mode. 0: veb, 1: vepa, 2: multi-channel, 3: distributed.	integer(int32)
virtualport	Whether vport is configured. New attribute added in E0930.	boolean
vsiId	VSI ID	string
vsiIdFormat	VSI ID format	string
vsiMngId	VSI manager ID	string
vsiTypeId	VSI type ID	string
vsiTypeVer	VSI type version	string
vsiNetResId	Network resource ID	string
tcpCheckSum	Whether TCP checksum is enabled. Required when kernel acceleration is enabled; optional otherwise.	boolean
firewalls	Virtual firewall rule	array	ApiDomainFirewallVO
id	Rule ID	integer(int64)
title	Rule name	string
ruleAction	Firewall type. 0: blacklist, 1: whitelist.	integer(int32)
firewallDefaultAction	VM firewall default action. -1: allow, 0: deny.	integer(int32)
vlanTrunkId	VLAN policy ID	string
vlanTrunkName	VLAN policy name	string
time	Sample time. New attribute added in E0930.	integer(int64)
readFlow	vNIC read throughput (Mbps). New attribute added in E0930.	number(double)
readPackets	vNIC read packet count. New attribute added in E0930.	number(double)
writeFlow	vNIC write throughput (Mbps). New attribute added in E0930.	number(double)
writePackets	vNIC write packet count. New attribute added in E0930.	number(double)
sendDropRate	vNIC send packet loss rate. New attribute added in E0930.	number(double)
receiveDropRate	vNIC receive packet loss rate. New attribute added in E0930.	number(double)
vmId	VM ID. New attribute added in E0930.	integer(int64)
vmTitle	VM display name. New attribute added in E0930.	string
inAvgBandwidth	Inbound average bandwidth, in Kbps. New attribute added in E0930P01.	integer(int64)
inBurst	Inbound burst buffer size, in KBytes. New attribute added in E0930P01.	integer(int64)
outAvgBandwidth	Outbound average bandwidth, in Kbps. New attribute added in E0930P01.	integer(int64)
outBurst	Outbound burst buffer size, in KBytes. New attribute added in E0930P01.	integer(int64)
limitInBound	Whether inbound traffic limit is enabled. New attribute added in E0930P01.	boolean
limitOutBound	Whether outbound traffic limit is enabled. New attribute added in E0930P01.	boolean

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"id": null,
"vmUuid": null,
"title": null,
"name": null,
"protectModel": null,
"networks": [
{
"ipAddr": null,
"ipv6": null,
"maskAddr": null,
"vsName": null,
"profileId": null,
"profileName": null,
"bindIp": true,
"bindIpv6": true,
"mac": null,
"gateway": null,
"dns": null,
"secondDns": null,
"ipv4Dhcp": true,
"ipv6PrefixLength": null,
"ipv6Gateway": null,
"ipv6Dns": null,
"ipv6SecondDns": null,
"ipv6Mode": null,
"ipv6Dhcp": true,
"mtu": null,
"portgroupUUID": null,
"vlan": null,
"mode": null,
"queues": null,
"netUUID": null,
"netType": null,
"location": null,
"ethName": null,
"driverType": null,
"isKernelAccelerated": null,
"deviceModel": null,
"vsId": null,
"vsMode": null,
"virtualport": true,
"vsiId": null,
"vsiIdFormat": null,
"vsiMngId": null,
"vsiTypeId": null,
"vsiTypeVer": null,
"vsiNetResId": null,
"tcpCheckSum": true,
"firewalls": [
{
"id": null,
"title": null,
"ruleAction": null
}
],
"firewallDefaultAction": null,
"vlanTrunkId": null,
"vlanTrunkName": null,
"time": null,
"readFlow": null,
"readPackets": null,
"writeFlow": null,
"writePackets": null,
"sendDropRate": null,
"receiveDropRate": null,
"vmId": null,
"vmTitle": null,
"inAvgBandwidth": null,
"inBurst": null,
"outAvgBandwidth": null,
"outBurst": null,
"limitInBound": true,
"limitOutBound": true
}
]
}
]
}

2.8.42 Batch query VM network info by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/network/list

API description

Batch query VM network info by ID/UUID list. The ID and UUID lists cannot both be empty. If both are provided, the ID list takes precedence. New return attributes added in E0930 and E0930P01.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"idList": [
1,
2,
3
],
"uuidList": [
"uuid-1",
"uuid-2"
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainBatchQueryDTO	VM ID/UUID list request entity	body	true	ApiDomainBatchQueryDTO	ApiDomainBatchQueryDTO
idList	VM ID list		false	array	integer(int64)
uuidList	VM UUID list		false	array	string

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainNetworkBatchInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainNetworkBatchInfoVO
id	VM ID	integer(int64)
vmUuid	VM UUID	string
title	VM display name	string
name	VM name	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
networks	VM network info	array	ApiBatchDomainNetworkVO
ipAddr	vNIC IP address	string
ipv6	vNIC IPv6 address	string
maskAddr	Subnet mask	string
vsName	vSwitch name	string
profileId	Network policy template ID	integer(int64)
profileName	Network policy template name	string
bindIp	Whether IPv4 is bound	boolean
bindIpv6	Whether IPv6 is bound	boolean
mac	vNIC MAC address	string
gateway	Gateway address	string
dns	Primary DNS server	string
secondDns	Secondary DNS server	string
ipv4Dhcp	Whether IPv4 DHCP is enabled	boolean
ipv6PrefixLength	IPv6 prefix length	integer(int32)
ipv6Gateway	IPv6 default gateway	string
ipv6Dns	IPv6 primary DNS server	string
ipv6SecondDns	IPv6 secondary DNS server	string
ipv6Mode	IPv6 mode	string
ipv6Dhcp	Whether IPv6 DHCP is enabled	boolean
mtu	MTU value	integer(int64)
portgroupUUID	VXLAN port group UUID	string
vlan	VLAN value	integer(int32)
mode	VM vNIC forwarding mode. Allowed values: dvs (corresponds to vSwitch forwarding mode VXLAN (SDN)), veb.	string
queues	Queue count	integer(int32)
netUUID	Bound VCF network	string
netType	vNIC type. 0: bridge, 1: NAT, 2: no network, 3: physical passthrough, 4: SR-IOV.	integer(int32)
location	Location	string
ethName	Host NIC name corresponding to SR-IOV	string
driverType	SR-IOV driver type. When the network type is SR-IOV, the driver type is vfio.	string
isKernelAccelerated	Kernel acceleration. Effective when the vNIC driver is virtio. 1: accelerated, 0: not.	integer(int32)
deviceModel	Driver model (rtl8139, virtio, e1000)	string
vsId	vSwitch ID	integer(int64)
vsMode	vSwitch forwarding mode. 0: veb, 1: vepa, 2: multi-channel, 3: distributed.	integer(int32)
virtualport	Whether vport is configured. New attribute added in E0930.	boolean
vsiId	VSI ID	string
vsiIdFormat	VSI ID format	string
vsiMngId	VSI manager ID	string
vsiTypeId	VSI type ID	string
vsiTypeVer	VSI type version	string
vsiNetResId	Network resource ID	string
tcpCheckSum	Whether TCP checksum is enabled. Required when kernel acceleration is enabled; optional otherwise.	boolean
firewalls	Virtual firewall rule	array	ApiDomainFirewallVO
id	Rule ID	integer(int64)
title	Rule name	string
ruleAction	Firewall type. 0: blacklist, 1: whitelist.	integer(int32)
firewallDefaultAction	VM firewall default action. -1: allow, 0: deny.	integer(int32)
vlanTrunkId	VLAN policy ID	string
vlanTrunkName	VLAN policy name	string
time	Sample time. New attribute added in E0930.	integer(int64)
readFlow	vNIC read throughput (Mbps). New attribute added in E0930.	number(double)
readPackets	vNIC read packet count. New attribute added in E0930.	number(double)
writeFlow	vNIC write throughput (Mbps). New attribute added in E0930.	number(double)
writePackets	vNIC write packet count. New attribute added in E0930.	number(double)
sendDropRate	vNIC send packet loss rate. New attribute added in E0930.	number(double)
receiveDropRate	vNIC receive packet loss rate. New attribute added in E0930.	number(double)
vmId	VM ID. New attribute added in E0930.	integer(int64)
vmTitle	VM display name. New attribute added in E0930.	string
inAvgBandwidth	Inbound average bandwidth, in Kbps. New attribute added in E0930P01.	integer(int64)
inBurst	Inbound burst buffer size, in KBytes. New attribute added in E0930P01.	integer(int64)
outAvgBandwidth	Outbound average bandwidth, in Kbps. New attribute added in E0930P01.	integer(int64)
outBurst	Outbound burst buffer size, in KBytes. New attribute added in E0930P01.	integer(int64)
limitInBound	Whether inbound traffic limit is enabled. New attribute added in E0930P01.	boolean
limitOutBound	Whether outbound traffic limit is enabled. New attribute added in E0930P01.	boolean

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"id": null,
"vmUuid": null,
"title": null,
"name": null,
"protectModel": null,
"networks": [
{
"ipAddr": null,
"ipv6": null,
"maskAddr": null,
"vsName": null,
"profileId": null,
"profileName": null,
"bindIp": true,
"bindIpv6": true,
"mac": null,
"gateway": null,
"dns": null,
"secondDns": null,
"ipv4Dhcp": true,
"ipv6PrefixLength": null,
"ipv6Gateway": null,
"ipv6Dns": null,
"ipv6SecondDns": null,
"ipv6Mode": null,
"ipv6Dhcp": true,
"mtu": null,
"portgroupUUID": null,
"vlan": null,
"mode": null,
"queues": null,
"netUUID": null,
"netType": null,
"location": null,
"ethName": null,
"driverType": null,
"isKernelAccelerated": null,
"deviceModel": null,
"vsId": null,
"vsMode": null,
"virtualport": true,
"vsiId": null,
"vsiIdFormat": null,
"vsiMngId": null,
"vsiTypeId": null,
"vsiTypeVer": null,
"vsiNetResId": null,
"tcpCheckSum": true,
"firewalls": [
{
"id": null,
"title": null,
"ruleAction": null
}
],
"firewallDefaultAction": null,
"vlanTrunkId": null,
"vlanTrunkName": null,
"time": null,
"readFlow": null,
"readPackets": null,
"writeFlow": null,
"writePackets": null,
"sendDropRate": null,
"receiveDropRate": null,
"vmId": null,
"vmTitle": null,
"inAvgBandwidth": null,
"inBurst": null,
"outAvgBandwidth": null,
"outBurst": null,
"limitInBound": true,
"limitOutBound": true
}
]
}
]
}

2.8.43 Unbind IP/MAC on VM vNIC

API endpoint

PUT  /NSphere/api/vm-resource/network/unbindIpMac

API description

Unbind IP/MAC on a VM vNIC. New API added in E0930.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
vmId	VM ID	query	true	integer(int64)
mac	vNIC MAC address	query	true	string
unbindIpv4	Unbind IPv4. Optional; defaults to unbinding when not provided.	query	false	boolean
unbindIpv6	Unbind IPv6. Optional; defaults to unbinding when not provided.	query	false	boolean

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.44 Pause VM by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/pause

API description

Pause a VM by ID/UUID. At least one of VM ID / UUID is required; they cannot both be empty. When both are provided, the operation follows the priority order ID -> UUID.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
id	VM ID	query	false	integer(int64)
uuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.45 Power off VM by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/poweroff

API description

Power off a VM by ID/UUID. At least one of VM ID / UUID is required; they cannot both be empty. When both are provided, the operation follows the priority order ID -> UUID.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
id	VM ID	query	false	integer(int64)
uuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.46 Restart VM by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/reboot

API description

Restart a VM by ID/UUID. At least one of VM ID / UUID is required; they cannot both be empty. When both are provided, the operation follows the priority order ID -> UUID.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
id	VM ID	query	false	integer(int64)
uuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.47 Restore VM

API endpoint

PUT  /NSphere/api/vm-resource/restore

API description

Restore VM

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
backupId	Backup ID.	query	true	integer(int64)
tmpDir	Temporary directory.	query	true	string
isForce	Whether to force restore.	query	true	boolean
useBackupPool	Whether to use the backup storage pool.	query	false	boolean

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.48 Resume VM by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/resume

API description

Resume a VM by ID/UUID. At least one of VM ID / UUID is required; they cannot both be empty. When both are provided, the operation follows the priority order ID -> UUID.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
id	VM ID	query	false	integer(int64)
uuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.49 Shut down VM by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/shutdown

API description

Shut down a VM by ID/UUID. At least one of VM ID / UUID is required; they cannot both be empty. When both are provided, the operation follows the priority order ID -> UUID.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
id	VM ID	query	false	integer(int64)
uuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.50 Hibernate VM by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/sleep

API description

Hibernate a VM by ID/UUID. At least one of VM ID / UUID is required; they cannot both be empty. When both are provided, the operation follows the priority order ID -> UUID.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
id	VM ID	query	false	integer(int64)
uuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.51 Query VM SPICE info

API endpoint

GET  /NSphere/api/vm-resource/spice

API description

Query VM SPICE info. At least one of vmId/vmUuid/vmName is required; they must not all be empty. If multiple are provided, they are used in the priority order vmId -> vmUuid -> vmName.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
vmName	VM name (domainName)	query	false	string
vmId	VM ID	query	false	integer(int64)
vmUuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiDomainSpiceInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiDomainSpiceInfoVO	ApiDomainSpiceInfoVO
id	VM ID	integer(int64)
uuid	VM UUID	string
domainName	VM name	string
hostIp	Host IP	string
port	SPICE port	integer(int32)
tlsPort	SPICE TLS port	integer(int32)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"id": null,
"uuid": null,
"domainName": null,
"hostIp": null,
"port": null,
"tlsPort": null
}
}

2.8.52 Batch query VM SPICE info

API endpoint

GET  /NSphere/api/vm-resource/spice/list

API description

Batch query VM SPICE info by hpId/clusterId/hostId. If none is provided, all are queried. When multiple are provided, hostId takes precedence; without hostId, hpId and clusterId are combined.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
offset	Offset. Specifies the record from which results start. Default 0. New parameter added in E0930.	query	false	integer(int32)
limit	Maximum records returned per page. Default 10. New parameter added in E0930.	query	false	integer(int32)
sortDir	Sort type. 0: no sort, 1: ascending, 2: descending. Defaults to no sort when sortField is not empty. New parameter added in E0930.	query	false	integer(int32)
sortField	Sort field. Supported fields: name, title. New parameter added in E0930.	query	false	string
hpId	VM data center ID	query	false	integer(int64)
clusterId	VM cluster ID	query	false	integer(int64)
hostId	VM host ID	query	false	integer(int64)

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainSpiceInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainSpiceInfoVO
id	VM ID	integer(int64)
uuid	VM UUID	string
domainName	VM name	string
hostIp	Host IP	string
port	SPICE port	integer(int32)
tlsPort	SPICE TLS port	integer(int32)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"id": null,
"uuid": null,
"domainName": null,
"hostIp": null,
"port": null,
"tlsPort": null
}
]
}

2.8.53 Batch query VM SPICE info by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/spice/list

API description

Batch query VM SPICE info by ID/UUID list. The ID and UUID lists cannot both be empty. If both are provided, the ID list takes precedence.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"idList": [
1,
2,
3
],
"uuidList": [
"uuid-1",
"uuid-2"
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainBatchQueryDTO	VM ID/UUID list request entity	body	true	ApiDomainBatchQueryDTO	ApiDomainBatchQueryDTO
idList	VM ID list		false	array	integer(int64)
uuidList	VM UUID list		false	array	string

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainSpiceInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainSpiceInfoVO
id	VM ID	integer(int64)
uuid	VM UUID	string
domainName	VM name	string
hostIp	Host IP	string
port	SPICE port	integer(int32)
tlsPort	SPICE TLS port	integer(int32)

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"id": null,
"uuid": null,
"domainName": null,
"hostIp": null,
"port": null,
"tlsPort": null
}
]
}

2.8.54 Start VM by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/start

API description

Start a VM by ID/UUID. At least one of VM ID / UUID is required; they cannot both be empty. When both are provided, the operation follows the priority order ID -> UUID.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
id	VM ID	query	false	integer(int64)
uuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.55 Query VM summary

API endpoint

GET  /NSphere/api/vm-resource/summary

API description

Query VM summary. At least one of vmId/vmUuid/vmName is required; they must not all be empty. If multiple are provided, they are used in the priority order vmId -> vmUuid -> vmName. New return attributes added in E0930.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
vmName	VM name (domainName)	query	false	string
vmId	VM ID	query	false	integer(int64)
vmUuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiDomainSummaryVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiDomainSummaryVO	ApiDomainSummaryVO
id	VM ID	integer(int64)
title	VM display name	string
domainName	VM name	string
desc	VM description. Maximum length 2048 characters.	string
hostName	VM host name	string
hostIp	VM host IP	string
hostId	VM host ID	integer(int64)
status	VM status	string
osVersion	VM operating system version	string
system	Guest operating system installed on the VM. 0: Windows, 1: Linux, 2: BSD.	integer(int32)
cpu	VM vCPU count	integer(int32)
cpuSocket	VM CPU socket count	integer(int32)
cpuCore	VM CPU cores per socket	integer(int32)
memory	VM memory	string
storage	VM total disk size	string
nspheretools	NSpheretools running status on the VM	string
nspheretoolRunning	Whether NSpheretools is running	boolean
hostBinding	0: standard VM; 1: host-bound VM (e.g. Hillstone VM).	integer(int32)
nspheretoolVersion	NSpheretools version	string
createTime	VM creation time	string
uptime	VM uptime, in minutes. -1 means unknown.	integer(int32)
lastOffTime	VM last power-off time	integer(int64)
uuid	VM UUID	string
osBit	VM architecture bits. Allowed values: x86_64, i686, or arch64.	string
autoConfig	VM auto-configuration	string
haStatus	HA status. 0: normal, 1: not joined to HA, 2: joined to HA but config file out of sync.	integer(int32)
haManage	HA status. 0: not managed by HA, 1: managed by HA.	integer(int32)
haRealStatus	Actual HA status. 0: off, 1: on.	integer(int32)
autoMigrate	Whether the VM allows auto-migration	string
protectModel	Whether the VM has protection mode enabled	string
protect	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
hostStatus	VM host status. 0: abnormal, 1: normal, 5: isolated mode.	integer(int32)
pageHostStatus	Host maintenance mode shown in the UI. 1: normal, 3: maintenance, 4: host maintenance (local storage failure).	integer(int32)
secretLevel	VM classification level. 4: top secret, 3: secret, 2: confidential, 1: internal.	string
isEncrypt	Whether the VM is encrypted	boolean
templateId	VM template ID	integer(int64)
secret	Flag indicating whether the VM is within the classified-policy security level	boolean
diskSecret	Whether any disk is encrypted	boolean
clusterSafety	Whether the cluster is a security zone	boolean
srmVm	Whether it is a disaster-recovery VM	boolean
cdpVm	Whether it is a CDP-imported VM	boolean
vmType	Low-order 2 bytes: VM category. Default 1 (standard VM). 101-200 are VDI-defined. High-order 2 bytes: VM type; bits number 0-31 from low to high, and the high 2 bytes span bits 16-31 with bits 17 and 16 used. 00: normal VM (shown as standard VM), 01: disaster-recovery source VM, 10: disaster-recovery target VM. Other bits unused.	integer(int32)
manageExistVm	Whether the VM is managed by BigCloud. 0: not managed, 1: managed.	integer(int32)
kaasVm	Whether the VM is a K8s cluster node. 0: no, 1: yes. For KaaS VMs and node components, kaasVm=1; for KaaS components, kaasVm=2.	integer(int32)
enableAntivirus	Whether the VM has antivirus configuration enabled.	boolean
antivirusStatus	VM antivirus status	string
currentStretchedHostGroupName	Name of the extended host group the VM currently belongs to	string
shouldInStretchedHostGroupName	Name of the extended host group the VM should belong to	string
ftStatus	VM FT status. 0: off, 1: primary, 2: secondary.	integer(int32)
ftGroupVmTitle	FT VM display name	string
componentVm	Whether it is a component VM	boolean
haEnable	Host HA status. 0: not in HA, 1: in HA.	integer(int32)
enableUltra	Whether the VM has Ultra mode enabled. 1: enabled; 0 or empty: disabled.	integer(int32)
hostPoolId	VM data center ID. New attribute added in E0930.	integer(int64)
clusterId	VM cluster ID. New attribute added in E0930.	integer(int64)
memRate	VM memory utilization (unit: %). New attribute added in E0930.	number(double)
cpuRate	VM CPU utilization (unit: %). New attribute added in E0930.	number(double)
ipAttributes	IP network info. New attribute added in E0930.	array	ApiDomainSummaryIpData
mac	MAC address.	string
ips	IP configuration.	array	ApiDomainSummaryIpConfig
ipAddress	IP address.	string
mask	Netmask.	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"id": null,
"title": null,
"domainName": null,
"desc": null,
"hostName": null,
"hostIp": null,
"hostId": null,
"status": null,
"osVersion": null,
"system": null,
"cpu": null,
"cpuSocket": null,
"cpuCore": null,
"memory": null,
"storage": null,
"nspheretools": null,
"nspheretoolRunning": true,
"hostBinding": null,
"nspheretoolVersion": null,
"createTime": null,
"uptime": null,
"lastOffTime": null,
"uuid": null,
"osBit": null,
"autoConfig": null,
"haStatus": null,
"haManage": null,
"haRealStatus": null,
"autoMigrate": null,
"protectModel": null,
"protect": null,
"hostStatus": null,
"pageHostStatus": null,
"secretLevel": null,
"isEncrypt": true,
"templateId": null,
"secret": true,
"diskSecret": true,
"clusterSafety": true,
"srmVm": true,
"cdpVm": true,
"vmType": null,
"manageExistVm": null,
"kaasVm": null,
"enableAntivirus": true,
"antivirusStatus": null,
"currentStretchedHostGroupName": null,
"shouldInStretchedHostGroupName": null,
"ftStatus": null,
"ftGroupVmTitle": null,
"componentVm": true,
"haEnable": null,
"enableUltra": null,
"hostPoolId": null,
"clusterId": null,
"memRate": null,
"cpuRate": null,
"ipAttributes": [
{
"mac": "0c:da:41:1d:03:30",
"ips": [
{
"ipAddress": null,
"mask": null
}
]
}
]
}
}

2.8.56 Modify VM summary

API endpoint

PUT  /NSphere/api/vm-resource/summary

API description

When the VM is running or paused, changes to clock setting, I/O priority, NSpheretools type, or hardware version take effect only after restarting the VM. New API added in E0930.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"id": 1,
"uuid": null,
"title": null,
"clock": "utc",
"blkiotune": 300,
"autoMigrate": true,
"desc": null,
"startPriority": -1,
"osha": 0,
"timeSync": false,
"haManage": true,
"vmPriority": 1,
"autoTools": true,
"nspheretoolsType": "virtio",
"enableIntegrityCheck": false,
"machineVersion": "5.0",
"seccomp": "disable",
"cpuExclusive": "disable",
"numaBalance": "disable",
"enableMultiQueue": false
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainModifySummaryDTO	Modify-VM-summary entity	body	true	ApiDomainModifySummaryDTO	ApiDomainModifySummaryDTO
id	VM ID. VM ID and VM UUID: at least one is required. If both are provided, VM ID takes precedence.		false	integer(int64)
uuid	VM UUID. VM ID and VM UUID: at least one is required. If both are provided, VM ID takes precedence.		false	string
title	VM display name. Maximum length 64 characters. Omitting this parameter leaves the display name unchanged.		false	string
clock	Clock setting. localtime: local time, utc: coordinated universal time.		true	string
blkiotune	VM I/O weight. 200: low, 300: medium, 500: high.		true	integer(int32)
autoMigrate	Whether auto-migration is enabled		true	boolean
desc	VM description. Maximum length 2048 characters.		false	string
startPriority	VM startup priority. -1: default, 0: low, 1: medium, 2: high.		false	integer(int32)
osha	Blue-screen fault policy. 0: no action, 1: fault restart, 2: fault migration. Default 0.		false	integer(int32)
timeSync	Whether time sync is enabled. Default false.		false	boolean
haManage	Whether managed by HA. null: no change. If the VM host has not joined a cluster or is not in HA, pass null.		false	boolean
vmPriority	VM business priority. 1: low, 2: medium, 4: high, null: no change.		false	integer(int32)
autoTools	Whether NSpheretools auto-upgrades. Default false.		false	boolean
nspheretoolsType	NSpheretools type. Allowed values: virtio (Virtio serial), serial (plain serial), null (no change).		false	string
enableIntegrityCheck	Whether integrity check is enabled. null: no change.		false	boolean
machineVersion	Hardware version. x86: 1.5 = pc-i440fx-1.5, 2.1 = pc-i440fx-2.1, 2.7 = pc-i440fx-2.7, 2.12 = pc-i440fx-2.12, 5.0 = pc-i440fx-5.0. arm: 2.12 = virt-2.12, 5.0 = virt-5.0. Default "5.0".		false	string
seccomp	VM escape protection. enable: on, disable: off, null: no change.		false	string
cpuExclusive	VM CPU exclusive. numa: enabled, disable: off, null: no change. numaBalance and cpuExclusive are mutually exclusive; only one can be enabled.		false	string
numaBalance	VM NUMA smart scheduling. enable: on, disable or null: off. numaBalance and cpuExclusive are mutually exclusive; only one can be enabled.		false	string
enableMultiQueue	Whether multi-queue acceleration is enabled. Default false.		false	boolean

Response status

Response code	Description	schema
200	OK	ApiResponseApiTaskMsgVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiTaskMsgVO	ApiTaskMsgVO
msgId	Message ID. Can be used to query task progress.	integer(int64)
targetId	Task target ID	integer(int64)
targetName	Task target name	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}

2.8.57 Batch query VM summary

API endpoint

GET  /NSphere/api/vm-resource/summary/list

API description

Batch query VM summary by hpId/clusterId/hostId. If none is provided, all are queried. When multiple are provided, hostId takes precedence; without hostId, hpId and clusterId are combined. New return attributes added in E0930.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
hpId	VM data center ID	query	false	integer(int64)
clusterId	VM cluster ID	query	false	integer(int64)
hostId	VM host ID	query	false	integer(int64)
offset	Offset. Specifies the record from which results start. Default 0. New parameter added in E0930.	query	false	integer(int32)
limit	Maximum records returned per page. Default 10. New parameter added in E0930.	query	false	integer(int32)
sortDir	Sort type. 0: no sort, 1: ascending, 2: descending. Defaults to no sort when sortField is not empty. New parameter added in E0930.	query	false	integer(int32)
sortField	Sort field. Supported fields: name, title, desc, mem, system. New parameter added in E0930.	query	false	string
domainName	VM name (domainName). New parameter added in E0930.	query	false	string
title	VM display name. New parameter added in E0930.	query	false	string
slaveClusterId	VM slave cluster ID. New parameter added in E0930.	query	false	integer(int64)
templetId	Template ID. New parameter added in E0930.	query	false	integer(int64)
enable	VM status. 1: VM, 2: template, 3: deleted VM, 4: creating, 5: OVF template. New parameter added in E0930.	query	false	integer(int32)

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainBatchSummaryVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainBatchSummaryVO
id	VM ID	integer(int64)
title	VM display name	string
name	VM name	string
computerName	Internal computer name	string
description	VM description. Maximum length 2048 characters.	string
hostId	VM host ID	integer(int64)
templateId	VM template ID	integer(int64)
hostName	VM host name	string
clusterName	Cluster name. New attribute added in E0930.	string
hpName	Data center name. New attribute added in E0930.	string
autoConfig	VNC port auto-config. 0: auto, 1: manual. New attribute added in E0930.	integer(int32)
clusterId	VM cluster ID. New attribute added in E0930.	integer(int64)
hostPoolId	VM data center ID.	integer(int64)
vmStatus	VM status	string
memRate	VM memory utilization (unit: %).	number(double)
cpuRate	VM CPU utilization (unit: %).	number(double)
cpu	VM vCPU count	integer(int32)
memory	VM memory	integer(int64)
osDesc	Guest OS description installed on the VM	string
system	Guest operating system installed on the VM. 0: Windows, 1: Linux, 2: BSD.	integer(int32)
autoRun	Auto-run. 0: auto, 1: manual. New attribute added in E0930.	integer(int32)
haStatus	HA status. 0: normal, 1: not joined to HA, 2: joined to HA but config file out of sync.	integer(int32)
haManage	HA status. 0: not managed by HA, 1: managed by HA.	integer(int32)
enable	VM status. 1: VM, 2: template, 3: deleted VM, 4: creating, 5: OVF template.	integer(int32)
createDate	VM creation date	string(date-time)
uuid	VM UUID	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
nspheretoolsStatus	NSpheretools status. 0: not running, 1: running.	integer(int32)
nspheretoolsVersion	NSpheretools version	string
antivirusEnable	Whether VM antivirus configuration is enabled. 1: enabled, 0: disabled.	integer(int32)
uptime	VM uptime, in minutes. -1 means unknown.	integer(int32)
hostBinding	0: standard VM; 1: host-bound VM (e.g. Hillstone VM).	integer(int32)
domainIps	VM IPs	array	string
vmType	Low-order 2 bytes: VM category. Default 1 (standard VM). 101-200 are VDI-defined. High-order 2 bytes: VM type; bits number 0-31 from low to high, and the high 2 bytes span bits 16-31 with bits 17 and 16 used. 00: normal VM (shown as standard VM), 01: disaster-recovery source VM, 10: disaster-recovery target VM. Other bits unused.	integer(int32)
ipAttributes	IP network info. New attribute added in E0930.	array	ApiDomainSummaryIpData
mac	MAC address.	string
ips	IP configuration.	array	ApiDomainSummaryIpConfig
ipAddress	IP address.	string
mask	Netmask.	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"id": null,
"title": null,
"name": null,
"computerName": null,
"description": null,
"hostId": null,
"templateId": null,
"hostName": null,
"clusterName": null,
"hpName": null,
"autoConfig": null,
"clusterId": null,
"hostPoolId": null,
"vmStatus": null,
"memRate": null,
"cpuRate": null,
"cpu": null,
"memory": null,
"osDesc": null,
"system": null,
"autoRun": null,
"haStatus": null,
"haManage": null,
"enable": null,
"createDate": null,
"uuid": null,
"protectModel": null,
"nspheretoolsStatus": null,
"nspheretoolsVersion": null,
"antivirusEnable": null,
"uptime": null,
"hostBinding": null,
"domainIps": [],
"vmType": null,
"ipAttributes": [
{
"mac": "0c:da:41:1d:03:30",
"ips": [
{
"ipAddress": null,
"mask": null
}
]
}
]
}
]
}

2.8.58 Batch query VM summary by ID/UUID list

API endpoint

PUT  /NSphere/api/vm-resource/summary/list

API description

Batch query VM summary by ID/UUID list. The ID and UUID lists cannot both be empty. If both are provided, the ID list takes precedence. New return attributes added in E0930.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"idList": [
1,
2,
3
],
"uuidList": [
"uuid-1",
"uuid-2"
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainBatchQueryDTO	VM ID/UUID list request entity	body	true	ApiDomainBatchQueryDTO	ApiDomainBatchQueryDTO
idList	VM ID list		false	array	integer(int64)
uuidList	VM UUID list		false	array	string

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainBatchSummaryVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainBatchSummaryVO
id	VM ID	integer(int64)
title	VM display name	string
name	VM name	string
computerName	Internal computer name	string
description	VM description. Maximum length 2048 characters.	string
hostId	VM host ID	integer(int64)
templateId	VM template ID	integer(int64)
hostName	VM host name	string
clusterName	Cluster name. New attribute added in E0930.	string
hpName	Data center name. New attribute added in E0930.	string
autoConfig	VNC port auto-config. 0: auto, 1: manual. New attribute added in E0930.	integer(int32)
clusterId	VM cluster ID. New attribute added in E0930.	integer(int64)
hostPoolId	VM data center ID.	integer(int64)
vmStatus	VM status	string
memRate	VM memory utilization (unit: %).	number(double)
cpuRate	VM CPU utilization (unit: %).	number(double)
cpu	VM vCPU count	integer(int32)
memory	VM memory	integer(int64)
osDesc	Guest OS description installed on the VM	string
system	Guest operating system installed on the VM. 0: Windows, 1: Linux, 2: BSD.	integer(int32)
autoRun	Auto-run. 0: auto, 1: manual. New attribute added in E0930.	integer(int32)
haStatus	HA status. 0: normal, 1: not joined to HA, 2: joined to HA but config file out of sync.	integer(int32)
haManage	HA status. 0: not managed by HA, 1: managed by HA.	integer(int32)
enable	VM status. 1: VM, 2: template, 3: deleted VM, 4: creating, 5: OVF template.	integer(int32)
createDate	VM creation date	string(date-time)
uuid	VM UUID	string
protectModel	Whether VM protection mode is enabled. 1: enabled, 0: disabled.	integer(int32)
nspheretoolsStatus	NSpheretools status. 0: not running, 1: running.	integer(int32)
nspheretoolsVersion	NSpheretools version	string
antivirusEnable	Whether VM antivirus configuration is enabled. 1: enabled, 0: disabled.	integer(int32)
uptime	VM uptime, in minutes. -1 means unknown.	integer(int32)
hostBinding	0: standard VM; 1: host-bound VM (e.g. Hillstone VM).	integer(int32)
domainIps	VM IPs	array	string
vmType	Low-order 2 bytes: VM category. Default 1 (standard VM). 101-200 are VDI-defined. High-order 2 bytes: VM type; bits number 0-31 from low to high, and the high 2 bytes span bits 16-31 with bits 17 and 16 used. 00: normal VM (shown as standard VM), 01: disaster-recovery source VM, 10: disaster-recovery target VM. Other bits unused.	integer(int32)
ipAttributes	IP network info. New attribute added in E0930.	array	ApiDomainSummaryIpData
mac	MAC address.	string
ips	IP configuration.	array	ApiDomainSummaryIpConfig
ipAddress	IP address.	string
mask	Netmask.	string

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"id": null,
"title": null,
"name": null,
"computerName": null,
"description": null,
"hostId": null,
"templateId": null,
"hostName": null,
"clusterName": null,
"hpName": null,
"autoConfig": null,
"clusterId": null,
"hostPoolId": null,
"vmStatus": null,
"memRate": null,
"cpuRate": null,
"cpu": null,
"memory": null,
"osDesc": null,
"system": null,
"autoRun": null,
"haStatus": null,
"haManage": null,
"enable": null,
"createDate": null,
"uuid": null,
"protectModel": null,
"nspheretoolsStatus": null,
"nspheretoolsVersion": null,
"antivirusEnable": null,
"uptime": null,
"hostBinding": null,
"domainIps": [],
"vmType": null,
"ipAttributes": [
{
"mac": "0c:da:41:1d:03:30",
"ips": [
{
"ipAddress": null,
"mask": null
}
]
}
]
}
]
}

2.8.59 Query VM VNC info

API endpoint

GET  /NSphere/api/vm-resource/vnc

API description

Query VM VNC info. At least one of vmId/vmUuid/vmName is required; they must not all be empty. If multiple are provided, they are used in the priority order vmId -> vmUuid -> vmName.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
vmName	VM name (domainName)	query	false	string
vmId	VM ID	query	false	integer(int64)
vmUuid	VM UUID	query	false	string

Response status

Response code	Description	schema
200	OK	ApiResponseApiDomainVncInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	ApiDomainVncInfoVO	ApiDomainVncInfoVO
vmId	VM ID	integer(int64)
vmName	VM name	string
vmUuid	VM UUID	string
hostIp	VM host IP	string
vncPort	VNC console IPv4 port	integer(int32)
vncPortIpv6	VNC console IPv6 port	integer(int32)
password	VNC console login password, returned Base64-encoded.	string
keyboardMap	Keyboard mapping	string
enableVncProxy	Whether VNC proxy is enabled	boolean

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"vmId": null,
"vmName": null,
"vmUuid": null,
"hostIp": null,
"vncPort": null,
"vncPortIpv6": null,
"password": null,
"keyboardMap": null,
"enableVncProxy": true
}
}

2.8.60 Batch query VM VNC info

API endpoint

GET  /NSphere/api/vm-resource/vnc/list

API description

Batch query VM VNC info by hpId/clusterId/hostId. If none is provided, all are queried. When multiple are provided, hostId takes precedence; without hostId, hpId and clusterId are combined.

Request Content-Type

application/x-www-form-urlencoded

Response Content-Type

application/json

Request parameters

Parameter name	Description	Location	Required	Type	schema
offset	Offset. Specifies the record from which results start. Default 0. New parameter added in E0930.	query	false	integer(int32)
limit	Maximum records returned per page. Default 10. New parameter added in E0930.	query	false	integer(int32)
sortDir	Sort type. 0: no sort, 1: ascending, 2: descending. Defaults to no sort when sortField is not empty. New parameter added in E0930.	query	false	integer(int32)
sortField	Sort field. Supported fields: name, title. New parameter added in E0930.	query	false	string
hpId	VM data center ID	query	false	integer(int64)
clusterId	VM cluster ID	query	false	integer(int64)
hostId	VM host ID	query	false	integer(int64)

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainVncInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainVncInfoVO
vmId	VM ID	integer(int64)
vmName	VM name	string
vmUuid	VM UUID	string
hostIp	VM host IP	string
vncPort	VNC console IPv4 port	integer(int32)
vncPortIpv6	VNC console IPv6 port	integer(int32)
password	VNC console login password, returned Base64-encoded.	string
keyboardMap	Keyboard mapping	string
enableVncProxy	Whether VNC proxy is enabled	boolean

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"vmId": null,
"vmName": null,
"vmUuid": null,
"hostIp": null,
"vncPort": null,
"vncPortIpv6": null,
"password": null,
"keyboardMap": null,
"enableVncProxy": true
}
]
}

2.8.61 Batch query VM VNC info by ID/UUID

API endpoint

PUT  /NSphere/api/vm-resource/vnc/list

API description

Batch query VM VNC info by ID/UUID list. The ID and UUID lists cannot both be empty. If both are provided, the ID list takes precedence.

Request Content-Type

application/json

Response Content-Type

application/json

Request example

{
"idList": [
1,
2,
3
],
"uuidList": [
"uuid-1",
"uuid-2"
]
}

Request parameters

Parameter name	Description	Location	Required	Type	schema
apiDomainBatchQueryDTO	VM ID/UUID list request entity	body	true	ApiDomainBatchQueryDTO	ApiDomainBatchQueryDTO
idList	VM ID list		false	array	integer(int64)
uuidList	VM UUID list		false	array	string

Response status

Response code	Description	schema
200	OK	ApiResponseListApiDomainVncInfoVO

Response parameters

Parameter name	Description	Type	schema
state	Response code. 0: success, 1: failure, 2: partial success	integer(int32)	integer(int32)
errorCode	Error code. Non-zero indicates a business error.	integer(int32)	integer(int32)
successMessage	Success message	string
failureMessage	Error message. Valid on failure or partial success.	string
data	Response data. When state is 0, contains the normal payload; when non-zero and non-empty, contains data needed to explain the exception.	array	ApiDomainVncInfoVO
vmId	VM ID	integer(int64)
vmName	VM name	string
vmUuid	VM UUID	string
hostIp	VM host IP	string
vncPort	VNC console IPv4 port	integer(int32)
vncPortIpv6	VNC console IPv6 port	integer(int32)
password	VNC console login password, returned Base64-encoded.	string
keyboardMap	Keyboard mapping	string
enableVncProxy	Whether VNC proxy is enabled	boolean

Response example

{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"vmId": null,
"vmName": null,
"vmUuid": null,
"hostIp": null,
"vncPort": null,
"vncPortIpv6": null,
"password": null,
"keyboardMap": null,
"enableVncProxy": true
}
]
}