Share via

VirtualMachine [SPFSDK][VMMREF]

  • Article

 

Applies To: Windows Azure Pack

The VirtualMachine entity represents virtual machine in Virtual Machine Manager (VMM).

Examples on how to the use this entity are at the bottom of this topic.

Inheritance Hierarchy

VMM
  VirtualMachine

Entity Properties

For more information about how the properties of an entity interact with HTTP operations, see Entity Basics.

Name

Create (PUT)

Read (GET)

Update (POST)

Delete (DELETE)

Type

Nullable

Description

ID

-

Optional

Required

Required

Edm.Guid

False

Key Property

The identifier of the entity.

StampId

Required

Optional

Required

Required

Edm.Guid

False

Key Property

The identifier of the stamp that restricts the query.

AddedTime

-

Optional

-

-

Edm.DateTime

True

When the virtual machine was added.

Agent

-

Optional

Optional

-

Edm.Boolean

True

This property is only used when the Operation property is set to Repair.

When True, indicates that the VMM in-guest agent should be repaired or upgraded.

AllocatedGPU

-

Optional

-

-

Edm.String

True

The identifier of the GPU used by this virtual machine.

BackupEnabled

-

Optional

-

-

Edm.Boolean

True

Indicates that backup is enable for this virtual machine.

BlockDynamicOptimization

Optional

Optional

-

-

Edm.Boolean

True

Whether dynamic optimization is blocked for a virtual machine.

BlockLiveMigrationIfHostBusy

-

Optional

-

-

Edm.Boolean

True

When True, live migration will not be available if the host is busy.

CanVMConnect

-

Optional

-

-

Edm.Boolean

True

When True, indicates that the virtual machine can be connected to.

CapabilityProfile

-

Optional

Optional

-

Edm.String

True

The associated capability profile.

CheckpointLocation

-

Optional

-

-

Edm.String

True

Location of the checkpoints associated with this virtual machine.

CloudId

Required

Optional

-

-

Edm.Guid

True

The identifier of the associated cloud.

CloudVMRoleName

-

Optional

-

-

Edm.String

True

The name of the VM Role this virtual machine is associated with.

ComputerName

Optional

Optional

-

-

Edm.String

True

The name of the computer that this virtual machine represents.

ComputerTierId

-

Optional

-

-

Edm.Guid

True

The identifier of a computer tier.

CostCenter

Optional

Optional

Optional

-

Edm.String

True

The cost center that this virtual machine is grouped with.

CPUCount

Optional

Optional

Optional

-

Edm.Byte

True

The number of CPUs on the virtual machine.

CPULimitForMigration

Optional

Optional

-

-

Edm.Boolean

True

Limit processor features to enable migration to a physical computer that has a different version of the same processor.

CPULimitFunctionality

Optional

Optional

-

-

Edm.Boolean

True

Limit CPU functions to enable running an older operating system.

CPUMax

-

Optional

Optional

-

Edm.Int32

True

The highest percentage of the total resources of a single CPU on the host that can be used by this virtual machine.

CPURelativeWeight

Optional

Optional

-

-

Edm.Int32

True

Specifies the amount of CPU resources on a host that this virtual machine can use relative to other virtual machines on the same host. A virtual machine with a higher setting is allocated more CPU resources than a virtual machine with a lower setting. The ranges of relative values for each type of host are as follows:

  • Hyper-V

    • 1 to 10000

  • Vmware ESX

    • 2000: High

    • 1500: Above Normal

    • 1000: Normal (default)

    • 750: Below Normal

    • 500: Low

    • 1 to 1000000: Custom

  • Citrix XenServer

    • 1 to 65536 (256 is Normal)

CPUReserve

-

Optional

Optional

-

Edm.Int32

True

The minimum percentage of the total resources of a single CPU on the host that can be used by this virtual machine.

CPUType

-

Optional

-

-

Edm.String

True

The type of CPU for the virtual machine, such as the speed and type.

CPUUtilization

-

Optional

-

-

Edm.Int32

True

How much of the CPU is being used.

CreationSource

-

Optional

-

-

Edm.String

True

The name of the object that create the virtual machine

CreationTime

-

Optional

-

-

Edm.DateTime

True

The date and time stamp of when this virtual machine was created.

