VirtualMachine
Applies To: System Center 2016 - Service Provider Foundation, System Center Technical Preview
VirtualMachines
Reads, creates, updates, and deletes virtual machines from Virtual Machine Manager (VMM). From this collection you can change the state of a virtual machine.
HTTP Verbs
| GET | POST | PUT | DELETE |
|---|---|---|---|
| Yes | Yes | Yes | Yes |
GET
Gets all virtual machines. This GET operation is further restricted by the available properties that you can add.
If you supply the ID property, the virtual machine with that identifier is returned.
If you supply the Name property, the virtual machine with that name is returned.
If you supply only the StampId property, all virtual machines that are assigned to the stamp are returned.
Entity Properties
| Name | Type | Mandatory | Description |
|---|---|---|---|
| StampId | Edm.Guid | No | The identifier of the stamp to restrict the query to |
| ID | Edm.Guid | No | The identifier of the virtual machine |
| Name | Edm.String | No | The name of the virtual machine |
POST
Creates a new virtual machine from either the specified virtual machine template or virtual hard disk.
Entity Properties
| Name | Type | Mandatory | Description |
|---|---|---|---|
| StampId | Edm.Guid | Yes | The identifier of the stamp to restrict the query to |
| Name | Edm.String | Yes | The name of the virtual machine |
| CloudId | Edm.Guid | Yes | The identifier of the cloud that this virtual machine will be associated with |
| VMTemplateId | Edm.Guid | No | The identifier of the template to create the virtual machine from |
| VirtualHardDiskId | Edm.Guid | No | The identifier of the virtual hard disk to create the virtual machine from |
| HardwareProfileId | Edm.Guid | No | The identifier of the hardware profile for this virtual machine |
| Description | Edm.String | No | The description of the virtual machine |
| CostCenter | Edm.String | No | The cost center that this virtual machine is grouped with |
| Tag | Edm.String | No | A user-defined data field |
| ComputerName | Edm.String | No | The name of the computer that this virtual machine represents |
| BlockDynamicOptimization | Edm.Boolean | No | Indicates whether dynamic optimization is blocked for this virtual machine |
| CPULimitForMigration | Edm.Boolean | No | When the value of this property is true, it limits processor features for the specified virtual machine to enable migration to a physical computer that has a different version of the same processor as the source computer. VMM does not support the migration of virtual machines between physical computers that have processors from different manufacturers. |
| CPULimitFunctionality | Edm.Boolean | No | Enables running an older operating system (such as Windows NT 4.0) on a virtual machine that is deployed on a Hyper-V host or on a VMware ESX host by providing limited CPU functionality for the virtual machine. |
| CPURelativeWeight | Edm.Int32 | No | Specifies the amount of CPU resources on a host that this virtual machine can use in relation 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. |
| DelayStartSeconds | Edm.Int32 | No | Specifies the number of seconds to wait after the virtualization service starts before automatically starting a virtual machine. This delay is used to stagger the startup time of multiple virtual machines to help reduce the demand on the physical computer’s resources. A typical setting might be 30 to 60 seconds. |
| Domain | Edm.String | No | Specifies a fully qualified domain name (FQDN) for an Active Directory domain. |
| DynamicMemoryBufferPercentage | Edm.Int32 | No | Specifies the percentage of memory above a virtual machine’s current memory allocation which the host should try to reserve as a buffer. The default value is 20. |
| DynamicMemoryEnabled | Edm.Boolean | No | When the value of this property is true, it enables dynamic memory for virtual machines. You can enable dynamic memory directly on a virtual machine or on a template or hardware profile that will be used to create virtual machines. The default value is false. |
| DynamicMemoryMaximumMB | Edm.Int32 | No | Specifies the maximum amount of memory that can be allocated to a virtual machine if dynamic memory is enabled. The default value is 65536. |
| FullName | Edm.String | No | The name of the person that this virtual machine is registered to |
| Memory | Edm.Int32 | No | Specifies, in megabytes (MB), the amount of random access memory (RAM) on the host that is allocated to a virtual machine. The default value is 512 MB. For a virtual machine on which dynamic memory is enabled (on a host running Windows Server 2008 R2 Service Pack 1 (SP1) or Windows Server 2012), this property represents the startup value. |
| MemoryWeight | Edm.Int32 | No | Indicates the priority in allocating memory to a virtual machine, in relation to other virtual machines on the same host. A virtual machine with a higher setting is allocated more memory resources than a virtual machine with a lower setting. |
| OrganizationName | Edm.String | No | Specifies the name of the organization for the person in whose name this virtual machine is registered. |
| StartAction | Edm.String | No | Specifies the behavior of a virtual machine when the virtualization service (Hyper-V, VMware, or XenServer) starts. Valid values are AlwaysAutoTurnOnVM, NeverAutoTurnOnVM, and TurnOnVMIfRunningWhenVSStopped. |
| StartVM | Edm.Boolean | No | Specifies that the virtual machine starts when it arrives at the destination host. |
| StopAction | Edm.String | No | Specifies the behavior of the virtual machine when the virtualization service (Hyper-V, VMware, or XenServer) stops. Valid values are SaveVM, TurnOffVM, and ShutdownGuestOS. |
| CPUCount | Edm.Byte | No | Specifies the number of CPUs on a virtual machine, a hardware profile, or a template. |
| Owner | UserAndRole | No | Specifies the user account of the owner of this virtual machine. |
| ProductKey | Edm.String | No | Specifies a product key. The product key is a 25-digit number that identifies the product license. A product key can be used to register VMM or an operating system to be installed on a virtual machine or host. |
| WorkGroup | Edm.String | No | Specifies the name of the workgroup to which you want to join this virtual machine. |
| TimeZone | Edm.Int32 | No | 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. |
| RunAsAccountUserName | Edm.String | No | Specifies the user name of the RunAsAccount of the virtual machine. |
| UserName | Edm.String | No | The user name of an account that has permissions to join the virtual machine to a domain |
| Password | Edm.String | No | Specifies the password that is associated with the UserName property. |
| LocalAdminRunAsAccountName | Edm.String | No | The name of the Run As account |
| LocalAdminUserName | Edm.String | No | The user account of the local administrator |
| LocalAdminPassword | Edm.String | No | Specifies the password that is associated with the LocalAdminUserName property. |
| NewVirtualNetworkAdapterInput | NewVMVirtualNetworkAdapterInput[] | Yes | A collection of network adapter information. Collection may be empty. |
| LinuxAdministratorSSHKey | Edm.String | No | Specifies the name of a public key file from the VMM library, for a Linux SSH Key. Warning: Currently unsupported. Use the LinuxAdministratorSSHKeyString property instead. |
| LinuxDomainName | Edm.String | No | Specifies an FQDN to be used in conjunction with Linux operating system specialization. |
| LinuxAdministratorSSHKeyString | Edm.String | No | Specifies the public key for the Linux SSH Key. |
PUT
Updates an existing virtual machine.
Entity Properties
| Name | Type | Mandatory | Description |
|---|---|---|---|
| StampId | Edm.Guid | Yes | The identifier of the stamp to restrict the query to |
| ID | Edm.Guid | Yes | The identifier of the virtual machine to update |
| CostCenter | Edm.String | No | The cost center that this virtual machine is grouped with |
| CPUCount | Edm.Byte | No | Specifies the number of CPUs on a virtual machine, on a hardware profile, or on a template. |
| CPUMax | Edm.Int32 | No | Specifies the highest percentage of the total resources of a single CPU on the host that can be used by this virtual machine at any given time. A value of 80 represents 80 percent. |
| CPUReserve | Edm.Int32 | No | Specifies the minimum percentage of the resources of a single CPU on the host to allocate to this virtual machine. The percentage of CPU capacity that is available to the virtual machine is never less than this percentage. |
| DelayStartSeconds | Edm.Int32 | No | Specifies the number of seconds to wait after the virtualization service starts before automatically starting a virtual machine. This delay is used to stagger the startup time of multiple virtual machines to help reduce the demand on the physical computer’s resources. A typical setting might be 30 to 60 seconds. |
| DeployPath | Edm.String | No | Specifies the path to use when deploying a stored virtual machine. |
| DiskIO | Edm.Int32 | No | Specifies the number of disk input/output operations per second (IOPS) on the host that can be used by this virtual machine. |
| Dismiss | Edm.Boolean | No | When the value of this property is true, it dismisses the last error on the virtual machine object. |
| VMNetworkAssignments | VMNetworkAssignments[] | Yes | Specifies the assigned network adapters and network pairs for this virtual machine. Collection may be empty. |
| Name | Edm.String | No | The name of the virtual machine |
| NetworkUtilization | Edm.Int32 | No | Specifies, in megabits per second (Mbps), the amount of bandwidth on the host's network that can be used by this virtual machine. |
| Owner | UserAndRole | No | Specifies the user account of the owner of this virtual machine. |
| GrantedToList | UserAndRole[] | Yes | The collection of user roles that have access to this virtual machine. Collection may be empty. |
| Tag | Edm.String | No | A user-defined data field |
| Operation | Edm.String | No | Controls the virtual machine. Valid values are: - Start - Stop - SaveState - DiscardSavedState - Suspend - Shutdown - Resume - Repair - Refresh - Reset - Store - Deploy |
| HighlyAvailable | Edm.Boolean | No | Specifies that a virtual machine will be placed on a Hyper-V host that is part of a host cluster. |
| Memory | Edm.Int32 | No | Specifies, in MB, the amount of RAM on the host that is allocated to a virtual machine. The default value is 512 MB. For a virtual machine on which dynamic memory is enabled (on a host running Windows Server 2008 R2 SP1 or Windows Server 2012), this property represents the startup value. |
| NumLock | Edm.Boolean | No | Enables the BIOS value for NumLock on a virtual machine (or on a template or hardware profile that is used to create virtual machines) on a Hyper-V host. This parameter does not apply to virtual machines on VMware ESX hosts or on Citrix XenServer hosts. |
| Retry | Edm.Boolean | No | When the value of this property is set to true, it retries the most recently failed job. |
| Description | Edm.String | No | The description of the virtual machine |
| SharePath | Edm.String | No | The Universal Naming Convention (UNC) path to a valid library share on an existing library server |
| StartAction | Edm.String | No | Specifies the behavior of a virtual machine when the virtualization service (Hyper-V, VMware, or XenServer) starts. Valid values are AlwaysAutoTurnOnVM, NeverAutoTurnOnVM, and TurnOnVMIfRunningWhenVSStopped. |
| StartVM | Edm.Boolean | No | Specifies that the virtual machine starts when it arrives at the destination host. |
| StopAction | Edm.String | No | Specifies the behavior of the virtual machine when the virtualization service (Hyper-V, VMware, or XenServer) stops. Valid values are SaveVM, TurnOffVM, and ShutdownGuestOS. |
| Undo | Edm.Boolean | No | If the value of this property is set to true, it reverses any changes that are made to this virtual machine. This property is available only when the most recent job has failed. |
| VMHostName | Edm.String | No | The name of the host virtual machine |
| CapabilityProfile | Edm.String | No | Specifies the capability profile. |
| Agent | Edm.Boolean | No | TBD |
| RelativeWeight | Edm.Int32 | No | TBD |
DELETE
Deletes an existing virtual machine.
Entity Properties
| Name | Type | Mandatory | Description |
|---|---|---|---|
| StampId | Edm.Guid | Yes | The identifier of the stamp to restrict the query to |
| ID | Edm.Guid | Yes | The identifier of the virtual machine to delete |