Step1: Fetch the Schema
Under the hood (IO) uses internal identifiers to track each entity type and metric ID. When interacting with the rest APIs you need to user the internal identifiers. The schema API provides the ability to look up and find the internal identifiers for entity types, properties and metrics for each entity type.
Tip
Refer to the Schema section in the swagger documentation for other help end points and more information
Each time you need to identify a new entity type, and/or additional metrics or property ids, you perform a GET to the following endpoint:
https://IPADDRESS/api/sdk/p/2/schema?withMatchingDisplayLabel=ESX%20VM&returnNameOnly=true&returnProperties=NONE&returnMetricsWithMatchingDisplayLabel=VM.*CPU.*
The response will contain schema information about entity types that match the ESX VM entity name, and will provide the results for all metrics matching the patten VM.*CPU.*.
For our scenario we note that the entity type ID is Virtual Machine and the metric ID is VM_cpu_used
Here is a breakdown of the various query parameters in that request:
withMatchingDisplayLabel=ESX%20VM: This option searches for all entity types that match that regular expression. In our case we provided an exact match based on the name shown in the (IO) user interface.
returnNameOnly=true: Our schema information contains a lot of meta data about each property and metric, including units, display names, types etc. By just returning the name (and id) we reduce the size and noise in the response.
returnProperties=NONE: Controls if we return information about available properties on each matching type. Since our example only filters by DisplayLabel we do not need any additional property information. If however you wanted to consider searching by other properties, you could set this to "FILTERABLE" and the list of properties which can be used in a filter will be returned.
returnMetricsWithMatchingDisplayLabel=VM.*CPU.*: (IO) supports many metrics for each entity type - this allows us to use a regular expression to reduce the number of metrics we are looking down to just the specific one of interest. If you have the exact name as shown in the user interface you can skip the wildcard matching portions for a faster look up.
These are just some of the options available to you when querying the available schema information. Refer to the swagger guide for more information.