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.