Virtual Infrastructure APIs

API Categories

This managed object type defines an alarm that is triggered and an action that occurs due to the triggered alarm when certain conditions are met on a specific ManagedEntity object.

alarm-manager

The alarm manager is a singleton object for managing alarms within a service instance.

authorization-manager

This managed object provides operations to query and update roles and permissions.

Privileges are the basic individual rights required to perform operations. They are statically defined and never change for a single version of a product. Examples of privileges are "Power on a virtual machine" or "Configure a host."

Roles are aggregations of privileges, used for convenience. For user-defined roles, the system-defined privileges, "System.Anonymous", "System.View", and "System.Read" are always present.

Permissions are the actual access-control rules. A permission is defined on a ManagedEntity and specifies the user or group ("principal") to which the rule applies. The role specifies the privileges to apply, and the propagate flag specifies whether or not the rule applies to sub-objects of the managed entity.

A ManagedEntity may have multiple permissions, but may have only one permission per user or group. If, when logging in, a user has both a user permission and a group permission (as a group member) for the same entity, then the user-specific permission takes precedent. If there is no user-specific permission, but two or more group permissions are present, and the user is a member of the groups, then the privileges are the union of the specified roles.

Managed entities may be collected together into a "complex entity" for the purpose of applying permissions consistently. Complex entities may have a Datacenter, ComputeResource, or ClusterComputeResource as a parent, with other child managed objects as additional parts of the complex entity:

A Datacenter's child objects are the root virtual machine and host Folders.
A ComputeResource's child objects are the root ResourcePool and HostSystem.
A ClusterComputeResource has only the root ResourcePool as a child object.

Child objects in a complex entity are forced to inherit permissions from the parent object. When query operations are used to discover permissions on child objects of complex entities, different results may be returned for the owner of the permission. In some cases, the child object of the complex entity is returned as the object that defines the permission, and in other cases, the parent from which the permission is propagated is returned as the object that defines the permission. In both cases, the information about the owner of the permission is correct, since the entities within a complex entity are considered equivalent. Permissions defined on complex entities are always applicable on the child entities, regardless of the propagation flag, but may only be defined or modified on the parent object.

In a group of fault-tolerance (FT) protected VirtualMachines, the secondary VirtualMachines are forced to inherit permissions from the primary VirtualMachine. Queries to discover permissions on FT secondary VMs always return the primary VM as the object that defines the permissions. Permissions defined on an FT primary VM are always applicable on its secondary VMs, but can only be defined or modified on the primary VM.

certificate-manager

CertificateManager provides an interface for managing the SSL certificates used by the ESX server.

cluster-compute-resource

The ClusterComputeResource data object aggregates the compute resources of associated HostSystem objects into a single compute resource for use by virtual machines.

The cluster services such as HA (High Availability), DRS (Distributed Resource Scheduling), and EVC (Enhanced vMotion Compatibility), enhance the utility of this single compute resource.

Use the Folder.CreateClusterEx method to create an instance of this object.

cluster-evcmanager

Controls Enhanced vMotion Compatibility mode for a particular cluster given by managedCluster.

VMware Enhanced vMotion Compatibility (EVC) facilitates vMotion between different CPU generations through the use of Intel Flex Migration and AMD-V Extended Migration technologies. When enabled for a cluster, EVC ensures that all VMs are vMotion-compatible with the CPUs of all hosts in the cluster.

See also EVCMode.

cluster-profile

cluster-profile-manager

compute-resource

Represents a set of physical compute resources for a set of virtual machines.

The base type ComputeResource, when instantiated by calling AddStandaloneHost_Task, represents a single host. The subclass ClusterComputeResource represents a cluster of hosts and adds distributed management features such as availability and resource scheduling.

A ComputeResource always has a root ResourcePool associated with it. Certain types of clusters such as those with VMware DRS enabled and standalone hosts (ESX Server 3) support the creation of ResourcePool hierarchies.

container-view

The ContainerView managed object provides a means of monitoring the contents of a single container and, optionally, other containers.

You can use a ContainerView with a PropertyCollector method to retrieve data or receive notification of changes. For information about using views with the PropertyCollector, see the description of ViewManager.

When you invoke the CreateContainerView method, you specify a managed object instance that provides the starting point for object selection. You can use the following managed objects as the basis of a container view:

Once you have created the view, the view list always represents the current configuration of the virtual environment and reflects any subsequent changes that occur.

crypto-manager

Singleton Managed Object used to manage cryptographic keys.

crypto-manager-host

crypto-manager-host-kms

crypto-manager-kmip

Singleton Managed Object used to manage cryptographic keys.

custom-fields-manager

The CustomFieldsManager object is used to add and remove custom fields to managed entities.

The custom fields values set on managed entities are available through the customValue property and through the summary objects for VirtualMachine and HostSystem. They are not available directly through this managed object.

This functionality is only available through VirtualCenter.

customization-spec-manager

The CustomizationSpecManager managed object is used to manage customization specifications stored on the VirtualCenter server.

datacenter

The Datacenter managed object provides the interface to the common container object for hosts, virtual machines, networks, and datastores.

These entities must be under a distinct datacenter in the inventory, and datacenters may not be nested under other datacenters.

Every Datacenter has the following set of dedicated folders. These folders are empty until you create entities for the Datacenter.

A folder for VirtualMachine, template, and VirtualApp objects.
A folder for a ComputeResource hierarchy.
A folder for Network, DistributedVirtualSwitch, and DistributedVirtualPortgroup objects.
A folder for Datastore objects.

For a visual representation of the organization of objects in a vCenter hierarchy, see the description of the ServiceInstance object.

datastore

Represents a storage location for virtual machine files.

A storage location can be a VMFS volume, a directory on Network Attached Storage, or a local file system path.

A datastore is platform-independent and host-independent. Therefore, datastores do not change when the virtual machines they contain are moved between hosts. The scope of a datastore is a datacenter; the datastore is uniquely named within the datacenter.

Any reference to a virtual machine or file accessed by any host within the datacenter must use a datastore path. A datastore path has the form "[<datastore>] <path>", where <datastore> is the datastore name, and <path> is a slash-delimited path from the root of the datastore. An example datastore path is "[storage] path/to/config.vmx".

You may use the following characters in a path, but not in a datastore name: slash (/), backslash (\), and percent (%).

All references to files in the VIM API are implicitly done using datastore paths.

When a client creates a virtual machine, it may specify the name of the datastore, omitting the path; the system, meaning VirtualCenter or the host, automatically assigns filenames and creates directories on the given datastore. For example, specifying My_Datastore as a location for a virtual machine called MyVm results in a datastore location of My_Datastore\MyVm\MyVm.vmx.

Datastores are configured per host. As part of host configuration, a HostSystem can be configured to mount a set of network drives. Multiple hosts may be configured to point to the same storage location. There exists only one Datastore object per Datacenter, for each such shared location. Each Datastore object keeps a reference to the set of hosts that have mounted the datastore. A Datastore object can be removed only if no hosts currently have the datastore mounted.

Thus, managing datastores is done both at the host level and the datacenter level. Each host is configured explicitly with the set of datastores it can access. At the datacenter, a view of the datastores across the datacenter is shown.