DataExchangeEnabled

-

Optional

-

-

Edm.Boolean

True

When true, indicates that the KVP (Key-value pair) exchange service is enabled

DelayStart

-

Optional

-

-

Edm.Int32

True

The number of milliseconds to wait after the virtualization service starts before automatically starting a virtual machine.

DelayStartSeconds

Optional

Optional

Optional

-

Edm.Int32

True

The number of seconds to wait after the virtualization service starts before automatically starting a virtual machine.

DeploymentErrorInfo

-

Optional

-

-

ErrorInfo

True

Provides detailed error information if the deployment of the virtual machine fails.

DeployPath

-

Optional

Optional

-

Edm.String

True

This property is only used when the Operation property is set to Deploy.

The path to use when deploying a stored virtual machine.

Description

Optional

Optional

Optional

-

Edm.String

True

The description of the virtual machine.

DiskIO

-

Optional

Optional

-

Edm.Int32

True

The number of disk I/O operations per second (IOPS) on the host that can be used by this virtual machine.

Dismiss

-

Optional

Optional

-

Edm.Boolean

True

This property is only used when the Operation property is set to Repair.

If True, dismiss the last error on the virtual machine entity.

Domain

Optional

Optional

-

-

Edm.String

True

A fully qualified domain name (FQDN) for an Active Directory domain.

DynamicMemoryBufferPercentage

Optional

Optional

-

-

Edm.Int32

True

The percentage of the current memory allocation which the host should try to reserve as a buffer. The default value is 20.

DynamicMemoryDemandMB

-

Optional

-

-

Edm.Int32

True

For a dynamic memory enabled virtual machine, this represents the demand of memory (in MB). If this value is higher than the MemoryAssignedMB value, then the virtual machine is using more memory than assumed.

DynamicMemoryEnabled

Optional

Optional

-

-

Edm.Boolean

True

Whether dynamic memory is enabled. The default is False.

DynamicMemoryMaximumMB

Optional

Optional

-

-

Edm.Int32

True

The maximum amount of memory that can be allocated if dynamic memory is enabled. The default value is 65536.

Enabled

-

Optional

-

-

Edm.Boolean

True

Enables an object when set to True, or disables an object when set to False.

ExcludeFromPRO

-

Optional

-

-

Edm.Boolean

True

When True, indicates that this virtual machine should be excluded from Performance and Resource Optimization (PRO).

ExpectedCPUUtilization

-

Optional

-

-

Edm.Int32

True

The expected CPU utilization amount.

FailedJobID

-

Optional

-

-

Edm.Guid

True

The identifier of a failed job.

FullName

Optional

Optional

-

-

Edm.String

True

The name of the person this virtual machine is registered to.

Generation

-

Optional

-

-

Edm.Int32

True

The generation of virtual machine created.

GrantedToList

-

Optional

Optional

-

Collection(UserAndRole [SPFSDK][VMMREF])

False

The users and roles that have access to the virtual machine.

HardwareProfileId

Optional

Optional

-

-

Edm.Guid

True

The identifier of the hardware profile.

HasPassthroughDisk

-

Optional

-

-

Edm.Boolean

True

When True, indicates that the virtual machine has a pass through disk.

HasSavedState

-

Optional

-

-

Edm.Boolean

True

When True, indicates that the virtual machine has a saved state associated with it.

HasVMAdditions

-

Optional

-

-

Edm.Boolean

True

When True, indicates that the virtual machine has the Virtual Machines Additions installed on it.

HeartbeatEnabled

-

Optional

-

-

Edm.Boolean

True

When True, indicates that heartbeat has been enabled for the virtual machine.

HighlyAvailable

-

Optional

Optional

-

Edm.Boolean

True

This property is only used when the Operation property is set to Deploy.

The virtual machine will be placed on a Hyper-V host that is part of a host cluster.

IsFaultTolerant

-

Optional

-

-

Edm.Boolean

True

When True, indicates that the virtual machine is fault tolerant.

IsHighlyAvailable

-

Optional

-

-

Edm.Boolean

True

When True, indicates that the virtual machine is currently placed on a host cluster.

IsRecoveryVM

-

Optional

-

-

Edm.Boolean

True

