Previously we showed you how to use the useful cmdlets available with the PowerCLI vRealize Operations Manager (vR Ops) module, but as we also explained there are only a few cmdlets at the moment and anyone who knows vR Ops will know that there is a lot more functionality than is provided by those cmdlets.
But don’t worry, it is possible to access the entire vR Ops REST API! PowerCLI gives us the ability to expand the capability of the module to perform many more tasks that aren’t available via the included cmdlets.
In this blog post, which is a continuation of my previous blog posts on the PowerCLI vR Ops module, I will explain how to access the entire vR Ops public REST API via PowerCLI. Before I begin, it will be helpful to cover some basic information about the vR Ops REST API.
The API is available via the base URI of https://{vrops-IP}/suite-api and if you browse to this link the documentation is available. For the most part, the API is pretty well documented with examples for usage including payloads for XML and JSON. Below is a screenshot of the XML request body example for the performAction method.
Throughout this post I will refer to the API documentation for example content such as this. So, if you are following along take some time to browse the API documentation and leave it open as I continue.
Another important topic to cover before I start is “extensionData” in PowerCLI. For those unfamiliar, this is a property container that is used for information returned from a client API call that doesn’t have a corresponding object property in PowerShell. For example, as in my previous post, I invoke the cmdlet Get-OMResource to retrieve a vR Ops resource object, the object properties includes “extensionData” that has a lot of interesting content.
ExtensionData is the key concept in accessing the vR Ops API via PowerCLI.
I will use the customer requirement for adding and updating a resource property as a walk-through. This should give you a good, basic understanding of how to leverage PowerCLI for any automation or programmatic administration of vR Ops.
To being, when I create a connection to vR Ops using Connect-OMServer a global variable is stored, $global:defaultOMServers, which has an extensionData property.
By the way, the [0] is the index of the server connection, since you can have multiple. To simply things for my purposes, I just assign the connection properties to a local variable.
Note that the extensionData property refers to the vR Ops API. This is where things get interesting! We can easily use the PowerShell Get-Member cmdlet or “gm” for short to explore the properties and methods in the extensionData property.
As you can see, there are a lot of methods available. This is where it is handy to have the API documentation open, because you can get additional information about each of these methods there by searching for the method name. For example, above there is a method CreateReport and I can find this in the API documentation by just using Ctrl-F in my browser.
Generally speaking, the methods you find in the extensionData of the server connection are “top level” URIs. For example /api/resource is a top level URI but there are lower level URIs like /api/resource/{id}/properties that are not contained in the server connection list of methods.
To access those, you simply need to browse the underlying object (for example, a resource object) and view the method membership within that object’s ExtensionData. I used a shortcut here, but basically the command I used drills down to a resource object to show the members.
Notice the AddProperties method is available here. I will look that up in the documentation.
Before I continue, I will grab a resource for which I want to create a new property, a virtual machine running Windows server OS named “bmutil”
If I simply reference the method, I can get help on the usage via the OverloadDefinitions property.
The method requires a single input of type VMware.VimAutomation.VRops.Views.PropertyContents so I will create a new variable $contentprops of this type to investigate.
So the only property is the singular Propertycontent. Now I will create a variable contentprop of type VMware.VimAutomation.VROps.Views.PropertyContent.
Hopefully, you aren’t confused by all of this! It can be a little frustrating. This is where the API documentation comes in handy because the input parameter is the XML payload you would send as the REST request body via HTTP. As I mentioned before, the API documentation provides an example.
I like to refer to the sample XML body because it helps in understanding how to create the input in PowerCLI. Visualizing this way helps put all of this into perspective. In addition to this, you can find in the API documentation more detail on the various data models used by the API which can be helpful in figuring out exactly what is required and descriptions of the properties. For example, you’ll find within the method’s documentation links to the data representations as shown below.
Now, this link actually navigates to <ns3:property-contents> (with an “s” just like the PowerCLI type above) which is a collection of <ns3:property-content> and that model is actually the one that explains what each of the key:value pairs in the payload are used for, the data type and whether or not it is a required field.
Using this information, I can now update the payload for the method. I am going to
create a new property called “custom|testproperty” with a value of “Created by PowerCLI” and manually put in a timestamp value. By the way, the timestamp value is a Unix epoch timestamp (i.e. number of seconds since January 1, 1970).
Now I will update the $contentprop variable with the required values.
Next I will update the $contentprops variable with $contentprop.
And I am ready to invoke the method to add this new property to my resource. But before that, I want to show that the property is not there by invoking the resource method GetResourceProperties.
OK, here we go… invoke $resource.ExtensionData.AddProperties($contentprops)…
Success! If I want to change the value of this property, I simply provide the same statkey property name with the new timestamp and value. Here I will just reuse the $contentprop and $contentprops variables.
The PowerCLI module for vR Ops is fully capable of leveraging the entire vR Ops public API and I hope this blog post provided you with a solid understanding of usage and concepts to explore and implement your own use cases. With this information you can easily create functions and community modules to open up more of the vR Ops functionality via PowerCLI and automate more of your infrastructure.
John Dias is a Staff Systems Engineer on VMware’s Solution Engineering and Technology team specializing in Cloud Management solutions.
John is a veteran IT professional with over 22 years of experience, most of that having been on the customer side running data center operations, data storage, virtual infrastructure and Unix environments for a major financial institution.
He normally blogs at storagegumbo.com and in his spare time he enjoys astronomy and astrophotography.