datastore-namespace-manager

The DatastoreNamespaceManager managed object exposes APIs for manipulating top-level directories of datastores which do not support the traditional top-level directory creation.

diagnostic-manager

Provides an interface for obtaining diagnostic information on a host (e.g.

generating and retrieving support logs on the host, reading audit records). For VirtualCenter, this includes the log files for the server daemon. For an ESX Server host, this includes detailed log files for the VMkernel.

distributed-virtual-portgroup

The DistributedVirtualPortgroup managed object defines how hosts and virtual machines connect to a network.

A distributed virtual portgroup specifies DistributedVirtualPort configuration options for the ports on a DistributedVirtualSwitch. A portgroup also represents a Network entity in the datacenter.

To configure host access by portgroup, set the portgroup in the host virtual NIC specification (HostVirtualNicSpec.portgroup).
To configure virtual machine access by portgroup, set the portgroup in the virtual Ethernet card backing (VirtualEthernetCard.backing.port.portgroupKey).

When you use a portgroup for network access, the Server will create a port according to config.type.

distributed-virtual-switch

A DistributedVirtualSwitch managed object is a virtual network switch that is located on a vCenter Server.

A distributed virtual switch manages configuration for proxy switches (HostProxySwitch). A proxy switch is located on an ESXi host that is managed by the vCenter Server and is a member of the switch. A distributed switch also provides virtual port state management so that port state is maintained when vCenter Server operations move a virtual machine from one host to another.

A proxy switch performs network I/O to support the following network traffic and operations:

Network traffic between virtual machines on any hosts that are members of the distributed virtual switch.
Network traffic between virtual machines that uses a distributed switch and a virtual machine that uses a VMware standard switch.
Network traffic between a virtual machine and a remote system on a physical network connected to the ESXi host.
vSphere system operations to support capabilities such as VMotion or High Availability.

A DistributedVirtualSwitch is the base distributed switch implementation. It supports a VMware distributed virtual switch implementation and it supports third party distributed switch implementations. The base implementation provides the following capabilities (DVSFeatureCapability):

NIC teaming
Network I/O control
Network resource allocation
Quality of service tag support
User-defined resource pools
I/O passthrough (VMDirectPath Gen2)

A VmwareDistributedVirtualSwitch supports the following additional capabilities (DVSFeatureCapability and VMwareDVSFeatureCapability):

Backup, restore, and rollback for a VMware distributed virtual switch and its associated portgroups.
Maximum Transmission Unit (MTU) configuration.
Health check operations for NIC teaming and VLAN/MTU support.
Monitoring switch traffic using Internet Protocol Flow Information Export (IPFIX).
Link Layer Discovery Protocol (LLDP).
Virtual network segmentation using a Private VLAN (PVLAN).
VLAN-based SPAN (VSPAN) for virtual distributed port mirroring.
Link Aggregation Control Protocol (LACP) defined for uplink portgroups.

Distributed Virtual Switch Configuration

To use a distributed virtual switch, you create a switch and portgroups on a vCenter Server, and add hosts as members of the switch.

Create a distributed virtual switch (Folder.CreateDVS_Task). Use a DVSConfigSpec to create a switch for a third-party implementation. Use a VMwareDVSConfigSpec to create a VMware distributed virtual switch.
Create portgroups (CreateDVPortgroup_Task) for host and virtual machine network connections and for the connection between proxy switches and physical NICs. A DistributedVirtualPortgroup specifies how virtual ports (DistributedVirtualPort) will be used. When you create a distributed virtual switch, the vCenter Server automatically creates one uplink portgroup (config.uplinkPortgroup). Uplink portgroups are distributed virtual portgroups that support the connection between proxy switches and physical NICs.

Port creation on a distributed switch is determined by the portgroup type (DVPortgroupConfigSpec.type):
- If a portgroup is early binding (static), then DVPortgroupConfigSpec.numPorts determines the number of ports that get created when the portgroup is created. This number can be increased if DVPortgroupConfigSpec.autoExpand is true.
- If a portgroup is ephemeral (dynamic), then numPorts is ignored and ports are created as needed.
You can also specify standalone ports that are not associated with a port group and uplink ports that are created on ESXi hosts (DVSConfigSpec.numStandalonePorts).

The DVPortgroupConfigInfo.numPorts property is the total number of ports for a distributed virtual switch. This total includes the ports generated by the static and dynamic portgroups and the standalone ports.
If you have created additional uplink portgroups, use the ReconfigureDvs_Task method to add the portgroup(s) to the DVSConfigSpec.uplinkPortgroup array.
Retrieve physical NIC device names from the host (HostSystem.config.network.pnic[].device).
Add host member(s) to the distributed virtual switch. To configure host members:
- Specify hosts (DVSConfigSpec.host[]).
- For each host, specify one or more physical NIC device names to identify the pNIC(s) for the host proxy connection to the network (DistributedVirtualSwitchHostMemberConfigSpec.backing.pnicSpec[].pnicDevice)
- Use the DistributedVirtualSwitch.ReconfigureDvs_Task method to update the switch configuration.
When you add a host to a distributed virtual switch (DistributedVirtualSwitch.config.host), the host automatically creates a proxy switch. The proxy switch is removed automatically when the host is removed from the distributed virtual switch.

Connect hosts and virtual machines to the distributed virtual switch.

Host connection	Specify port or portgroup connections in the host virtual NIC spec ([HostVirtualNicSpec](../../data-structures/HostVirtualNicSpec/).[distributedVirtualPort](../../data-structures/HostVirtualNicSpec/) or [HostVirtualNicSpec](../../data-structures/HostVirtualNicSpec/).[portgroup](../../data-structures/HostVirtualNicSpec/)).
Virtual machine connection	Specify port or portgroup connections in the distributed virtual port backing ([VirtualEthernetCardDistributedVirtualPortBackingInfo](../../data-structures/VirtualEthernetCardDistributedVirtualPortBackingInfo/)) for the virtual Ethernet cards on the virtual machine ([VirtualEthernetCard](../../data-structures/VirtualEthernetCard/).[backing](../../data-structures/VirtualDevice/)).

Backup, Rollback, and Query Operations

If you are using a VmwareDistributedVirtualSwitch, you can perform backup and rollback operations on the switch and its associated distributed virtual portgroups. When you reconfigure a VMware distributed virtual switch (ReconfigureDvs_Task), the Server saves the current switch configuration before applying the configuration updates. The saved switch configuration includes portgroup configuration data. The Server uses the saved switch configuration as a checkpoint for rollback operations. You can rollback the switch or portgroup configuration to the saved configuration, or you can rollback to a backup configuration (EntityBackupConfig).

To backup the switch and portgroup configuration, use the DistributedVirtualSwitchManager.DVSManagerExportEntity_Task method. The export method produces a EntityBackupConfig object. The backup configuration contains the switch and/or portgroups specified in the SelectionSet parameter. To backup the complete configuration you must select the distributed virtual switch and all of its portgroups.
To rollback the switch configuration, use the DVSRollback_Task method to determine if the switch configuration has changed. If it has changed, use the ReconfigureDvs_Task method to complete the rollback operation.
To rollback the portgroup configuration, use the DistributedVirtualPortgroup.DVPortgroupRollback_Task method to determine if the portgroup configuration has changed. If it has changed, use the ReconfigureDVPortgroup_Task method to complete the rollback operation.

