QueryVmInstance

API Request

URLs
GET zstack/v1/vm-instances
GET zstack/v1/vm-instances/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 06771ba1b893402bb4c715b7acf3606e" \
-X GET http://localhost:8080/zstack/v1/vm-instances?q=name=vm1&q=vmNics.ip=192.168.20.100
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 95c7b190063f423ea6b305f054af8bf5" \
-X GET http://localhost:8080/zstack/v1/vm-instances/3b9c1b2bca5848459881bfad378540b5

Queryable Fields

You can check all queryable fields and resource names that can be queried across tables by using zstack-cli, entering QueryVmInstance, and pressing the Tab key.

API Response

Sample Response
{
  "inventories": [
    {
      "uuid": "bece18afd5af4a8cbcc87496aa3ae8a8",
      "name": "Test-VM",
      "description": "web server VM",
      "zoneUuid": "c0e8b8f5d43f454d8feccc0e1e5cf119",
      "clusterUuid": "e54efff1e153434395450e1dffa646df",
      "imageUuid": "21185daf4c3e46718be48005cbd7893d",
      "hostUuid": "474924e1b9c743119cb892e4223598d2",
      "lastHostUuid": "d059fbc6f21e44f1a9c5d84ee22c6913",
      "instanceOfferingUuid": "83c3e86180354d4e800104b9393842f7",
      "rootVolumeUuid": "b24130cd01b14e2ca1ee1e46fb0011bb",
      "platform": "Linux",
      "defaultL3NetworkUuid": "3d875625d62944069cd042aacf64b940",
      "type": "UserVm",
      "hypervisorType": "KVM",
      "memorySize": 8.589934592E9,
      "cpuNum": 1.0,
      "allocatorStrategy": "LastHostPreferredAllocatorStrategy",
      "createDate": "May 11, 2017 1:23:02 PM",
      "lastOpDate": "May 11, 2017 1:23:02 PM",
      "state": "Running",
      "vmNics": [
        {
          "uuid": "e4c2726154ba431d9b7d3fab19d5a969",
          "vmInstanceUuid": "bece18afd5af4a8cbcc87496aa3ae8a8",
          "usedIpUuid": "41be2de0c7e64c519e5ccc6f739f6094",
          "l3NetworkUuid": "3d875625d62944069cd042aacf64b940",
          "ip": "192.168.1.10",
          "mac": "00:0c:29:bd:99:fc",
          "netmask": "255.255.255.0",
          "gateway": "192.168.1.1",
          "deviceId": 0.0,
          "createDate": "May 11, 2017 1:23:02 PM",
          "lastOpDate": "May 11, 2017 1:23:02 PM"
        }
      ],
      "allVolumes": [
        {
          "uuid": "b24130cd01b14e2ca1ee1e46fb0011bb",
          "name": "Root-Volume-For-VM-bece18afd5af4a8cbcc87496aa3ae8a8",
          "primaryStorageUuid": "2fc0cd0b063543089d0c13b9fe37e706",
          "vmInstanceUuid": "bece18afd5af4a8cbcc87496aa3ae8a8",
          "diskOfferingUuid": "9cea3663fd2f4aa58232ad72ef7a423c",
          "rootImageUuid": "21185daf4c3e46718be48005cbd7893d",
          "installPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-b24130cd01b14e2ca1ee1e46fb0011bb/b24130cd01b14e2ca1ee1e46fb0011bb.qcow2",
          "type": "Root",
          "format": "qcow2",
          "size": 1.073741824E11,
          "actualSize": 2.147483648E10,
          "deviceId": 0.0,
          "state": "Enabled",
          "status": "Ready",
          "createDate": "May 11, 2017 1:23:02 PM",
          "lastOpDate": "May 11, 2017 1:23:02 PM"
        }
      ]
    }
  ]
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventories List See inventories. 0.6
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6
#inventories
Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
zoneUuid String The zone UUID. 0.6
clusterUuid String The cluster UUID. 0.6
imageUuid String The image UUID. 0.6
hostUuid String The host UUID. 0.6
lastHostUuid String 0.6
instanceOfferingUuid String The instance offering UUID. 0.6
rootVolumeUuid String The root volume UUID. 0.6
platform String 0.6
defaultL3NetworkUuid String 0.6
type String The VM instance type. Options:
  • UserVm
  • ApplianceVm
 0.6
hypervisorType String 0.6
memorySize Long 0.6
cpuNum Integer 0.6
cpuSpeed Long 0.6
allocatorStrategy String 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
state String The state of the VM instance. Options:
  • Created
  • Starting
  • Running
  • Stopping
  • Stopped
  • Rebooting
  • Destroying
  • Destroyed
  • Migrating
  • Expunging
  • Pausing
  • Paused
  • Resuming
  • VolumeMigrating
  • Unknown
 0.6
vmNics List See vmNics. 0.6
allVolumes List See allVolumes. 0.6
Note: The state of a VM instance can be changed as follows:
  • A VM instance in the Created state can be changed to the Starting, Destroying, or Destroyed state.
  • A VM instance in the Starting state can be changed to the Running, Stopped, Paused, Destroying, or Unknown state.
  • A VM instance in the Running state can be changed to the Destroying, Stopping, Stopped, Rebooting, Migrating, Pausing, Paused, or Unknown state.
  • A VM instance in the Stopping state can be changed to the Stopped, Destroying, Running, or Unknown state.
  • A VM instance in the Stopped state can be changed to the Starting, Running, Paused, Destroying, VolumeMigrating, or Unknown state.
  • A VM instance in the Migrating state can be changed to the Running, Stopped, Unknown, or Destroying state.
  • A VM instance in the VolumeMigrating state can be changed to the Stopped, Unknown, or Destroying state.
  • A VM instance in the Rebooting state can be changed to the Running, Stopped, Unknown, or Destroying state.
  • A VM instance in the Paused state can be changed to the Resuming, Stopped, Running, Stopping, Destroying, Unknown, or Migrating state.
  • A VM instance in the Pausing state can be changed to the Paused, Destroying, Running, or Unknown state.
  • A VM instance in the Resuming state can be changed to the Running, Destroying, Paused, or Unknown state.
  • A VM instance in the Unknown state can be changed to the Destroying, Stopping, Paused, Running, or Stopped state.
  • A VM instance in the Destroying state can be changed to the Unknown, Destroyed, Running, or Expunging state.
  • A VM instance in the Destroyed state can be changed to the Stopped state.
#vmNics
Name Type Description Starting Version
uuid String The resource UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
l3NetworkUuid String The L3 network UUID. 0.6
ip String The IP address. 0.6
mac String The MAC address. 0.6
hypervisorType String The hypervisor type. 0.6
netmask String The netmask. 0.6
gateway String The gateway. 0.6
metaData String 0.6
ipVersion Integer The IP version. 0.6
deviceId Integer The device ID. 0.6
type String The NIC type. 0.6
usedIps List For more information, see usedIps 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
#usedIps
Name Type Description Starting Version
uuid String The resource UUID. 0.6
ipRangeUuid String The IP range UUID. 0.6
l3NetworkUuid String The L3 network UUID. 0.6
ipVersion Integer The IP version. 3.1
ip String The IP address. 0.6
netmask String The netmask. 0.6
gateway String The gateway. 0.6
usedFor String 0.6
ipInLong long 0.6
vmNicUuid String The VM NIC UUID. 3.1
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
#allVolumes
Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
diskOfferingUuid String The disk offering UUID. 0.6
rootImageUuid String The root image UUID. 0.6
installPath String The installation path. 0.6
type String The volume type. 0.6
format String The volume format. 0.6
size Long The volume size. 0.6
actualSize Long The actual size of the volume. 0.6
deviceId Integer 0.6
state String The volume state. 0.6
status String The volume status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
isShareable Boolean 0.6
volumeQos String The volume QoS, in the format of total=1048576 3.2.0

SDK Sample

Java SDK
QueryVmInstanceAction action = new QueryVmInstanceAction();
action.conditions = asList("name=vm1","vmNics.ip=192.168.20.100");
action.sessionId = "1a2f35770a8e4e53b4bfb9d0d7ae7e50";
QueryVmInstanceAction.Result res = action.call();
Python SDK
QueryVmInstanceAction action = QueryVmInstanceAction()
action.conditions = ["name=vm1","vmNics.ip=192.168.20.100"]
action.sessionId = "0dd4f4ec663f4502ba3fedda9d0ebc1b"
QueryVmInstanceAction.Result res = action.call()