Managed Object - SearchIndex(vim.SearchIndex)

Property of: ServiceContent
See also: Datacenter, ManagedEntity, VirtualMachine
Since: 2.0

Managed Object Description

The SearchIndex service allows a client to efficiently query the inventory for a specific managed entity by attributes such as UUID, IP address, DNS name, or datastore path. Such searches typically return a VirtualMachine or a HostSystem. While searching, only objects for which the user has sufficient privileges are considered. The findByInventoryPath and findChild operations only search on entities for which the user has view privileges; all other SearchIndex find operations only search virtual machines and hosts for which the user has read privileges. If the user does not have sufficient privileges for an object that matches the search criteria, that object is not returned.

Properties

Name	Type	Description
None

Methods

Methods defined in this Managed Object
FindAllByDnsName, FindAllByIp, FindAllByUuid, FindByDatastorePath, FindByDnsName, FindByInventoryPath, FindByIp, FindByUuid, FindChild

FindAllByDnsName(findAllByDnsName)

Finds all virtual machines or hosts by DNS name. The DNS name for a virtual machine is the one returned from VMware tools, hostName.

Required Privileges: System.View
Since: vSphere API 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the SearchIndex used to make the method call.
datacenter* P	ManagedObjectReference to a Datacenter	If specified, restricts the query to entities in a particular datacenter. If not specified, the entire inventory is searched. *Since* vSphere API 4.0
dnsName P	xsd:string	The fully qualified domain name to find. *Since* vSphere API 4.0
vmSearch P	xsd:boolean	If true, search for virtual machines, otherwise search for hosts. *Since* vSphere API 4.0

*Need not be set PRequired privilege - see tooltip for details

Return Value

Type	Description
ManagedObjectReference[] to a ManagedEntity[]	The list of all virtual machines or hosts that are found. If no managed entities are found, an empty list is returned. If there are multiple matches, all matching entities are returned.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindAllByDnsName" type="vim25:FindAllByDnsNameRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindAllByDnsNameResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ManagedObjectReference" maxOccurs="unbounded"/>
                     </sequence>
                  </complexType>
               </element>

FindAllByIp(findAllByIp)

Finds all virtual machines or hosts by IP address, where the IP address is in dot-decimal notation. For example, 10.17.12.12. The IP address for a virtual machine is the one returned from VMware tools, ipAddress.

Required Privileges: System.View
Since: vSphere API 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the SearchIndex used to make the method call.
datacenter* P	ManagedObjectReference to a Datacenter	If specified, restricts the query to entities in a particular datacenter. If not specified, the entire inventory is searched. *Since* vSphere API 4.0
ip P	xsd:string	The dot-decimal notation formatted IP address to find. *Since* vSphere API 4.0
vmSearch P	xsd:boolean	If true, search for virtual machines, otherwise search for hosts. *Since* vSphere API 4.0

*Need not be set PRequired privilege - see tooltip for details

Return Value

Type	Description
ManagedObjectReference[] to a ManagedEntity[]	The list of all virtual machines or hosts that are found. If no managed entities are found, an empty list is returned. If there are multiple matches, all matching entities are returned.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindAllByIp" type="vim25:FindAllByIpRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindAllByIpResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ManagedObjectReference" maxOccurs="unbounded"/>
                     </sequence>
                  </complexType>
               </element>

FindAllByUuid(findAllByUuid)

Finds all virtual machines or hosts by UUID.

Required Privileges: System.View
Since: vSphere API 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the SearchIndex used to make the method call.
datacenter* P	ManagedObjectReference to a Datacenter	If specified, restricts the query to entities in a particular datacenter. If not specified, the entire inventory is searched. *Since* vSphere API 4.0
uuid P	xsd:string	The UUID to find. If vmSearch is true, the UUID can be either BIOS or instance UUID. *Since* vSphere API 4.0
vmSearch P	xsd:boolean	If true, search for virtual machines, otherwise search for hosts. *Since* vSphere API 4.0
instanceUuid* P	xsd:boolean	Should only be set when vmSearch is true. If specified, search for virtual machines whose instance UUID matches the given uuid. Otherwise, search for virtual machines whose BIOS UUID matches the given uuid. *Since* vSphere API 4.0

*Need not be set PRequired privilege - see tooltip for details

Return Value

Type	Description
ManagedObjectReference[] to a ManagedEntity[]	The list of all virtual machines or hosts that are matching with the given UUID. If no managed entities are found, an empty list is returned. If there are multiple matches, all matching entities are returned.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindAllByUuid" type="vim25:FindAllByUuidRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindAllByUuidResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ManagedObjectReference" maxOccurs="unbounded"/>
                     </sequence>
                  </complexType>
               </element>

FindByDatastorePath(findByDatastorePath)

Finds a virtual machine by its location on a datastore.

Required Privileges: System.View

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the SearchIndex used to make the method call.

datacenter P

ManagedObjectReference
to a Datacenter

Specifies the datacenter to which the datastore path belongs.

Since 2.0

path P

xsd:string

A datastore path to the .vmx file for the virtual machine.

Since 2.0

PRequired privilege - see tooltip for details

Return Value

Type	Description
ManagedObjectReference to a VirtualMachine	The virtual machine that is found. If no virtual machine is found, null is returned. Only a single entity is returned, even if there are multiple matches.

Faults