To perform query operations on a distributed virtual switch, use the DistributedVirtualSwitchManager methods.

distributed-virtual-switch-manager

The DistributedVirtualSwitchManager provides methods that support the following operations:

Backup and restore operations for VmwareDistributedVirtualSwitch and associated DistributedVirtualPortgroup managed objects.
Query operations for information about portgroups and distributed virtual switches.
Distributed virtual switch configuration update operations.

environment-browser

This managed object type provides access to the environment that a ComputeResource presents for creating and configuring a virtual machine.

The environment consists of three main components:

The virtual machine configuration options. Each vim.vm.ConfigOption describes the execution environment for a virtual machine, the particular set of virtual hardware that is supported. A ComputeResource might support multiple sets. Access is provided through the configOptionDescriptor property and the QueryConfigOption operation.
The supported device targets. Each virtual device specified in the virtual machine needs to be hooked up to a "physical" counterpart. For networks, this means choosing a network name; for a virtual CD-rom this might be an ISO image, etc. The environment browser provides access to the device targets through the QueryConfigTarget operation.
Storage locations and files. A selection of locations where the virtual machine files can be stored, and the possibility to browse for existing virtual disks and ISO images. The datastore browser, provided by the datastoreBrowser property, provides access to the contents of one or more datastores. The items in a datastore are files that contain configuration, virtual disk, and the other data associated with a virtual machine.
The capabilities supported by the ComputeResource to which the virtual machine belongs.

event-history-collector

EventHistoryCollector provides a mechanism for retrieving historical data and updates when the server appends new events.

event-manager

This managed object type provides properties and methods for event management support.

Event objects are used to record significant state changes of managed entities.

extensible-managed-object

ExtensibleManagedObject provides methods and properties that provide access to custom fields that may be associated with a managed object.

Use the CustomFieldsManager to define custom fields. The CustomFieldsManager handles the entire list of custom fields on a server. You can can specify the object type to which a particular custom field applies by setting its managedObjectType. (If you do not set a managed object type for a custom field definition, the field applies to all managed objects.)

extension-manager

This managed object type provides directory and basic management services for all registered extensions.

Clients use the ExtensionManager, available in ServiceInstance, to access extension objects.

While several authentication methods are available for extension servers to use (see SessionManager), only one authentication method is valid for an extension at any given time.

failover-cluster-configurator

FailoverClusterConfigurator provides operations to create and configure a vCenter High Availability Cluster (VCHA Cluster).

failover-cluster-manager

FailoverClusterManager provides operations to manage a vCenter High Availability Cluster (VCHA Cluster).

A VCHA Cluster consists of three VMs. One is the Active vCenter VM that serves client requests. Second is the Passive VM that is identical to the Active vCenter VM in terms of resources and capabilities. Passive VM constantly receives updates from Active VM and takes over the role of Active vCenter VM in the event of failover. Third is the Witness VM that acts as a quorum VM in a VCHA Cluster. Sole purpose of Witness VM is to avoid classic split-brain problem in a VCHA Cluster. A VCHA Cluster has following states - 1. Healthy - All three nodes in a VCHA Cluster are healthy and connected. State replication between Active and Passive node is working and both nodes are in-sync. 2. Degraded - A VCHA Cluster is said to be in degraded state when it has lost one of the three nodes. Node loss can be due to various reasons and as a result the lost node is not visible to other two nodes. If an Active node is lost, Passive node will take the role of Active node. If Passive or Witness node is lost, Active node will continue to serve requests. A VCHA Cluster can also be in degraded state if state replication fails between Active and Passive nodes. 3. Isolated - All three nodes are isolated from each other. If this happens while VCHA Cluster is in enabled mode, Active node stops serving client requests. If nodes are isolated in a disabled VCHA Cluster mode, Active node continues to serve client requests. A VCHA Cluster has following modes - 1. Enabled - State replication between Active and Passive nodes is enabled and automatic failover happens if Active node fails while the VCHA Cluster is in a healthy state. 2. Disabled - All three nodes are part of VCHA Cluster but state replication and automatic failover is disabled. 3. Maintenance - All three nodes are part of VCHA Cluster but automatic failover is disabled while state replication continues. Active node continues to serve client requests even if Passive and Witness nodes are lost.

file-manager

This managed object type provides a way to manage and manipulate files and folders on datastores.

The source and the destination names are in the form of a URL or a datastore path.

A URL has the form

scheme://authority/folder/path?dcPath=dcPath&dsName=dsName

where

scheme is http or https.
authority specifies the hostname or IP address of the VirtualCenter or ESX server and optionally the port.
dcPath is the inventory path to the Datacenter containing the Datastore.
dsName is the name of the Datastore.
path is a slash-delimited path from the root of the datastore.

A datastore path has the form

[datastore] path

where
datastore is the datastore name.
path is a slash-delimited path from the root of the datastore.

An example datastore path is "[storage] path/to/file.extension". A listing of all the files, disks and folders on a datastore can be obtained from the datastore browser.

See also ipmiSupported.

host-image-config-manager

This managed object is the interface for configuration of the ESX software image, including properties such as acceptance level.

It is currently designed to be host agent specific.

host-kernel-module-system

The KernelModuleSystem managed object controls the configuration of kernel modules on the host.

host-local-account-manager

This managed object type provides an interface through which local accounts on a host are managed.

Note that this managed object applies only to applications that use a local account database on the host to provide authentication (ESX Server, for example). POSIX and win32 hosts may impose different restrictions on the password, ID, and description formats. POSIX host implementation may restrict the user or group name to be lower case letters and less than 16 characters in total. It may also disallow characters such as ";", "\n", and so on. In short, all the platform dependent rules and restrictions regarding naming of users/groups and password apply here. An InvalidArgument fault is thrown if any of these rules are not obeyed.

host-local-authentication

The HostLocalAuthentication managed object represents local authentication for user accounts on an ESX host.

host-memory-system

The MemoryManagerSystem managed object provides an interface through which the host memory management policies that affect the performance of running virtual machines can be gathered and configured.

host-network-system

This managed object type describes networking host configuration and serves as the top level container for relevant networking data objects.

host-nvdimm-system

Managed object responsible for reading and configuring Non-Volatile DIMMs.

host-patch-manager

This managed object is the interface for scanning and patching an ESX server.

VMware publishes updates through its external website. A patch update is synonymous with a bulletin. An update may contain many individual patch binaries, but its installation and uninstallation are atomic.

host-pci-passthru-system

This managed object manages the PciPassthru state of the host.

host-power-system

Managed object responsible for getting and setting host power management policies.

host-profile

A host profile describes ESX Server configuration.

The HostProfile managed object provides access to profile data and it defines methods to manipulate the profile. A host profile is a combination of subprofiles, each of which contains configuration data for a specific capability. Some examples of host capabilities are authentication, memory, networking, and security. For access to individual subprofiles, see the HostApplyProfile data object (HostProfile.config.applyProfile).

