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.

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 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 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.