Step2: Find the entity identifiers
When an instance of an entity type is created it is assigned a unique identifier (uid). These UIDs are globally unique across types. Using the internal entity type name, and (optionally) additional filter properties, you can query and find the entities that you want to report on. Filtering can be quite complex, leveraging topology information, properties and logical operators such as AND and OR. In our example we are focusing on search all entities of a given type for a specific property value.
Tip
Refer to the Schema section in the swagger documentation for other helpful end points and more information
Each time you need to identify a new entity instance you perform a GET to the following endpoint:
https://IPADDRESS/api/sdk/p/2/inventory/type/VirtualMachine?f ilterProperty=DisplayLabel&filterOperator=iContains&filterValue=<partial_vm_name>&prop=EntityType&prop=uid&prop=DisplayLabel
The response will contain the first 10 ESX VMs, whose display label (i.e. name) matches the <partial_vm_name> value provided. For each VM the entity type, uid, and display label will be returned.
For our scenario we note the uid for the desired ESX VM.
Here is a breakdown of the various query parameters in that request:
VirtualMachine: This portion of the URL restricts our search to a given entity type. Here we are using the internal identifier found during step 1. All further options are restricted to entities of this type.
Tip
Refer to swagger documentation for more advanced filtering options, such as filtering across multiple entity types.
filterProperty=DisplayLabel: This indicates that you want to filter the set of entities based on the DisplayLabel (i.e. name that you see in the UI. We are providing the internal ID of this filterable property (as noted during step 1.
filterOperator=iContains: This is the filter operation to use when matching the value against the property. In this case we are doing a case-insensitive contains, i.e. where it is considered a match if any portion of the name contains the provided value in order, regardless of case. To do an exact match you could provide `equals` as the operators. There are numerous additional operators documented in the swagger documentation.
filterValue=<partial_vm_name>: Provides the name that you want to search for. How this value is interpreted depends on the filterOperator - in this example it is the text which should be found anywhere in the name, regardless of case.
prop=EntityType&prop=uid&prop=DisplayLabel: This lists out the properties that we want returned for each entity that we find. You can list out multiple prop items to request various properties.
The options listed here are just a subset of what is available. Refer to the swagger documentation for additional options.
Operators
Detailed descriptions for each operator are provided in the section below.
Group - Equality
equals: Property exactly equals the specified value (Leverages indexes).
notEquals: Property is undefined or does not exactly equal the value (Leverages indexes.)
iEquals: Case-insensitive equals operator.
notiEquals: Case-insensitive not equals operator.
Group- String Match
regex: Uses regular expressions (Disabled by default; security risk).
pattern: Safe, simple pattern matcher supporting *, ?, and | (OR).
notPattern: Property does not match the specified safe pattern.
startsWith: String property starts with the specific string (case-sensitive).
notStartsWith: Property is undefined or does not start with the specific string.
endsWith: String property ends with the specific string (case-sensitive).
notEndsWith: Property is undefined or does not end with the specific string.
Group - List/Contains
in: Property value exactly matches ANY of the supplied list values (Leverages indexes).
notIn: Property is undefined or does NOT exactly match ALL of the specified list values (Leverages indexes).
contains: String property contains the specific string (case-sensitive), (Leverages indexes).
notContains: Property is undefined or does not contain the specific string (case-sensitive), (Leverages indexes.)
Group - Existence
defined: Determines if the property is/is not defined on the object.
Group - List/Contains
iContains: String property contains the specific string (case-insensitive). (Does NOT leverage indexes.)
notiContains: Property is undefined or does not contain the specific string (case-insensitive). (Does NOT leverage indexes.)
Group - List Element
leIn: Any value in a list property matches any value in the supplied list.
notleIn: Property is undefined or all values in the list property do not match all values in the supplied list.
leContains: Any value in a list property contains the supplied value (case-sensitive).
notleContains: Property is undefined or ALL values in the list property do not contain the supplied value (case-sensitive).
ileContains: Any value in a list property contains the supplied value (case-insensitive).
notileContains: Property is undefined or ALL values in the list property do not contain the supplied value (case-insensitive).
Group - Boolean
and: Returns true if all nested property matchers return true.
or: Returns true if any of the nested property matchers return true
union: Internal OR-like operator for handling embedded relationships.
not: Returns true if the nested property matcher returns false (Not available via REST API).
Group - Relationship
relatesTo: Returns elements related to criteria; elements must have this relationship.
notRelatesTo: Returns elements not related to elements matching the criteria.
optionalRelatesTo: Returns elements related to criteria; elements without the relationship are also returned.