Host profiles are part of the stateless configuration architecture. In the stateless environment, a Profile Engine runs on each ESX host, but an ESX host does not store its own configuration state. Instead, host configuration data is stored on vCenter Servers. Every time a host boots or reboots, it obtains its profile from the vCenter Server.

To create a base host profile use the HostProfileManager.CreateProfile method. To create a profile from an ESX host, specify a HostProfileHostBasedConfigSpec. To create a profile from a file, specify a HostProfileSerializedHostProfileSpec.
To create a subprofile for a particular host capability, use the HostProfileManager.CreateDefaultProfile method. After you create the default profile you can modify it and save it in the base profile.
To update an existing profile, use the HostProfile.UpdateHostProfile method.
To apply a host profile to an ESX host, use the ExecuteHostProfile method to generate configuration changes, then call the HostProfileManager.ApplyHostConfig_Task method to apply them.

Host-Specific Configuration

An individual host or a set of hosts may have some configuration settings that are different from the settings specified in the host profile. For example, the IP configuration for the host's virtual network adapters must be unique.

To verify host-specific data, use the deferredParam parameter to the ExecuteHostProfile method. The Profile Engine will determine if you have specified all of the required parameters for the host configuration. If additional data is required, call the ExecuteHostProfile method again as many times as necessary to verify a complete set of parameters.
To apply host-specific data, use the userInput parameter to the HostProfileManager.ApplyHostConfig_Task method.

The Profile Engine saves host-specific data in an AnswerFile that is stored on the vCenter Server. The HostProfileManager provides several methods to manipulate answer files.

Profile Compliance

You can create associations between hosts and profiles to support compliance checking. When you perform compliance checking, you can determine if a host configuration conforms to a host profile.

To create an association between a host and a profile, use the AssociateProfile method. The method adds the host to the HostProfile.entity[] list.
To retrieve the list of profiles associated with a host, use the HostProfileManager.FindAssociatedProfile method.
To check host compliance, use the CheckProfileCompliance_Task method. If you do not specify any hosts, the method will check the compliance of all hosts that are associated with the profile.

You can also use the Profile Compliance Manager to check compliance by specifying profiles, entities (hosts), or both. See ProfileComplianceManager.CheckCompliance_Task.

Profile Plug-Ins

The vSphere architecture uses VMware profile plug-ins to define profile extensions. For information about using a plug-in to extend a host profile, see the VMware Technical Note Developing a Host Profile Extension Plug-in.

For access to host configuration data that is defined by plug-ins, use the ApplyProfile.policy[] and ApplyProfile.property[] lists. The HostApplyProfile and its subprofiles, which collectively define host configuration data, are derived from the ApplyProfile.

Policies store ESX configuration data in PolicyOption objects.
Profile property lists contain subprofiles defined by plug-ins. Subprofiles can be nested.
- Subprofile lists are available as an extension to the base host profile (HostProfile.config.applyProfile.property[]).
- Subprofile lists are available as extensions to the host subprofiles - for example, the network subprofile (HostApplyProfile.network.property[]).

If you make changes to host profile data, later versions of profile plug-ins may not support the host configuration implied by the changes that you make. When a subsequent vSphere version becomes available, you must verify that the new version supports any previous configuration changes that you have made.

host-profile-manager

The HostProfileManager provides access to a list of HostProfiles and it defines methods to manipulate profiles and AnswerFiles.

host-service-system

The HostServiceSystem managed object describes the configuration of host services.

This managed object operates in conjunction with the HostFirewallSystem managed object.

host-snmp-system

Provision the SNMP Version 1,2c agent.

This object is accessed through the HostConfigManager object.

host-specification-manager

The HostSpecificationManager provides the functionality to update, restrieve and delete HostSpecification and HostSubSpecification.

host-storage-system

This managed object gets and sets configuration information about the host's storage subsystem.

The properties and operations are used to configure the host to make storage available for virtual machines. This object contains properties that are specific to ESX Server and general to both the ESX Server system and the hosted architecture.

host-system

The HostSystem managed object type provides access to a virtualization host platform.

Invoking destroy on a HostSystem of standalone type throws a NotSupported fault. A standalone HostSystem can be destroyed only by invoking destroy on its parent ComputeResource. Invoking destroy on a failover host throws a DisallowedOperationOnFailoverHost fault. See ClusterFailoverHostAdmissionControlPolicy.

host-vflash-manager

The VFlash Manager object is used to configure vFlash resource and vFlash cache on the ESX host.

host-virtual-nic-manager

The VirtualNicManager managed object describes the special Virtual NIC configuration of the host.

host-vmotion-system

Deprecated as of VI API 4.0, use virtualNicManager.

The VMotionSystem managed object describes the VMotion configuration of the host.

host-vsan-internal-system

The VsanInternalSystem exposes low level access to CMMDS, as well as draft versions of VSAN object and disk management APIs that are subject to change in future releases.

No compatibility is guaranteed on any of the APIs, including their prototype, behavior or result encoding.

host-vsan-system

The VsanSystem managed object type exposes VSAN configuration primitives and serves as a host-level access point for relevant VSAN data objects.

host-vstorage-object-manager

Interface to manage virtual storage object on an ESXi host.

http-nfc-lease

Represents a lease on a VirtualMachine or a VirtualApp, which can be used to import or export disks for the entity.

While the lease is held, operations that alter the state of the virtual machines covered by the lease are blocked. Examples of blocked operations are PowerOn, Destroy, Migrate, etc.

A lease is in one of four states:

Initializing: This is the initial state. The lease remains in this state while the corresponding import/export task is preparing the objects. In an import session, this involves creating inventory objects.
Ready: The lease changes to this state once the corresponding import/export task is done preparing the lease. The leased objects are now ready, and the client can use the information provided in the [info](../../sdk/vim25/release/HttpNfcLease/moId/info/get) property to determine where to up/download disks. The client must call [HttpNfcLeaseProgress](../../sdk/vim25/release/HttpNfcLease/moId/HttpNfcLeaseProgress/post) periodically to keep the lease alive and report progress to the corresponding import/export task. Failure to do so causes the lease to time out and enter the error state.
Done: When the client is done transferring disks, it calls [HttpNfcLeaseComplete](../../sdk/vim25/release/HttpNfcLease/moId/HttpNfcLeaseComplete/post) to signal the end of the import/export session. This causes the corresponding import/export task to complete successfully.
Error: If an error occurs during initialization or the lease times out, it will change to this state. The client can also abort the lease manually by calling [HttpNfcLeaseAbort](../../sdk/vim25/release/HttpNfcLease/moId/HttpNfcLeaseAbort/post). In this state, the [error](../../sdk/vim25/release/HttpNfcLease/moId/error/get) property can be read to determine the cause. If the lease belongs to an import session, all objects created during the import are removed when the lease enters this state.

The import/export task corresponding to the lease continues running while the lease is held.

inventory-view

The InventoryView managed object provides a means of browsing the inventory and tracking changes to open folders.

This managed object is particularly useful for UI clients that display a tree-based navigation panel of the inventory.

InventoryView maintains the view list of managed object references to inventory objects. When you create an inventory view (CreateInventoryView), the server initializes the view's object list with a single folder - the root folder.

