Managed Object - ServiceInstance

See also: Capability, Event, HostSystem, HostVMotionCompatibility, ResourcePool, ServiceContent, VirtualMachine, VirtualMachinePowerState

Managed Object Description

The ServiceInstance managed object is the singleton root object of the inventory. This instance might be implemented by a VirtualCenter server managing a collection of hosts or by a standalone host agent. The inventory of managed objects is as follows:


  Managed Objects:

    ServiceInstance  -- Root object
    Datacenter       -- A data center object
    Folder           -- Hierarchical folder
    VirtualMachine   -- A virtual machine
    ComputeResource  -- A compute resource
                          (either a cluster or a stand-alone host)
    ResourcePool     -- A subset of resources provided by a ComputeResource
    Host             -- A single host (ESX Server or GSX Server)

  The VirtualCenter hierarchy is organized as follows:

               ServiceInstance
                     !
                  Folder*
                     !
                 Datacenter   (Has references to Network and Datastore objects)
                     !
              -----------------
               !               !
             Folder*          Folder*
               !               !
         VirtualMachine  ComputeResource  (marked as stand-alone or cluster)
                               !
                        -----------------
                        !               !
                    ResourcePool*     Host+

 Legend:  * : Indicates that the objects can be nested.
          + : Indicates that one or more can be presented.

The host agent hierarchy has the same general form as the VirtualCenter hierarchy, but most of the objects are limited to one instance:


                ServiceInstance
                     !
                  Folder (1)
                     !
                 Datacenter  (1)
                     !
              -----------------
               !              !
             Folder (1)     Folder (1)
               !               !
         VirtualMachine  ComputeResource (1)
                               !
                        -----------------
                        !               !
                    ResourcePool*     Host (1)

 Legend: (1) Indicates exactly one of those instances. The only variable entries
 in the host agent tree are the number of virtual machines and the
 ResourcePool hierarchy.

Properties

Name	Type	Description
capability P	Capability	API-wide capabilities.
content P	ServiceContent	The properties of service instance. This property is identical to the return value from retrieveContent method. It is provided to allow for PropertyCollector driven inventory traversal from ServiceInstance object
serverClock P	xsd:dateTime	This property contains the time most recently obtained from the server. The time is not necessarily current. The intended use of this property is for clients to receive notification if the time on the server has been changed in a non-linear fashion. A client should not rely on this method to get the current time on the server; instead, the client should use the CurrentTime method.

PRequired privilege - see tooltip for details

Methods

Methods defined in this Managed Object
CurrentTime, QueryVMotionCompatibility, RetrieveServiceContent, ValidateMigration

CurrentTime

Returns the current time on the server.

If a client is interested in monitoring time changes, the serverClock property can be used.

Required Privileges: System.View

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the ServiceInstance used to make the method call.

Return Value

Type	Description
xsd:dateTime	The date and time on the server.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="CurrentTime">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="CurrentTimeResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:dateTime"/>
               </sequence>
            </complexType>
         </element>

QueryVMotionCompatibility

Investigates the general VMotion compatibility of a virtual machine with a set of hosts. The virtual machine may be in any power state. Hosts may be in any connection state and also may be in maintenance mode.

Required Privileges: Resource.QueryVMotion

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the ServiceInstance used to make the method call.
vm	ManagedObjectReference to a VirtualMachine	The virtual machine that is the designated VMotion candidate.
host	ManagedObjectReference[] to a HostSystem[]	The group of hosts to analyze for compatibility.
compatibility*	xsd:string[]	The set of compatibility types to investigate. Each is a string chosen from VMotionCompatibilityType. If this argument is not set, then all compatibility types are investigated.

*Need not be set

Return Value

Type	Description
HostVMotionCompatibility[]	An array where each element, associated with one of the input hosts, specifies which of the requested compatibility types applies to that host. If an input host has never been connected and therefore has no information available for determining its compatibility, it is omitted from the return list.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="QueryVMotionCompatibility">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="vm" type="vim2:ManagedObjectReference"/>
                  <element name="host" type="vim2:ManagedObjectReference" maxOccurs="unbounded"/>
                  <element name="compatibility" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="QueryVMotionCompatibilityResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2:HostVMotionCompatibility" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

RetrieveServiceContent

Retrieves the properties of the service instance.

Required Privileges: System.Anonymous

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the ServiceInstance used to make the method call.

Return Value

Type	Description
ServiceContent	The properties belonging to the service instance, including various object managers.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="RetrieveServiceContent">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="RetrieveServiceContentResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2:ServiceContent"/>
               </sequence>
            </complexType>
         </element>

ValidateMigration

Checks the validity of a set of proposed migrations. A migration is the act of changing the assigned execution host of a virtual machine, which can result from invoking MigrateVM_Task or RelocateVM_Task. For each of the virtual machines being tested, the privileges required are:

Resource.HotMigrate if the virtual machine is powered on.
Resource.ColdMigrate if the virtual machine is powered off or suspended.

Required Privileges: Dynamic - See discussion above

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the ServiceInstance used to make the method call.
vm	ManagedObjectReference[] to a VirtualMachine[]	The set of virtual machines intended for migration.
state*	VirtualMachinePowerState	The power state that the virtual machines must have. If this argument is not set, each virtual machine is evaluated according to its current power state.
testType*	xsd:string[]	The set of tests to run. If this argument is not set, all tests will be run.
pool* P	ManagedObjectReference to a ResourcePool	The target resource pool for the virtual machines. If the pool parameter is left unset, the target pool for each particular virtual machine's migration will be that virtual machine's current pool.
host*	ManagedObjectReference to a HostSystem	The target host on which the virtual machines will run. The host parameter may be left unset if the compute resource associated with the target pool represents a stand-alone host or a DRS-enabled cluster. In the former case the stand-alone host is used as the target host. In the latter case, each connected host in the cluster that is not in maintenance mode is tested as a target host.

*Need not be set P Required privilege: Resource.AssignVMToPool

Return Value

Type	Description
Event[]	A set of events that describe the warnings or errors that would apply if the proposed set of migrations were executed.

Faults

Type	Description
InvalidArgument	Thrown if the target host(s) and target pool for a migration are not associated with the same compute resource, or if the host parameter is left unset when the target pool is associated with a non-DRS cluster.
InvalidPowerState	Thrown if the state argument is set and at least one of the specified virtual machines is not in that power state.
InvalidState
NoActiveHostInCluster	Thrown if a target host is not specified and a cluster associated with a target pool does not contain at least one potential target host. A host must be connected and not in maintenance mode in order to be considered as a potential target host.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="ValidateMigration">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="vm" type="vim2:ManagedObjectReference" maxOccurs="unbounded"/>
                  <element name="state" type="vim2:VirtualMachinePowerState" minOccurs="0"/>
                  <element name="testType" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
                  <element name="pool" type="vim2:ManagedObjectReference" minOccurs="0"/>
                  <element name="host" type="vim2:ManagedObjectReference" minOccurs="0"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="ValidateMigrationResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2:Event" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>