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 the following example, we are searching all entities of a given type for a specific property value.
Tip
See the Schema section in the Swagger documentation for other helpful endpoints and more information.
Each time you need to identify a new entity instance, perform a GET request to the following endpoint:
https://<IPADDRESS>/api/sdk/p/2/inventory/type/VirtualMachine?filterProperty=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 (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 in Step 1. All further options are restricted to entities of this type.
Tip
See the 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 (the name that you see in the user interface). 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 performing a case-insensitive ICONTAINS operation instead of a CONTAINS operation, such that a match of any portion of the name contains the provided value regardless of case. To do an exact match you could use EQUALS as the operator. There are 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 found anywhere in the name, regardless of case.
prop=EntityType&prop=uid&prop=DisplayLabel: This lists the properties that we want returned for each entity that we find. You can list multiple property items to request various properties.
The options listed here are only a subset of what is available. See the Swagger documentation for additional options.
Property Filter Operators
Property filter operators allow you to define conditions when querying or filtering objects. These operators determine how a property value is evaluated against the specified criteria.
Equality Operators
Use equality operators to check whether a property exactly matches or does not match a specified value.
Operator | Description | Recommended Documentation |
|---|---|---|
| Property exactly equals the specified value. Uses indexes for faster queries. | Yes |
| Property is undefined or does not exactly equal the specified value. Uses indexes. | Yes |
| Case-insensitive equality comparison. | Yes |
| Case-insensitive not-equals comparison. | Yes |
String Matching Operators
These operators match string values based on patterns or specific prefixes/suffixes.
Operator | Description |
|---|---|
pattern | Safe pattern matcher supporting *, ?, and ` |
notPattern | Property does not match the specified pattern. |
startsWith | String property starts with the specified string (case-sensitive). |
notStartsWith | Property is undefined or does not start with the specified string. |
endsWith | String property ends with the specified string (case-sensitive). |
notEndsWith | Property is undefined or does not end with the specified string. |
Boolean Operators
Boolean operators allow you to combine multiple property filters.
Operator | Description |
|---|---|
and | Returns true only if all nested property matchers evaluate to true. |
or | Returns true if any nested property matcher evaluates to true. |
union | Internal OR-like operator used for embedded relationships. |
not | Returns true if the nested property matcher evaluates to false. Not available through the REST API. |
Relationship Operators
These operators filter objects based on their relationships with other objects.
Operator | Description |
|---|---|
relatesTo | Returns elements related to objects matching the specified criteria. |
notRelatesTo | Returns elements not related to objects matching the criteria. |
optionalRelatesTo | Returns elements related to the criteria and also includes elements without the relationship. |
List Element Operators
These operators evaluate values inside list-type properties.
Operator | Description |
|---|---|
leIn | Any value in a list property matches any value in the supplied list. |