InventoryView provides methods to open and close folders in the inventory. Use these methods to add and subtract objects from the view list. Use the InventoryView together with the PropertyCollector to manage the data resulting from OpenInventoryViewFolder and CloseInventoryViewFolder methods. By using the PropertyCollector, you have access to the modifications to the view, rather than processing the entire view list.

For example, you might use the following sequence of operations with an InventoryView and the PropertyCollector:

Create an InventoryView.
Create a filter specification for the PropertyCollector.
- Use the InventoryView as the starting object in the ObjectSpec for the filter.
- Use a set of TraversalSpec data objects to identify paths in possible inventory configurations.
- Use the PropertySpec to identify object properties for retrieval.
Use either the CheckForUpdates or WaitForUpdates method to obtain InventoryView modifications. Both methods return an UpdateSet object that describes the changes returned by the PropertyCollector.
Call the OpenInventoryViewFolder or method.

io-filter-manager

Interface to manage IO Filters installed on the ESXi hosts and IO Filter configurations on virtual disks.

IO Filters are customized filters provided by third parties to process I/Os to virtual disks. They can be used to provide data services such as flash caching and replication. This interface is only supported on vCenter server.

ip-pool-manager

Singleton Managed Object used to manage IP Pools.

IP Pools are used to allocate IPv4 and IPv6 addresses to vApps.

iscsi-manager

This managed object provides interfaces for mapping VMkernel NIC to iSCSI Host Bus Adapter.

license-assignment-manager

license-manager

This managed object type controls entitlements for a given VMware platform.

VMware platforms include VirtualCenter, ESX Server, VMware Server, Workstation and Player. Entitlements define what software capabilities this host may use.

Entitlements are identified by a short string 'key'. Keys can represent either a particular edition (Full, Starter) or a particular feature/function (featureKey) (backup, nas). An edition implies zero one or more functions which are express, denied or optional. For example a 'Full' edition includes 'iscsi' function but a Starter edition might disallow it.

Which edition a given VMware platform uses can be defined at any time. Generally this is done right after first install and boot as installation software may not set it. For editions that are similar in nature, any future changes to edition type will only impact future requests for functionality. Current functionality is left unaffected. The same is true for optional functions enabled/disabled after some period of time. For dissimilar editions, such transitions may require entering maintenance mode first else an exception of InvalidState will be thrown.

To specify the edition type and any optional functions, use updateLicense for ESX Server and addLicense follow by LicenseAssingmentManager.updateAssignedLicense for VirtualCenter.

When an edition is specified for a given host, the cost of that edition (how many licenses are needed) is determined. The cost is computed using the license's CostUnit value multiplied by the number of units activated. For example, when a VMware platform is set to an edition which uses a 'cpuPackage' on a two socket server, two licenses would be needed to successfully install that edition.

Here is a diagram of the unit costs supported by this API and their relationships.

   +------------------------------+   +--------+      +-------+
   | +-----------+ +-----------+  |   | Server |      |  Host |
   | |           | |           |  |   +--------+      +-------+
   | |  cpuCore  | |   cpuCore |  |                   +-------+
   | +-----------+ +-----------+  |   +--------+      |  Host |
   |                  cpuPackage  |   |  VM    |      +-------+
   +------------------------------+   +--------+

list-view

The ListView managed object provides access to updates on a specific set of objects.

You can use a ListView with a PropertyCollector method to retrieve data or receive notification of changes. For information about using views with the PropertyCollector, see the description of ViewManager.

When you invoke the CreateListView method, you specify a list of objects. The view list always represents the current configuration of the virtual environment and reflects any subsequent changes that occur.

localization-manager

LocalizationManager provides access to descriptions of the message catalogs that are available for client-side message localization.

Clients of the VIM API may use SessionManager.SetLocale to cause the server to emit localized messages, or may perform client-side localization based on message catalogs provided by the LocalizationManager.

A message catalog is a file that contains a set of key-value pairs.

The key is an ASCII string that identifies the message.
The value is a UTF-8 string that contains the text of the message, sometimes containing substitution variables.

The server will localize fields tagged with 'localizable' based on the value of the UserSession.locale and messageLocale properties which are set via SessionManager.SetLocale.

The following list shows some of the ways that vSphere uses localized messages.

