Creating and Using Filters

You can use the vSphere SDK for Perl to define and use filters that select objects based on property values. Filters can reduce a large result set to only those objects with characteristics of interest to you.

Using Filters with Vim::find_entity_view() or Vim::find_entity_views()

You can call Vim::find_entity_view() or Vim::find_entity_views() to retrieve objects from the ESX/ESXi host. Vim::find_entity_view() returns the first object it finds that matches the search criteria. Vim::find_entity_views() returns all objects.

When you call Vim::find_entity_view() the first object found might not be the one you are looking for. For example, you might want to retrieve only those virtual machine objects whose names begin with a certain prefix. When you call Vim::find_entity_views(), the command might return more objects than you want to work with, for example all virtual machines in a datacenter. You can apply one or more filters to Vim::find_entity_view() and Vim::find_entity_views() to select a subset of objects based on property values.

To apply a filter to the results of Vim::find_entity_view() or Vim::find_entity_views(), you supply an optional filter parameter. The value of the parameter is an anonymous hash reference containing one or more pairs of filter criteria. Each of the criteria is a property path and a match value. The match value can be either a string or a regular expression object. If the match value is a string, the value of the property must match the string exactly (including case). To match Boolean values, use the strings true and false.

The following filter parameter matches a virtual machine power state of poweredOff:

filter => { 'runtime.powerState' => 'poweredOff' }

You can also match using a regular expression object, generally known as a qr// (quoted regular expression) object. In this case, the value of the property must match the regular expression.

The following filter matches objects whose names begin with Test:

filter => { 'name' => qr/^Test/ }

filter => { 'name' => qr/^test/i } # make the match case-insensitive with the i option

For more information about the qr// operator, see the perlre (perl regular expressions) and perlop man pages in the standard Perl documentation.

The following example illustrates how you might use Vim::find_entity_views() in combination with a filter. It prints a list of virtual machine objects whose guest operating system names contain the string Windows.

Example: Filter that Creates Views of Windows-Based Virtual Machines Only

. . .

my $vm_views = Vim::find_entity_views(

view_type => 'VirtualMachine',

filter => {

# True if string 'Windows' appears anywhere in guestFullName

'config.guestFullName' => qr/Windows/

}

);

# Print VM names

foreach my $vm (@$vm_views) {

print "Name: " . $vm->name . "\n";

}

. . .

 

If you pass multiple filter criteria to Vim::find_entity_view() or Vim::find_entity_views(), the method returns only the managed objects for which all criteria match. The filter parameter specified in Example: Example of Multiple Filter Specification includes two criteria. The example returns only virtual machines that fulfill both requirements:

■	Guest operating system is Windows — the config property’s guestFullName property includes the string Windows.

■	Virtual machine is running. The power state is poweredOn.

Example: Example of Multiple Filter Specification

. . .

my $vm_views = Vim::find_entity_views(

view_type => 'VirtualMachine',

filter => {

'config.guestFullName' => qr/Windows/,

'runtime.powerState' => 'poweredOn'

}

);

# Print VM names

foreach my $vm (@$vm_views) {

print "Name: " . $vm->name . "\n";

}

. . .

 

Important You can match only properties that have simple types like strings and numbers. Specifying a property with a complex type as an argument to a filter results in a fatal runtime error. For example, you cannot specify the runtime property of a VirtualMachine object, which is a complex object, not a string.