Type	Description
InvalidDatastore	Thrown if a datastore has not been specified in the path or if the specified datastore does not exist on the specified datacenter.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindByDatastorePath" type="vim25:FindByDatastorePathRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindByDatastorePathResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ManagedObjectReference" minOccurs="0"/>
                     </sequence>
                  </complexType>
               </element>

FindByDnsName(findByDnsName)

Finds a virtual machine or host by DNS name. The DNS name for a virtual machine is the one returned from VMware tools, hostName.

Required Privileges: System.View

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the SearchIndex used to make the method call.
datacenter* P	ManagedObjectReference to a Datacenter	If specified, restricts the query to entities in a particular datacenter. If not specified, the entire inventory is searched. *Since* 2.0
dnsName P	xsd:string	The fully qualified domain name to find. *Since* 2.0
vmSearch P	xsd:boolean	if true, search for virtual machines, otherwise search for hosts. *Since* 2.0

*Need not be set PRequired privilege - see tooltip for details

Return Value

Type	Description
ManagedObjectReference to a ManagedEntity	The virtual machine or host managed entity that is found. If no managed entities are found, null is returned. Only a single entity is returned, even if there are multiple matches.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindByDnsName" type="vim25:FindByDnsNameRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindByDnsNameResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ManagedObjectReference" minOccurs="0"/>
                     </sequence>
                  </complexType>
               </element>

FindByInventoryPath(findByInventoryPath)

Finds a managed entity based on its location in the inventory. The path is separated by slashes ('/'). For example, a path should be of the form "My Folder/My Datacenter/vm/Discovered VM/VM1". A leading slash or trailing slash is ignored. Thus, the following paths all represents the same object: "a/b", "/a/b", "a/b/", and '/a/b/'. Slashes in names must be represented using %2f, following the standard URL syntax. Any object in the inventory can be retrieved using this method, including resource pools and hosts.

Required Privileges: System.View

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the SearchIndex used to make the method call.

inventoryPath P

xsd:string

The path to the entity.

Since 2.0

P Required privilege: inventoryPath

Return Value

Type	Description
ManagedObjectReference to a ManagedEntity	The managed entity that is found. If no match is found, null is returned.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindByInventoryPath" type="vim25:FindByInventoryPathRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindByInventoryPathResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ManagedObjectReference" minOccurs="0"/>
                     </sequence>
                  </complexType>
               </element>

FindByIp(findByIp)

Finds a virtual machine or host by IP address, where the IP address is in dot-decimal notation. For example, 10.17.12.12. The IP address for a virtual machine is the one returned from VMware tools, ipAddress.

Required Privileges: System.View

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the SearchIndex used to make the method call.
datacenter* P	ManagedObjectReference to a Datacenter	If specified, restricts the query to entities in a particular datacenter. If not specified, the entire inventory is searched. *Since* 2.0
ip P	xsd:string	The dot-decimal notation formatted IP address to find. *Since* 2.0
vmSearch P	xsd:boolean	if true, search for virtual machines, otherwise search for hosts. *Since* 2.0

*Need not be set PRequired privilege - see tooltip for details

Return Value

Type	Description
ManagedObjectReference to a ManagedEntity	The virtual machine or host managed entity that is found. If no managed entities are found, null is returned. Only a single entity is returned, even if there are multiple matches. If called directly on an ESX server with vmSearch set to false, returns the host managed entity if the address matches any of the Console OS IP addresses.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindByIp" type="vim25:FindByIpRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindByIpResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ManagedObjectReference" minOccurs="0"/>
                     </sequence>
                  </complexType>
               </element>

FindByUuid(findByUuid)

Finds a virtual machine or host by BIOS or instance UUID.

Required Privileges: System.View

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the SearchIndex used to make the method call.
datacenter* P	ManagedObjectReference to a Datacenter	If specified, restricts the query to entities in a particular datacenter. If not specified, the entire inventory is searched. *Since* 2.0
uuid P	xsd:string	The UUID to find. If vmSearch is true, the uuid can be either BIOS or instance UUID. *Since* 2.0
vmSearch P	xsd:boolean	If true, search for virtual machines, otherwise search for hosts. *Since* 2.0
instanceUuid* P	xsd:boolean	Should only be set when vmSearch is true. If specified, search for virtual machines whose instance UUID matches the given uuid. Otherwise, search for virtual machines whose BIOS UUID matches the given uuid. *Since* 2.0

*Need not be set PRequired privilege - see tooltip for details

Return Value

Type	Description
ManagedObjectReference to a ManagedEntity	The virtual machine or host managed entity that is found. If no managed entities are found, null is returned. Only a single entity is returned, even if there are multiple matches.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindByUuid" type="vim25:FindByUuidRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindByUuidResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ManagedObjectReference" minOccurs="0"/>
                     </sequence>
                  </complexType>
               </element>

FindChild(findChild)

Finds a particular child based on a managed entity name. This only searches the immediate children of a managed entity. For a Datacenter, the host and vm folders are considered children. For a ComputeResource, the hosts and root ResourcePool are considered children.

Required Privileges: System.View

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the SearchIndex used to make the method call.

entity P

ManagedObjectReference
to a ManagedEntity

A reference to a managed entity.

Since 2.0

name P

xsd:string

The name of the child object.

Since 2.0

PRequired privilege - see tooltip for details

Return Value

Type	Description
ManagedObjectReference to a ManagedEntity	The managed entity that is found, or null if no match is found.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindChild" type="vim25:FindChildRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindChildResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ManagedObjectReference" minOccurs="0"/>
                     </sequence>
                  </complexType>
               </element>