Current task status (TaskInfo.description)
Events (VirtualMachineMessage.text and Questions (VirtualMachineQuestionInfo.text)
Faults (MethodFault.faultMessage)
HostProfile and ClusterProfile descriptions (Profile.ProfileDescription. description returned by the Profile.RetrieveDescription method)

managed-entity

ManagedEntity is an abstract base type for all managed objects present in the inventory tree.

The base type provides common functionality for traversing the tree structure, as well as health monitoring and other basic functions.

Most Virtual Infrastructure managed object types extend this type.

managed-object-view

ManagedObjectView is the base class for view objects that provide access to a set of ManagedEntity objects.

ManagedObjectView defines a view list; the list contains references to objects in the view. To create a view use the ViewManager methods.

network

Represents a network accessible by either hosts or virtual machines.

This can be a physical network or a logical network, such as a VLAN.

Networks are created:

explicitly when configuring a host.
automatically when adding a host to VirtualCenter.
automatically when adding a new virtual machine to a host or to VirtualCenter.

To configure network access for hosts and virtual machines, use DistributedVirtualSwitch and DistributedVirtualPortgroup managed objects.

opaque-network

This interface defines an opaque network, in the sense that the detail and configuration of the network is unknown to vSphere and is managed by a management plane outside of vSphere.

However, the identifier and name of these networks is made available to vSphere so that host and virtual machine virtual ethernet device can connect to them.

option-manager

This managed object type is used for managing key/value pair options.

You can define options on the fly only if the option is supported by the concrete implementation, in a logical tree using a dot notation for keys. For example, "Ethernet.Connection" describes the Connection option as child of the Ethernet option.
Options can be updated even if not visible in supportedOption or settings or the queryMethod returned values only if supported by the concrete implementation.
Attempt to add random Options that are not supported by the concrete implementation may result in unexpected side-effects.
You can use the queryMethod to retrieve a single property or a subset of properties based on the dot notation path.

overhead-memory-manager

Provide static VM overhead memory values for (vm, host) pairs in Virtual Center.

ovf-manager

Service interface to parse and generate OVF descriptors.

The purpose of this interface is to make it easier for callers to import VMs and vApps from OVF packages and to export VI packages to OVF. In the following description, the term "client" is used to mean any caller of the interface.

This interface only converts between OVF and VI types. To actually import and export entities, use ResourcePool.importVApp, VirtualMachine.exportVm and VirtualApp.exportVApp.

Import

For the import scenario, the typical sequence of events is as follows:

The client calls parseDescriptor to obtain information about the OVF descriptor. This typically includes information (such as a list of networks) that must be mapped to VI infrastructure entities.

The OVF descriptor is validated against the OVF Specification, and any errors or warnings are returned as part of the ParseResult. For example, the parser might encounter a section marked required that it does not understand, or the XML descriptor might be malformed.

The client decides on network mappings, datastore, properties etc. It then calls createImportSpec to obtain the parameters needed to call ResourcePool.importVApp.

If any warnings are present, the client will review these and decide whether to proceed or not. If errors are present, the ImportSpec will be missing, so the client is forced to give up or fix the problems and then try again.

The client now calls ResourcePool.importVApp, passing the ImportSpec as a parameter. This will create the virtual machines and VirtualApp objects in VI and return locations to which the files of the entity can be uploaded. It also returns a lease that controls the duration of the lock taken on the newly created inventory objects. When all files have been uploaded, the client must release this lease.

Export

Creating the OVF descriptor is the last part of exporting an entity to OVF. At this point, the client has already downloaded all files for the entity, optionally compressing and/or chunking them (however, the client may do a "dry run" of creating the descriptor before downloading the files. See OvfManager.createDescriptor).

In addition to the entity reference itself, information about the choices made on these files is passed to createDescriptor as a list of OvfFile instances.

The client must inspect and act upon warnings and errors as previously described.

No matter if the export succeeds or fails, the client is responsible for releasing the shared state lock taken on the entity (by VirtualMaching.exportVm or VirtualApp.exportVApp) during the export.

Error handling

All result types contain warning and error lists. Warnings do not cause processing to fail, but the caller (typically, the user of a GUI client) may choose to reject the result based on the warnings issued.

Errors cause processing to abort by definition.

performance-manager

This managed object type provides the service interface for obtaining statistical data about various aspects of system performance, as generated and maintained by the system's performance providers.

A "performance provider" (PerfProviderSummary) is any managed object that generates utilization or other performance metrics. Performance providers include managed entities, such as hosts, virtual machines, compute resources, resource pools, datastores, and networks. Performance providers also include physical or virtual devices associated with these objects, such as virtual host-bus adapters and network-interface controllers (NICs)

Performance Counters
Each performance provider—the instrumented device or entity—has its own set of counters that provides metadata about its available metrics. Each counter has a unique key, referred to as the counterId. The actual performance metrics generated at runtime are identified by this counterId. Counters are organized by groups of finite system resources, such as memory, CPU, disk, and so on. The links in this list contain documentation for performance counters, by group. Each page contains a table that includes data extracted from instances of the PerfCounterInfo data object, including the counter name, its Label, Unit, StatsType, RollupType, and Level:

Cluster Services

CPU
Host-Based Replication
Management Agent
Memory
Network
Power
Resource Scheduler
Storage Capacity:
- Datastore / Virtual Machine
Storage I/O:
System
vCenter Resource
Virtual Machine Operations

Other performance-counter groups, in addition to those listed here, exist on the system. However, only the counter groups listed are considered of possible interest to third-party developers.

Obtaining Metadata and Metrics
This interface provides these query operations:

QueryPerfProviderSummary, for obtaining metatdata about performance providers
QueryPerfCounter and QueryPerfCounterByLevel for obtaining metadata about supported counters.
QueryPerf, QueryAvailablePerfMetric, and QueryPerfComposite for obtaining statistics for one or more entities:
- Use QueryPerf to obtain metrics for multiple entities in a single call.
- Use QueryPerfComposite to obtain statistics for a single entity with its descendent objects—statistics for a host and all its virtual machines, for example.

Product and Version Specifics
Some differences between ESX and vCenter Server implementations of this interface include:

For ESX systems, this interface provides access to real-time data, and to real-time data that has been rolled up into "PastDay" statistics (if applicable for the specific counter).
For vCenter Server systems, this interface provides access to real-time and historical data. vCenter Server collects statistics on a regular basis from all ESX systems that it manages, and aggregates the results based on the level settings for the server.
Default sampling interval is product- and version-specific:
- ESX 3.x (and subsequent) systems: 20 second interval
- ESX 2.x systems: 60 second interval
VirtualCenter Server 2.5 (and subsequent vCenter Server) systems initially collect statistics data 10 minutes after system startup, and then hourly thereafter.

See the Programming Guide for more information about using PerformanceManager.

profile

The Profile managed object is the base class for host and cluster profiles.

profile-compliance-manager

Interface handling the Compliance aspects of entities.

profile-manager

This class is responsible for managing Profiles.

property-collector

The PropertyCollector managed object retrieves and detects changes to the properties of other managed objects.

The RetrievePropertiesEx method provides one-time property retrieval. The WaitForUpdatesEx method provides incremental change detection and supports both polling and notification.

For change detection a client creates one or more filters to specify the subset of managed objects in which the client is interested. Filters keep per-session state to track incremental changes. Because this state is per-session:

A session cannot share its PropertyCollector filters with other sessions
two different clients can share the same session, and so can share the same filters, but this is not recommended
When a session terminates, the associated PropertyCollector filters are automatically destroyed.

property-filter

The PropertyFilter managed object type defines a filter that controls the properties for which a PropertyCollector detects incremental changes.

Filters are subordinate objects; they are part of the PropertyCollector and do not have independent lifetimes. A Filter is automatically destroyed when the session on which it was created is closed or the PropertyCollector on which it was created is destroyed.

resource-planning-manager

resource-pool

Represents a set of physical resources: a single host, a subset of a host's resources, or resources spanning multiple hosts.

Resource pools can be subdivided by creating child resource pools. In order to run, a virtual machine must be associated as a child of a resource pool.

In a parent/child hierarchy of resource pools and virtual machines, the single resource pool that has no parent pool is known as the root resource pool.

Configuration

A resource pool is configured with a set of CPU (in MHz) and memory (in MB) resources. These resources are specified in absolute terms with a resource reservation and a resource limit, along with a shares setting. The shares are used during resource contention, to ensure graceful degradation.

For the root resource pool, the values of the reservation and the limit are set by the system and are not configurable. The reservation and limit are set to the same value, indicating the total amount of resources the system has available to run virtual machines. This is computed as the aggregated CPU and memory resources provided by the set of current available hosts in the parent compute resource minus the overhead of the virtualization layer.

Since the resource pool configuration is absolute (in MHz or MB), the configuration can become invalid when resources are removed. This can happen if a host is removed from the cluster, if a host becomes unavailable, or if a host is placed in maintenance mode. When this happens, the system flags misconfigured resource pools and displays the reservations and limits that are in effect. Further, in a DRS enabled cluster, the tree can be misconfigured if the user bypasses VirtualCenter and powers on VMs directly on the host.

A General Discussion of Resource pool states and admission control There are three states that the resource pool tree can be in: undercommited (green), overcommited (yellow), and inconsistent (red). Depending on the state, different resource pool configuration policies are enforced. The states are described in more detail below:

GREEN (aka undercommitted): We have a tree that is in a good state. Every node has a reservation greater than the sum of the reservations for its children. We have enough capacity at the root to satisfy all the resources reserved by the children. All operations performed on the tree, such as powering on virtual machines, creating new resource pools, or reconfiguring resource settings, will ensure that the above constraints are maintained.
RED (aka. inconsistent): One or more nodes in the tree has children whose reservations are greater than the node is configured to support. For example, i) a resource pool with a fixed reservation has a running virtual machine with a reservation that is higher than the reservation on resource pool itself., or ii) the child reservations are greater than the limit.

