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.

. . .
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";
}
. . .

. . .
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";
}
. . .