Filtering Views Selectively Using Properties

Each Perl view object has properties that correspond to properties of server-side managed objects as follows:

■	For each simple property (string, Boolean, numeric data type), including inherited simple properties, the SDK creates an accessor method. The accessor method name is the same as the property name.

■	Arrays of properties become arrays of properties of the same name.

Because many of the server-side managed objects have a large number of properties, accessing only a small number of objects can potentially result in noticeable performance degradation. You use a properties filter to populate the view object only with properties you are interested in to avoid that problem.

Using View Subroutines with a Properties Argument

The view subroutines—get_view(), get_views(), find_entity_view(), and find_entity_views() —can accept a properties argument that consists of a list of property paths for retrieval from the server. Go to the vSphere Web Services SDK Reference for a list of properties for each server-side managed object. Property paths can be full paths, and can include nested properties. Properties do not have to be top-level managed object properties.

The following example illustrates filtering by property.

1	Populate a virtual machine view with power-state information only, as follows:

my $vm_view = Vim::find_entity_view(

view_type => 'VirtualMachine',

filter => { 'name' => 'foo' },

properties => [ 'runtime.powerState' ]

);

2	Use the view object’s get_property() method. Note that $vm_view is an array reference, not a scalar.

my $state = $vm_view->get_property('runtime.powerState');

3	If you are interested in subproperties of the retrieved properties, you can retrieve them like this:

my $vm_view = Vim::find_entity_view(

view_type => 'VirtualMachine',

filter => { 'name' => 'foo' },

properties => [ 'config.hardware' ]);

my $memsize = $vm_view->get_property('config.hardware.memoryMB');

get_property() works with fully-populated views as well. The following code fragments uses get_property to retrieve a property from a virtual machine.

my $vm_view = Vim::find_entity_view(

view_type => 'VirtualMachine',

filter => { 'name' => 'foo' });

my $memsize = $vm_view->get_property('config.hardware.memoryMB');

The following code fragment, which retrieves the same property by traversing the tree, has the same result.

my $vm_view = Vim::find_entity_view(

view_type => 'VirtualMachine',

filter => { 'name' => 'foo' });

my $memsize = $vm_view->config->hardware->memoryMB;

When you use a filtered view and attempt to read a property that was not retrieved from the server, the result is the same as if the property were unset.

Using Filters on the Utility Application Command Line

When you run a utility application that takes arguments specifying names for virtual machines, host systems, and so on, you must supply the exact name on the command line. Regular expressions are not accepted.

When you run a utility application, there are some restrictions on special characters:

■	In virtual machine names, you must represent the character forward slash (/) as %2f, backward slash (\) as %5c, and percent (%) as %25 when they appear in virtual machine names.

■	On UNIX-like command lines, surround names that contain special characters with single-quotes, and use percent (%) as the escape character.

For example, to search for the virtual machine San Jose, run this command:

perl vminfo.pl --username Administrator --password 'secret' --server myserver --vmname 'San Jose'

To search for the virtual machine San-Jose/5, run this command:

perl vminfo.pl --username Administrator --password 'secret' --server myserver --vmname 'San-Jose%2f5'