When True, indicates that that this virtual machine is a recovery virtual machine.

IsUndergoingLiveMigration

-

Optional

-

-

Edm.Boolean

True

When True, indicates that the virtual machine is currently in a live migration.

LastRestoredCheckpointId

-

Optional

-

-

Edm.Guid

True

The identifier of the last checkpoint used to restore this virtual machine.

LibraryGroup

-

Optional

-

-

Edm.String

True

Not used.

LimitCPUForMigration

-

Optional

-

-

Edm.Boolean

True

Limit processor features to enable migration.

LimitCPUFunctionality

-

Optional

-

-

Edm.Boolean

True

Limit CPU functions to enable running an older operating system.

LinuxAdministratorSSHKey

Optional

Optional

-

-

Edm.String

True

Specifies the name of a public key file from the VMM library, of a Linux SSH Key.

This property is used when the virtual machine is being created from a template that is using a Linux operating system.

If specifying an SSH key, use either this property or LinuxAdministratorSSHKeyString, but not both.

LinuxAdministratorSSHKeyString

Optional

Optional

-

-

Edm.String

True

The public key for the Linux SSH Key.

This property is used when the virtual machine is being created from a template that is using a Linux operating system.

If specifying an SSH key, use either this property or LinuxAdministratorSSHKey, but not both.

LinuxDomainName

Optional

Optional

-

-

Edm.String

True

A fully qualified domain name (FQDN) to be used in conjunction with Linux operating system specialization.

LocalAdminPassword

Optional

Optional

-

-

Edm.String

True

The password associated with the LocalAdminUserName property.

LocalAdminRunAsAccountName

Optional

Optional

-

-

Edm.String

True

Not used.

LocalAdminUserName

Optional

Optional

-

-

Edm.String

True

The user name of the local administrator account.

Location

-

Optional

-

-

Edm.String

True

The file path of the virtual machine.

MarkedAsTemplate

-

Optional

-

-

Edm.Boolean

True

When True, indicates that this virtual machine has been flagged as a template.

Memory

Optional

Optional

Optional

-

Edm.Int32

True

The allocated memory in megabytes or the startup memory if dynamic memory is enabled.

MemoryAssignedMB

-

Optional

-

-

Edm.Int32

True

The amount of memory in use by the virtual machine in MB.

MemoryAvailablePercentage

-

Optional

-

-

Edm.Int16

True

The percentage (1-100) of memory available to the virtual machine.

MemoryWeight

Optional

Optional

-

-

Edm.Int32

True

The priority in allocating memory to this virtual machine in relation to other virtual machines on the same host.

ModifiedTime

-

Optional

-

-

Edm.DateTime

True

When the virtual machine was last modified.

MostRecentTaskId

-

Optional

-

-

Edm.Guid

True

The identifier of the most recent task.

Name

Required

Optional

Optional

-

Edm.String

True

The name of the virtual machine.

NetworkUtilization

-

Optional

Optional

-

Edm.Int32

True

The amount of bandwidth on the host's network that can be used by a specific virtual machine, in megabits per second (Mbps).

NewVirtualNetworkAdapterInput

Optional

Optional

-

-

Collection(NewVMVirtualNetworkAdapterInput [SPFSDK][VMMREF])

False

A collection of network adapter information used when creating a new virtual machine.

If the virtual machine is being created from a VM template, and this collection has network adapter information, adapter information must be provided for every network adapter defined by the VM template.

If the virtual machine is being created from a virtual hard disk, this collection is used to automate the creation of virtual network adapters and assign them to the specified VM networks.

NumLock

-

Optional

Optional

-

Edm.Boolean

True

If True, enables the BIOS value for NumLock on a virtual machine.

Not applicable on VMware ESX hosts or Citrix XenServer hosts.

OperatingSystem

-

Optional

-

-

Edm.String

True

The operating system running on the virtual machine.

OperatingSystemInstance

-

Optional

-

-

OperatingSystem [SPFSDK][VMMREF]

True

Describes the operating system of the virtual machine.

OperatingSystemShutdownEnabled

-

Optional

-

-

Edm.Boolean

True

When True, indicates that the operations system on the virtual machine supports shutdown.

Operation

-

Optional

Optional

-

Edm.String

True