In this state, the DRS algorithm is disabled until the resource pool tree's configuration has been brought back into a consistent state. We also restrict the resources that such invalid nodes request from their parents to the configured reservation/limit, in an attempt to isolate the problem to a small subtree. For the rest of the tree, we determine whether the cluster is undercommitted or overcommitted according to the existing rules and perform admission control accordingly.

Note that since all changes to the resource settings are validated on the VirtualCenter server, the system cannot be brought into this state by simply manipulating a cluster resource pool tree through VirtualCenter. It can only happen if a virtual machine gets powered on directly on a host that is part of a DRS cluster.
YELLOW (aka overcommitted): In this state, the tree is consistent internally, but the root resource pool does not have the capacity at to meet the reservation of its children. We can only go from GREEN -> YELLOW if we lose resources at the root. For example, hosts becomes unavailable or is put into maintenance mode. Note that we will always have enough capacity at the root to run all currently powered on VMs. However, we may not be able to satisfy all resource pool reservations in the tree. In this state, the reservation configured for a resource pool is no longer guaranteed, but the limits are still enforced. This provides additional flexibility for bringing the tree back into a consistent state, without risking bringing the tree into a RED state. In more detail:
- Resource Pool The root is considered to have unlimited capacity. You can reserve resources without any check except the requirement that the tree remains consistent. This means that nodes whose parents are all configured with expandable reservations and no limit will have unlimited available resources. However, if there is an ancestor with a fixed reservation or an expandable reservation with a limit somewhere, then the node will be limited by the reservation/limit of the ancestor.
- Virtual Machine Virtual machines are limited by ancestors with a fixed reservation and the capacity at the root.

Destroying a ResourcePool

When a ResourcePool is destroyed, all the virtual machines are reassigned to its parent pool. The root resource pool cannot be destroyed, and invoking destroy on it will throw an InvalidType fault.

Any vApps in the ResourcePool will be moved to the ResourcePool's parent before the pool is destroyed.

The Resource.DeletePool privilege must be held on the pool as well as the parent of the resource pool. Also, the Resource.AssignVMToPool privilege must be held on the resource pool's parent pool and any virtual machines that are reassigned.

scheduled-task

The scheduled task object.

scheduled-task-manager

Object manager for scheduled tasks.

search-index

The SearchIndex service allows a client to efficiently query the inventory for a specific managed entity by attributes such as UUID, IP address, DNS name, or datastore path.

Such searches typically return a VirtualMachine or a HostSystem. While searching, only objects for which the user has sufficient privileges are considered. The findByInventoryPath and findChild operations only search on entities for which the user has view privileges; all other SearchIndex find operations only search virtual machines and hosts for which the user has read privileges. If the user does not have sufficient privileges for an object that matches the search criteria, that object is not returned.

service-instance

The ServiceInstance managed object is the singleton root object of the inventory on both vCenter servers and servers running on standalone host agents.

The server creates the ServiceInstance automatically, and also automatically creates the various manager entities that provide services in the virtual environment. Some examples of manager entities are LicenseManager, PerformanceManager, and ViewManager. You can access the manager entities through the content property.

A vSphere API client application begins by connecting to a server and obtaining a reference to the ServiceInstance. The client can then use the RetrieveServiceContent method to gain access to the various vSphere manager entities and to the root folder of the inventory.

When you create managed objects, the server adds them to the inventory. The inventory of managed objects includes instances the following object types:

ServiceInstance -- Root of the inventory; created by vSphere.
Datacenter -- A container that represents a virtual data center. It contains hosts, network entities, virtual machines and virtual applications, and datastores.
Folder -- A container used for hierarchical organization of the inventory.
VirtualMachine -- A virtual machine.
VirtualApp -- A virtual application.
ComputeResource -- A compute resource (either a cluster or a stand-alone host).
ResourcePool -- A subset of resources provided by a ComputeResource.
HostSystem -- A single host (ESX Server or VMware Server).
Network -- A network available to either hosts or virtual machines.
DistributedVirtualSwitch -- A distributed virtual switch.
DistributedVirtualPortgroup -- A distributed virtual port group.
Datastore -- Platform-independent, host-independent storage for virtual machine files.

The following figure shows the organization of managed objects in the vCenter hierarchy:

Every Datacenter has the following set of dedicated folders. These folders are empty until you create entities for the Datacenter.

A folder for any combination of VirtualMachine and/or VirtualApp objects. VirtualApp objects can be nested, but only the parent VirtualApp can be visible in the folder. Virtual machines that are children of virtual applications are not associated with a VirtualMachine/VirtualApp folder.
A folder for a ComputeResource hierarchy.
A folder for network entities - any combination of Network, DistributedVirtualSwitch, and/or DistributedVirtualPortgroup objects.
A folder for Datastore objects.

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

service-manager

The ServiceManager managed object is a singleton object that is used to present services that are optional and not necessarily formally defined.

This directory makes available a list of such services and provides an easy way to locate them. The service being represented can take arbitrary form here and is thus represented by a generic ManagedObject. The expectation is that the client side is knowledgeable of the instance type of the specific service it is interested in using.

session-manager

This managed object type includes methods for logging on and logging off clients, determining which clients are currently logged on, and forcing clients to log off.

simple-command

A managed object that wraps the execution of a single arbitrary command.

The specific command executed is assumed to be known from the service name by the client invoking this command. This object presents a generic interface for such services.

site-info-manager

This managed object type is used for managing external site-related capabilities which are advertised by vCenter.

storage-pod

The StoragePod data object aggregates the storage resources of associated Datastore objects into a single storage resource for use by virtual machines.

The storage services such as Storage DRS (Distributed Resource Scheduling), enhance the utility of the storage pod.

Use the Folder.CreateStoragePod method to create an instance of this object.

storage-query-manager

This managed object is used to query vCenter Server's storage system entities.

storage-resource-manager

This managed object type provides a way to configure resource usage for storage resources.

task

A task is used to monitor and potentially cancel long running operations.

task-history-collector

TaskHistoryCollector provides a mechanism for retrieving historical data and updates when the server appends new tasks.

task-manager

The TaskManager managed object provides an interface for creating and managing Task managed objects.

Many operations are non-blocking, returning a Task managed object that can be monitored by a client application. Task managed objects may also be accessed through the TaskManager.

tenant-tenant-manager

A singleton managed object for managing vCenter tenants.

user-directory

The UserDirectory managed object provides information about users and groups on a vSphere server and ESX hosts.

The method RetrieveUserGroups returns a list of user account data. The method can perform a search operation based on specific criteria - user name, group name, sub-string or string matching, and, on Windows, domain. Use the results as input to the AuthorizationManager methods SetEntityPermissions and ResetEntityPermissions.

The content of the returned results depends on the server environment:

On a Windows host, RetrieveUserGroups can search from the set of trusted domains on the host, including the primary domain of the system. A special domain (specified as an empty string - "") refers to the users and groups local to the host.
On an ESX Server or a Linux host, the search operates on the users and groups defined in the /etc/passwd file. Always specify an empty string ("") for the domain argument. If the /etc/passwd file contains Sun NIS or NIS+ users and groups, RetrieveUserGroups returns information about these accounts as well.

vcenter-vstorage-object-manager

Interface to manage virtual storage object on a vCenter.

