A frequent request from the field and VMware customers is, “How can I get data out of vROps using the REST APIs?”  The reasons for this vary, but typically there is a desire to incorporate the metrics and properties from vROps with another data set or monitoring tool.  In this blog post, I’ll give you an overview of how to use the vROps REST APIs to pull information.

By the way, there is a fantastic fling that I recommend customers investigate for this purpose.  It also uses the REST APIs but in an easier-to-use executable.  For many, it provides exactly what is required.  For others, they prefer to use the REST APIs directly because they need to run the extraction as part of another process and don’t want to use the fling; if that’s you, this blog will help.

Setting Up Your Postman Environment

I will be using Postman client for this, and if you would like to download my Postman collection for vRealize Operations you can find it here.  If you aren’t familiar with Postman, I highly recommend it to explore REST APIs and develop code or write scripts that use the APIs.

To begin, I want to point out a few features I configure in Postman to save time.  First, I always set up an environment to hold variables such as authentication information, response data or other bits I will need in common with other REST calls.  For example, here’s my current environment:

I can set up several environments in Postman so I can easily switch between REST endpoints or solutions.  Many of the variables above are created and updated dynamically as part of my REST calls.  You will see that later in this blog.

At a minimum, to use my Postman collection for vROps, you will need an environment with three variables:

Vrops: the FQDN or IP of your vROps node

User: a local vROps user with API permissions

Pass: the user’s password (be careful here as this is stored in the clear)

Authentication

Once the environment is ready, you can begin working with the collection.  The first request you will send is the one named “RUN FIRST – Get vR Ops Auth Token”

Notice the request URL and the request body contain items in double curly braces, like {{user}}.  This is how we reference the environment variables set up earlier.  They variables are replaced with your environment values when the request is sent.

Why am I making you run this first?  While you could use basic authentication for the requests, that is not a best practice.  Better, faster and more secure is to use something called a Bearer Token which can be saved in the environment and used for successive requests.  This is what the Tests tab handles in this request:

The tests are just snippets of Javascript that can perform post-request tasks such as evaluating the response to make sure it is the expected response or contains an expected value.  In my collection, I’m using it to store variables in the environment as well.  For example, my request for a token returns:

Which is stored in my environment automatically, as the current value (the one on the right, ignore “INITIAL VALUE” for now):

Now my subsequent requests will use this token to authenticate.

Getting Resource IDs

With authentication handled, let’s dive into the subject which is getting metrics and properties out of vROps.  Usually, customers want to get this data for particular resource kinds (like virtual machines) or for specific objects (like all hosts in a cluster).  I’ll use the example of getting metrics for all virtual machines first.

To begin, we need to get the resourceIds of each virtual machine resource.  The resourceId is a unique identifier used in vROps for each resource.  To do this, we will use the request titled “Get Resources by resourceKind and Save to var” – which will do exactly what it says!

First, note that I have a header for Authorization that includes the Bearer Token variable I saved earlier:

Now, take a look at the URL above.  The API is GET Resources and one optional query I can add to the URL template is the resourceKind (the query is the part of the URL to the right of the “?”).  Any valid resourceKind can be used in the query and you can even search for multiple resourceKinds in a single request.  For example:

You can add other query parameters, but let’s keep it simple for now.  When I submit the request, the variables are replaced with the values from your current environment.  You can see this by selecting the “Code” link to the right of the request window – Postman will generate a code snippet for your use in many different programming and scripting languages!  Here’s a Python snippet using the Requests module:

When the response is returned, you can see the reply (in JSON) in the Body tab below the request.

I got 103 resources of resourceKind VirtualMachine.  Fantastic, but what to do with this response?  Once again the Tests comes to the rescue.  In this request, I’ve added a test to parse through the response and grab all the resourceIds and place them into an environment variable named “resourceIds”:

I’m doing this for you in Postman, but you will need to write your own code to extract these resourceIds obviously.

Time to Get Metrics!

Now that I have all the resourceIds I need, I’m going to send another request to query for some metrics.  Let’s say I want to get all CPU metrics for these VMs.

Here’s a pro-tip since this comes up a lot and it can cause your script or code to run very slowly even in moderately sized environments.  Do NOT use repeated GET requests to retrieve metrics or properties.  Instead, use POST to query for stats (the vROps API lingo for metrics) and properties.  For example, in my collection use “Query Metrics of Resources” instead of “Get Stats from Resource (not query)” to get metrics from multiple resources in a single request.

Now, this is where we will need to understand precisely what data your project requires from vROps.

• What timeframes? e. last 5 minutes?  Last day?
• How should they be rolled up?
• Which metrics or properties?

Now is as good a time as any to introduce the API documentation.  You can find this on your vROps appliance by browsing to https://{{your vrops IP}}/suite-api and the documentation is a blog for another day.  I’m only showing this to give you an idea of what can be included in your query request:

For example, I want to get all CPU metrics for the virtual machines from the last 24 hours and I want the hourly average of each metric.

The body of my request would look like:

Notice I have a lot of environment variables in the body!  You probably understand why I have {{resourceIds}} since we covered that previously.  Let me explain the others.

{{cpuStatsJSON}} is a variable that results from the test run after “Get StatKeys for Resource and Load var” to make it easy to find and use statKeys in subsequent requests.  Take a look at the test and note that I’m only extracting statKeys that start with “cpu|” so you can modify this test if you would like to use a different set of statKeys.

Of course, you don’t need to use my environment variable.  You can simply replace the statKey array value with one or more statKeys in JSON format (i.e. [“statkey1”,”statkey2”,”statkey3”]).

{{epoch} and {{epochPrev24}} are timestamps created by Pre-request Script, the twin feature of Tests.  In this case, before the request is sent, the pre-request script is run and the epoch values for the current time and the previous 24 hours are added to the environment variables.

No doubt, you would do something similar in your own code.

Finally, the query parameters for rollUpType, intervalType and intervalQuantifier provide the formatting for the response data.  In this query, we will get a response for the previous 24 hours for each metric with an hourly average.

Let’s say that instead you wanted to see the maximum for every 30 minutes.  In that case, you would change the format parameters as follows:

“rollUpType” : “MAX”,
“intervalType” : “MINUTES”,
“intervalQuantifier” : “30”,

However, change your “begin” and “end” values to a shorter time period – setting the format with that level of granularity will increase the response time.

Overview of the Response

Now we can send the request and get our data!

Maybe a little hard to see from the screenshot, but notice the time (upper right corner) for the response was about 2 seconds (for 325 VMs).  Compare that with a response time for getting metrics from an individual resource (around 401ms) multiplied by the number of resources (325 VMs * 401ms) means that it would take 2 minutes to get the same information.  This is why I strongly recommend using the query APIs instead.

Now that you have your data, I want to point out a couple of things.  In the JSON response (XML is available, just change your Accept header) you will find an array of “values” for each resourceId that had metrics meeting the query parameters.  I’ve loaded this into jsonviewer.stack.hu to make it easier to navigate:

What you end up with is an array of timestamps and an array of values (the “data” key).  From here, you just need to write your code to present this information in whatever format you require!

I hope this blog post and the Postman collection helps you with extracting metrics and properties from vRealize Operations.  Feedback is welcome either via comment or Twitter @johnddias.