Controls the virtual machine:

  • Start

  • Stop

  • SaveState

  • DiscardSavedState

  • Suspend

  • Shutdown

  • Resume

  • Repair

  • Refresh

  • Reset

  • Store

  • Deploy

OrganizationName

Optional

Optional

-

-

Edm.String

True

The name of the organization for the person in whose name a virtual machine is registered.

Owner

Optional

Optional

Optional

-

UserAndRole [SPFSDK][VMMREF]

True

The user account of the owner of this virtual machine.

Password

Optional

Optional

-

-

Edm.String

True

The password that is associated with the UserName property.

Path

-

Optional

-

-

Edm.String

True

Not used.

PerfCPUUtilization

-

Optional

-

-

Edm.Int32

True

Average CPU utilization of the virtual machine for the last ten minutes.

PerfDiskBytesRead

-

Optional

-

-

Edm.Int64

True

Average disk-read throughput (in bytes per second) of the virtual machine for the last ten minutes.

PerfDiskBytesWrite

-

Optional

-

-

Edm.Int64

True

Average disk-write throughput (in bytes per second) of the virtual machine for the last ten minutes.

PerfNetworkBytesRead

-

Optional

-

-

Edm.Int64

True

Average network-read throughput (in bytes per second) of the virtual machine for the last ten minutes.

PerfNetworkBytesWrite

-

Optional

-

-

Edm.Int64

True

Average network-write throughput (in bytes per second) of the virtual machine for the last ten minutes.

ProductKey

Optional

Optional

-

-

Edm.String

True

The product license key for the operating system.

Retry

-

Optional

Optional

-

Edm.Boolean

True

This property is only used when the Operation property is set to Repair.

If True, retry the most recently failed job.

RunAsAccountUserName

Optional

Optional

-

-

Edm.String

True

The user name of the run as account for this virtual machine.

RunGuestAccount

-

Optional

-

-

Edm.String

True

The run guest account.

ServiceDeploymentErrorMessage

-

Optional

-

-

Edm.String

True

If the virtual machine was deployed as part of a service, and failed, this is the error message.

ServiceId

-

Optional

-

-

Edm.Guid

True

The identifier of the associated service.

SharePath

-

Optional

Optional

-

Edm.String

True

This property is only used when the Operation property is set to Store.

The Universal Naming Convention (UNC) path to a valid library share on an existing library server.

SourceObjectType

-

Optional

-

-

Edm.String

True

The type of object that created the virtual machine, such as a VM Template.

StartAction

Optional

Optional

Optional

-

Edm.String

True

The behavior of a virtual machine when the virtualization service starts.

  • AlwaysAutoTurnOnVM

  • NeverAutoTurnOnVM

  • TurnOnVMIfRunningWhenVSStopped

StartVM

Optional

Optional

Optional

-

Edm.Boolean

True

This property is used when the Operation property is set to Deploy or when the virtual machine is created for the first time.

If True, start the VM when it arrives at the destination host.

Status

-

Optional

-

-

Edm.String

True

The state of the virtual machine.

StatusString

-

Optional

-

-

Edm.String

True

A friendly string describing the state of the virtual machine.

StopAction

Optional

Optional

Optional

-

Edm.String

True

The behavior of a virtual machine when the virtualization service stops.

  • SaveVM

  • TurnOffVM

  • ShutdownGuestOS

Tag

Optional

Optional

Optional

-

Edm.String

True

Extra information attached to this instance.

TimeSynchronizationEnabled

-

Optional

-

-

Edm.Boolean

True

Whether time synchronization is enabled.

TimeZone

Optional

Optional

-

-

Edm.Int32

True

Specifies a number (an index) that identifies a geographical region that shares the same standard time. For a list of index numbers and corresponding time zones, see Microsoft Time Zone Index Values.

TotalSize

-

Optional

-

-

Edm.Int64

True

The size of the virtual machine.

Undo

-

Optional

Optional

-

Edm.Boolean

True

This property is only used when the Operation property is set to Repair.

If True, reverse any changes made to this virtual machine.

UndoDisksEnabled

-

Optional

-

-

Edm.Boolean

True

When True, indicates that undo disks have been.

UpgradeDomain

-

Optional

-

-

Edm.Int32