VStorageObjectManager and SPBM policy support: All of the VStorageObjectManager APIs requiring ESXi host uses "Programatically selected" host to perform the actual operation. If the selected host is of 6.5 version then policy would not be passed down to host. In that case, user operation would succeed but if user checks SPBM Entity Compliance, it will show "Mismatch" / "Non Compliant" as a compliance result.

view

View is the base class for session-specific view objects.

A view is a mechanism that supports selection of objects on the server and subsequently, access to those objects. To create a view, use the ViewManager methods. A view exists until you terminate it by calling the DestroyView method, or until the end of the session. Access to a view is limited to the session in which it is created.

There are three types of views:

A view maintains a view list that contains managed object references. You can use a view with the PropertyCollector to retrieve data and obtain notification of changes to the virtual environment. For information about using views with the PropertyCollector, see the description of ViewManager.

view-manager

The ViewManager managed object provides methods to create ContainerView, InventoryView, and ListView managed objects.

The ViewManager also maintains a list of managed object references to the views that you have created. Use the viewList property to access the views.

A View is a mechanism that supports selection of objects on the server and subsequently, access to those objects. Views can simplify the task of retrieving data from the server. When you use a view, you can use a single invocation of a PropertyCollector method to retrieve data or receive notification of changes instead of multiple invocations involving multiple filter specifications. A view exists until you destroy it or until the end of the session.

The ViewManager supports the following views:

A ContainerView is based on Folder, Datacenter, ComputeResource, ResourcePool, or HostSystem managed objects. Use a container view to monitor the container contents and optionally, its descendants.
A ListView managed object is based on an arbitrary but specific set of objects. When you create a list view, you provide a list of objects to populate the view (CreateListView), or you provide an existing view from which the new view is created (CreateListViewFromView).
An InventoryView managed object is based on the entire inventory. Use an inventory view as a general mechanism to monitor the inventory or portions of the inventory.

For example, you might use the following sequence of operations to get the names of all the virtual machines on a server:

Create a ContainerView for the root folder in the server inventory. For the ContainerView, use the type property to include only virtual machines.
Create a filter specification for the PropertyCollector.
- Use the ContainerView as the starting object in the ObjectSpec for the filter.
- Use the TraversalSpec to select all objects in the view list (all the virtual machines).
- Use the PropertySpec to retrieve the name property from each virtual machine.
Invoke the PropertyCollector RetrieveProperties method.

virtual-app

Represents a multi-tiered software solution.

A vApp is a collection of virtual machines (and potentially other vApp containers) that are operated and monitored as a unit. From a manage perspective, a multi-tiered vApp acts a lot like a virtual machine object. It has power operations, networks, datastores, and its resource usage can be configured.

From a technical perspective, a vApp container is a specialized resource pool that has been extended with the following capabilities:

Product information such as product name, vendor, properties, and licenses.
A power-on/power-off sequence specification
Support for import/export vApps as OVF packages
An OVF environment that allows for application-level customization

Destroying a vApp

When a vApp is destroyed, all of its virtual machines are destroyed, as well as any child vApps.

The VApp.Delete privilege must be held on the vApp as well as the parent folder of the vApp. Also, the VApp.Delete privilege must be held on any child vApps that would be destroyed by the operation.

virtual-disk-manager

Most VirtualDiskManager APIs will be DEPRECATED as of vSphere 6.5. Please use VStorageObjectManager APIs to manage Virtual disks.

This managed object type provides a way to manage and manipulate virtual disks on datastores. The source and the destination names are in the form of a URL or a datastore path.

A URL has the form

scheme://authority/folder/path?dcPath=dcPath&dsName=dsName

where

scheme is http or https.
authority specifies the hostname or IP address of the VirtualCenter or ESX server and optionally the port.
dcPath is the inventory path to the Datacenter containing the Datastore.
dsName is the name of the Datastore.
path is a slash-delimited path from the root of the datastore.

A datastore path has the form

[datastore] path

where

datastore is the datastore name.
path is a slash-delimited path from the root of the datastore.

An example datastore path is "[storage] path/to/file.extension". A listing of all the files, disks and folders on a datastore can be obtained from the datastore browser.

Transcoder API

Overview

Introduced in vCenter 8.0 U2, the Transcoder API allows users to convert data objects from their XML representation to JSON and vice versa.

Through the Virtual Infrastructure JSON API users are enabled to access vCenter APIs via a JSON-based wire protocol, an alternative to the SOAP/XML. The incentive behind the creation of the Transcoder API is to aid developers migrating their vCenter automations from SOAP/XML to VI/JSON.

Additionally, the Transcoder API enables developers to intertwine different SDKs (SOAP and JSON based) in a single automation by transcoding data objects from one runtime to another.

Usage

The Transcoder API is comprised of a single endpoint - /sdk/{namespace}/{release}/transcoder, moreover, a single operation, and is part of the VI/JSON APIs - available under the common path /sdk/{namespace}/{release}. Additional to the path parameters namespace and release, operation specific parameters are:

A valid VI data object to be transcoded, serialized in XML or JSON format, present in the HTTP body.
The format the data object is transcoder from, denoted by the Content-type header.
The format the data object is transcoded to, denoted by the Accept header.
An optional query parameter target_release used to downgrade the data object to a previous release according to the rules for backward compatibility.

transcode is available only through valid authentication. Authenticated access is granted through the vmware-api-session-id header. For more details on vmware-api-session-id see the VI/JSON landing page.

Exclusively for the transcoder service, a valid vmware_soap_session cookie header also provides authenticated access. This particular authentication variant allows existing SOAP clients to consume the transcoder easily.

The vmware_soap_session cookie header:

cookie: vmware_soap_session="{soap-session-id}"

is obtainable through the SOAP based vim.SessionManager#Login.

As an example, an HTTP request for transcoding a minimalistic, XML-serialized vim.vm.ConfigSpec looks like:

POST /sdk/vim25/8.0.3.0/transcoder HTTP/1.1
Host: {vcenter-address}
Accept: application/json
Content-type: application/xml
vmware-api-session-id: {session-id}
Content-Length: 396

&lt;obj versionId="2.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns="urn:vim25" xsi:type="VirtualMachineConfigSpec"&gt;
   &lt;name&gt;sample-vm&lt;/name&gt;
   &lt;guestId&gt;guest&lt;/guestId&gt;
   &lt;annotation&gt;Sample&lt;/annotation&gt;
   &lt;files&gt;
      &lt;vmPathName&gt;[datastore1]&lt;/vmPathName&gt;
   &lt;/files&gt;
   &lt;numCPUs&gt;1&lt;/numCPUs&gt;
   &lt;memoryMB&gt;4&lt;/memoryMB&gt;
&lt;/obj&gt;

The conversion is from Content-type: application/xml to Accept: application/json, hence, the response is a JSON serialized VirtualMachineConfigSpec:

{
    "_typeName": "VirtualMachineConfigSpec",
    "name": "sample-vm",
    "guestId": "guest",
    "annotation": "Sample",
    "files": {
        "_typeName": "VirtualMachineFileInfo",
        "vmPathName": "[datastore1]"
    },
    "numCPUs": 1,
    "memoryMB": 4
}