ScriptVcopsvRops

vRops API consumed with Powershell

vRops have been out for sometime now, and a lot of new features have been added, not to talk about a whole new user interface experience. The future looks bright for vRops. Another great feature is a REST / RESTful api.

This what I’m going to talk a bit about, and more so show vRops API consumed with Powershell.

First thing to know is how to get a hold of the vRops API and the documentation for it, and if you should wish to use it, there’s also a java and python client. I prefer to use a plugin for Firefox or Chrome, but again it’s up to you.

vRops API – https://vRopsIP/suite-api/api/

vRops API Documentation – https://vRopsIP/suite-api/docs/rest/index.html

vRops API Clients – https://vRopsIP/suite-api/

You can also just browse around the API, a good place to start would be https://vRopsIP/suite-api/api/adapters or https://vRopsIP/suite-api/api/resources/ just to get an idea of how data is structured and what kind of data you can get access to.

To get access to the API data you will need to authenticate, I use the admin user.

vRops API consumed with Powershell

First I’m using Powershell v4, as a ran into some issues with an earlier version. Second we need a way to trust the ssl certificate, this can be done with the below code.

 

add-type @"
    using System.Net;
    using System.Security.Cryptography.X509Certificates;
    public class TrustAllCertsPolicy : ICertificatePolicy {
        public bool CheckValidationResult(
            ServicePoint srvPoint, X509Certificate certificate,
            WebRequest request, int certificateProblem) {
            return true;
        }
    }
"@
[System.Net.ServicePointManager]::CertificatePolicy = New-Object TrustAllCertsPolicy

 

With that done let’s jump into it. The command I’m going to use is called ‘Invoke-RestMethod’. It works in the way that you provide it with a ‘Method’, a ‘URI’ and a set of ‘Credential’. The ‘Method’ is what you want to do, the options are ‘Default’, ‘Delete’, ‘Get’, ‘Head’, ‘Merge’, ‘Options’, ‘Patch’, ‘Post’, ‘Put’, and ‘Trace’. I will circle back to ‘URI’ in a moment, so next up is ‘Credential’, this should clear to most, but that’s a username and a password. There are multiple ways to do this (Get-Credential is one way), but you can also use the below and then provide $cred to the -Credential parameter.

$username = "User"
$password = "Password"
$secPw = ConvertTo-SecureString $password -AsPlainText -Force
$cred = New-Object PSCredential -ArgumentList $username,$secPw

 

That brings us to the ‘URI’, which is also referred to as URL. The URI is a structured call, for which we can define what the output shall include. The URI can be quite simple as shown below:

Https://vRopsIP/suite-api/api/resources – This shows a list of resources – A resource can for example be a VM, a Host or a Datastore. Another example would be:

Https://vRopsIP/suite-api/api/adapters – Again this is pretty straightforward, this outputs a list of adapters.

In the next part I’m going to show you how this can be used in different ways to get data out and how to get the data needed.

 

Examples of vRops API consumed with Powershell

I’m going to jump straight into it. The below picture shows what I already talked about. First part trusts all ssl certificates, then the $cred store is populated with username and password in a secure manner (Don’t write it in clear text as I did here as it defeats the purpose. Get it as an input) and last the Invoke-RestMethod is used to get a list of resources.

vRops-API-GettingStarted

The variable $data, now contains the output from the Invoke-RestMethod command. Now it possible to dig into the data set. By default data is in xml format, this can be changed, I will get back to that later.

vRops-API-XMLData

 

Now I dig into the actual data, by running the above command

 

vRops-API-Resources

Above I have started to look at what the out come of the Invoke-RestMethod command I ran before. This list all the resources (By default only 100 items are returned per page – This can be changed in the URI path by adding pageSize=<NUMBER>. The max page size is 5000) and some of them can be seen here. Below I go a step deeper by looking a the resourceKey. AdapterKindKey refers to the adapter or content pack from which data is gathered and resourceKindKey refers to the type of object this item belongs to. This is a way to find the object you need, to get more data out such as statistics.

vRops-API-ResourceKey

I pick the first VM to show case what you can use the vRops API for. I need the identifier of the object in order to do a specific query for that object and it’s data. This is what is done in the first line below and after that I run the Invoke-RestMethod command. This time I have expanded a bit on what I have done so far. First I have after ‘resources/’ added stats, which mean that the output will contain stats data from the object queried, next is ‘ResourceID’, the is the ID I just got form the previous command. Now I come to commands ‘format’ and ‘rolluptype’, the first can be ‘csv’ or ‘xml’ (think it possible to do json, but haven’t tried) and the latter can be ‘min’, ‘avg’ or ‘max’ dependent on your need. So now $data gets populated with statistical data from the VM named ‘PvmDB_2’, in CSV format and with the rolluptype set to average.

vRops-API-ResourcesIDfier

 

 

This is a snipped of the output of the $data variable, as it can be seen structured over six lines per data set.

First line is the ID of the object

Second line is the metric being displayed

Line three and four are blank

The fifth line is timestamps in milliseconds since epoc and

the sixth line is the actual data which has been collected for the metric.

 

vRops-API-CSVData

 

 

Next picture shows the same query as above just as xml instead of csv (the same query not the same metric)

vRops-API-XMLDataOutPut

 

So there you have it vRops data straight out of vRops it self. But as a little treat I have a last query to run before I end this blog post. Notices at the end of the URI, I have added ‘statkey=cpu:0|swapwait_summation’ so instead of getting all data points for a given object, I have now specified which metric or statkey if you will, that I want data from. Multiple metric can be specified in a single URI, which makes it a lot easier to get large data set out of vRops. Example of this could be for reporting or monitoring.

vRops-API-StatKey

 

Before I end, these screen dumps and tests were done on VMware’s Hands on labs, which are located at http://labs.hol.vmware.com/ I used the lab called HOL-SDC-1401. Thanks to VMware’s HOL team for providing these awesome play grounds, which can be used to learn how VMware’s products work. On a side note I have also used HOL for doing live demos at VMUG, that’s just how awesome they are.

 

That’s all for now – More will come in due time.

 

9 thoughts on “vRops API consumed with Powershell

  1. This is an excellent post and i was able to recreate it for a lot of other Get calls in the vrops api. My question is, do you have a similar post for how to submit a Post method call to an endpoint to put data into vROps?

    For example, i’d like to create a notification rule via the api (https://server/notifcations/rules), with the $body variable containing the name:value pairs i need to create it. For this call, only the ‘name’ variable is required.

    $body = @{
    “name” = “myNewRule”
    }
    Invoke-RestMethod -ContentType ‘application/json’ -Method Post -Uri $url -Credential $cred -Body ($body | ConvertTo-Json)

    I get an error 500 Internal Server Error when i run it this way. What am i missing?

    Thanks for your help.

  2. Hi. Thank you for article. It is good starting point for me. But can you update article for vROPS? Some things are different in vROPS, for example list of resources is simply $data.’resources’. ‘resource’

  3. Hi, I’m a bit late to the party, but there just doesn’t seem to be that many articles on this topic -__-
    Thanks for a great article.
    The https://vRopsIP/suite-api/docs/rest/index.html page would have been great if VMware had included examples…
    Their lack of useful documentation makes their API really difficult to use effectively. Hopefully you, or others, will write some more articles like this 😉

Leave a Reply

Your email address will not be published. Required fields are marked *