Access to vSphere Server Data

To obtain information about the virtual infrastructure, you retrieve managed object properties. Managed object properties can be simple data types, such as integer or string data, or they can be complex types such as data objects that contain sets of properties.

Obtaining Information from a Server

With a reference to a managed object, you can obtain information about the state of the server-side inventory objects and populate client-side data objects based on the values. You can use one of the following approaches:

■	Use an accessor (getter) method. The client proxy interface provides accessor methods for each data object property. You can use these accessor methods to obtain the values of the object. See Language-Specific Classes and Methods for information about client proxy interface accessor methods.

■	Use a PropertyCollector to navigate to a selected point on the server and obtain values from specific properties. See Property Collector for more information about PropertyCollector.

■

Use the SearchIndex managed object to obtain a managed object reference to the managed entity of interest. The SearchIndex can return managed object references to specific managed entities—ComputeResource, Datacenter, Folder, HostSystem, ResourcePool, VirtualMachine—given an inventory path, IP address, or DNS name.

Important You can use API methods to operate on managed objects in the vSphere inventory. A method that updates properties in one managed object may also update properties in other managed objects. The Server performs asynchronous updates to the inventory. There is no guarantee that the inventory will be completely updated when the method returns to the caller. Use the PropertyCollector method WaitForUpdatesEx to obtain property changes.

Working with Data Structures

Properties contain information about the server-side objects at a given point in time. The value of a property can be of one of the following types:

■	Simple data types, such as a string, boolean, or integer (or other numeric) data type. For example, the ManagedEntity managed object has a name property that takes a string value.

■

Arrays of simple data types or data objects. For example, a HostSystem managed object contains an array of managed object references (a type of data object) to virtual machines hosted by that physical machine. As another example, the SessionManager managed object has a sessionList property that is an array of UserSession data objects.

■	Enumerated types (enumeration, enum) of predefined values. The values can be a collection of simple data types or data objects. For example, a virtual machine's power state can be one of three possible string values—poweredOn, poweredOff, or suspended.

The type of a property is often a string, but the property actually expects one of the values an enumeration encapsulates. For example, when you set VirtualMachineConfigSpec.guestid you can specify one of the elements of the VirtualMachineGuestOSIdentifier as a string.

■	Complex (or composite) data types. For example, the HostProfileConfigInfo object contains data objects, an array of data objects, and an array of strings.

Accessing Property Values

To use the composite data structures and arrays that contain Server data:

■	Use dot notation to access nested properties in composite data structures.

■	Cast unconstrained property values (xsd:anyType) to array types.

■	Use keys or index values as appropriate to access array values.

Nested Properties and Property Paths in Composite Data Structures

vSphere Data objects can include properties that are defined as composite data types, such as data objects. The embedded data objects can also contain properties that are data objects. Properties can nest to several levels.

For example, the following figure shows a UML class diagram of the VirtualMachine managed object, which has a runtime property that is defined as an xsd:dateTime data type. VirtualMachine also has a summary property that is a VirtualMachineSummary data object. The VirtualMachineSummary data object contains a config property that is a VirtualMachineConfigSummary data object.

VirtualMachine Managed Object and Nested Properties

To refer to a nested property, use dot notation to separate the object names in the sequence that defines the path to the property. Your code must handle the type referenced at the end of the sequence.

For example, you can compare the property referenced by the path summary.config.guestId (a string value) to the property referenced in the path summary.config (the complete VirtualMachineSummary data object).

Nested Properties and Data Types shows examples of property references and the corresponding data types for some of the properties of the VirtualMachine managed object shown in VirtualMachine Managed Object and Nested Properties.

Nested Properties and Data Types 

Reference	Data Type
summary	VirtualMachineSummary data object
summary.config	VirtualMachineConfigSummary data object
summary.config.guestID	string

xsd:anyType Arrays

The vSphere API uses xsd:anyType unconstrained type declarations. A vSphere client must map values of xsd:anyType to explicit data types. An xsd:anyType value can represent a single data value or it can represent an array. The WSDL for the vSphere API defines array types for all of the data values that a vSphere client can send or receive as arrays. The array types use the prefix “Array Of”. An example of an array type is ArrayOfString for string values.

When a client sends data to a vSphere Server, the client must use explicit datatypes. For example, a client can define a MethodAction for a ScheduledTask. The vSphere API defines arguments to the action (the MethodActionArgument.value property) as type xsd:anyType. If the action takes an array argument, the client must set the corresponding MethodAction.argument[].value to the appropriate ArrayOf... type.