True

The assigned upgrade domain. A value starting at zero, this groups virtual machines in a service together.

Those with the same UpgradeDomain values, starting with the lowest numbered group, will be serviced at the same time. The next ascending value-group will be serviced until all have been completed.

UseCluster

-

Optional

-

-

Edm.Boolean

True

Not used.

UseLAN

-

Optional

-

-

Edm.Boolean

True

Not used.

UserName

Optional

Optional

-

-

Edm.String

True

The user name of an account that has permissions to join the virtual machine to a domain.

VirtualHardDiskId

Optional

Optional

-

-

Edm.Guid

True

The identifier of the associated virtual hard disk.

VirtualizationPlatform

-

Optional

-

-

Edm.String

True

The virtualization platform hosting the virtual machine.

VirtualMachineState

-

Optional

-

-

Edm.String

True

The state of the virtual machine.

VMBaseConfigurationId

-

Optional

-

-

Edm.Guid

True

Not used.

VMConfigResource

-

Optional

-

-

Edm.String

True

The virtual machine configuration resource.

VMConnection

-

Optional

-

-

Edm.Stream

False

The connection stream to the virtual machine.

VMCPath

-

Optional

-

-

Edm.String

True

The path to the XML configuration file for the virtual machine.

VMHostName

-

Optional

Optional

-

Edm.String

True

This property is only used when the Operation property is set to Deploy.

The name of the VM host to deploy the virtual machine to.

VMId

-

Optional

-

-

Edm.Guid

True

The identifier of the virtual machine.

VMNetworkAssignments

-

Optional

Optional

-

Collection(VMNetworkAssignment [SPFSDK][VMMREF])

False

This property is only used when the Operation property is set to Deploy.

Assigns the virtual network adapters of this virtual machine to the specified virtual network.

VMResource

-

Optional

-

-

Edm.String

True

The virtual machine resource name.

VMResourceGroup

-

Optional

-

-

Edm.String

True

The virtual machine resource group name.

VMTemplateId

Optional

Optional

-

-

Edm.Guid

True

The identifier of the template on which the virtual machine is based.

WorkGroup

Optional

Optional

-

-

Edm.String

True

The name of the workgroup to which to join the virtual machine.

Relationships

For more information about how the relationships of an entity are used, see Entity Basics.

Name

Relationship Type

From Property

To Entity

To Property

Cloud

One or None

Not specified

Cloud [SPFSDK][VMMREF]

Not specified

MostRecentTask

One or None

Not specified

Job [SPFSDK][VMMREF]

Not specified

FailedJob

One or None

Not specified

Job [SPFSDK][VMMREF]

Not specified

VirtualNetworkAdapters

Many

Not specified

VirtualNetworkAdapter [SPFSDK][VMMREF]

Not specified

VMCheckpoints

Many

Not specified

VMCheckPoint [SPFSDK][VMMREF]

Not specified

VirtualSCSIAdapters

Many

Not specified

VirtualSCSIAdapter [SPFSDK][VMMREF]

Not specified

VirtualHardDisks

Many

Not specified

VirtualHardDisk [SPFSDK][VMMREF]

Not specified

VirtualDVDDrives

Many

Not specified

VirtualDVDDrive [SPFSDK][VMMREF]

Not specified

VirtualDiskDrives

Many

Not specified

VirtualDiskDrive [SPFSDK][VMMREF]

Not specified

OData Operations

This entity does not have any OData operations.

Notes

The RunAsynchronously query parameter may be added to the URL (with a value of 1) of an Update operation. This will tell the service to return immediately after the request is sent instead of waiting for the update to finish, which may cause the request to timeout. For example:

https://contoso.com:30005/ae122d5f-3aab-4d75-ad48-d6593246a49e/services/systemcenter/vmm/VirtualMachines(ID=guid'38c9c3b9-9288-4d7a-82fa-501cd4eb9ecb',StampId=guid'd70c1a9b-c241-48f5-880a-b6c36071e653')?RunAsynchronously=1

Examples

See Also

Entities [SPFSDK][VMMREF]
VirtualMachines Collection [SPFSDK][VMMREF]
VMTemplate [SPFSDK][VMMREF]
HardwareProfile [SPFSDK][VMMREF]