When a client receives xsd:anyType data from a vSphere Server, it must cast the data to an explicit type. For example, the PropertyCollector method RetrievePropertiesEx returns a set of ObjectContent data objects. The ObjectContent.propSet property is a list of DynamicProperty objects that contains the requested property values. Each DynamicProperty object contains a name-value pair. The value property (DynamicProperty.val) is of type xsd:anyType. It can represent a single object or an array of objects.

When the returned value is a single object such as an Event, ManagedObjectReference, or String, you can cast it directly to a variable of the appropriate type. However, when the value is an array of objects you cannot cast the anyType value directly to an array variable.

When the PropertyCollector returns array data, it sends it as an xsd:anyType value. The language-specific bindings contain definitions for array objects such as ArrayOfEvent, ArrayOfManagedObjectReference, and ArrayOfString, and corresponding “get” methods. To extract the actual array from a property of type xsd:anyType, cast DynamicProperty.val to the appropriate array type and use the matching get method – for example, getEvent(), getManagedObjectReference(), or getString().The following sections provide examples of how to cast returned values for a few of the array types. The code uses the JAX-WS-generated Java bindings for the VMware vSphere Web Services SDK WSDL. Each of the code fragments uses this logic:

■	Use the DynamicProperty.getVal() method to retrieve the anyType property value.

■	Specify the appropriate array type to cast the anyType value.

■	Use the corresponding get method to assign the result of the cast operation to a list variable.

Event Array Example

/*

* Handling arrays of Event objects.

* Cast the return value to ArrayOfEvent and use getEvent().

*/

List[] eventList = ((ArrayOfEvent) dynamicProp.getVal()).getEvent();

ManagedObjectReference Array Example

/*

* Handling arrays of ManagedObjectReference objects.

* Cast the return value to ArrayOfManagedObjectReference and use getManagedObjectReference().

*/

List[] morList =

((ArrayOfManagedObjectReference)dynamicProp.getVal()).getManagedObjectReference();

String Array Example

/*

* Handling arrays of strings.

* Cast the return value to ArrayOfString and use getString().

*/

List[] stringList = ((ArrayOfString) dynamicProp.getVal()).getString();

Indexed Array and Key-Based Array Properties

The VMware vSphere data structures include array properties, which can be indexed arrays or key-based arrays.

■

Indexed arrays are accessed by using an index integer. Indexed arrays are used for arrays of data types whose positions in the array do not change. For example, the roleList property of the AuthorizationManager managed object is an array of authorization roles. Adding a new role to the array does not change the position of existing elements in the array.

■

Key-based arrays are used for information whose position is subject to change. A key-based array (same basic concept as a Perl hash or a Python dictionary) uses a unique, unchanging value as a key to access an element’s value. Typically, the key is a string, but integers can also be used. For example, Event arrays use integers as keys. Nested properties can also refer to entries in a key-based array. For example, a.b.c["xyz"] refers to the property c that has the key value of xyz.

The vSphere management object model uses key-based arrays to track managed object references. The contents of a key-based array property are accessed by the value of either the key property or, in the case of a managed object reference, its value property. The value of these fields is unique across all of the components of an array.

Unset Optional Properties

Many of the Data Objects in the vSphere Web Services SDK have optional properties that may be set by your client application or by a Server process or event. If you retrieve a data object that has a optional property that is unset, the Server will not return a value for the optional property. If you call an accessor function to retrieve the property value, the value returned by the function depends on the programming language that you are using.

For example, if you are programming in Java or C#, the value you will receive for an unset property is “null”.

Data Object - HostFirewallInfo Properties shows part of the Properties table for the HostFirewallInfo Data Object in the vSphere Web Services SDK API Reference. When you look at properties in the vSphere Web Services SDK API Reference, you can see that optional properties are marked with a red asterisk.

In this example, that the defaultPolicy property is always returned, but the ruleset property will be returned as a null value if it has not been set.

Data Object - HostFirewallInfo Properties

Since Data Objects are part of many different constructs, there is no standard scenario for when an optional property should be set, what will happen if an optional property is left unset, or what you should do if a null value is returned.

Escape Character in Name and Path Properties

The percent sign (%) is used as an escape character to embed special characters in strings. For example, %2f (or %2F) is interpreted as the slash (/) character. To include a percent sign as a literal in a string, use %%.The path to the inventory starts from the root folder (ServiceContent.rootFolder property), denoted by the slash character.

Special Characters 

Character	Description	Representation in URL
%	Percent sign	%25
/	Slash	%2F, %2f
\	Backslash	%5C, %5c
-	Dash	%2D, %2d
.	Dot	%2E, %2e
“	Double quotation mark	%2B, %2b