Home > Blogs > VMware PowerCLI Blog


Using the entire API for vRealize Operations via PowerCLI

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.

clip_image002

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.

clip_image004

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.

clip_image006

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. 

clip_image008

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.

clip_image010

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.

clip_image012

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.

clip_image014

Notice the AddProperties method is available here.  I will look that up in the documentation.

clip_image016

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”

clip_image018

If I simply reference the method, I can get help on the usage via the OverloadDefinitions property.

clip_image020

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.

clip_image022

So the only property is the singular Propertycontent.  Now I will create a variable contentprop of type VMware.VimAutomation.VROps.Views.PropertyContent.

clip_image024

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.

clip_image026

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.

clip_image027

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.

clip_image029

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.

clip_image031

Next I will update the $contentprops variable with $contentprop.

clip_image033

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.
 

clip_image035

OK, here we go… invoke $resource.ExtensionData.AddProperties($contentprops)…

clip_image037

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.

clip_image039

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.


Dias_John_thumb1_thumbJohn 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.

This entry was posted in vRealize Operations and tagged on by .
Alan Renouf

About Alan Renouf

Alan Renouf is a Product Line Manager at VMware focusing on API's, SDK's and CLI's, He is responsible for providing the architects and operators of private and public cloud infrastructure with the toolkits/frameworks and command-line interfaces they require to build a fully automated software-defined datacenter. Alan is a frequent blogger at http://blogs.vmware.com/PowerCLI a book author and has a personal blog at http://virtu-al.net. You can follow Alan on twitter as @alanrenouf.

6 thoughts on “Using the entire API for vRealize Operations via PowerCLI

  1. Matthew Graci

    What is the command syntax to execute the PushEvent RestAPI via PowerCli for a VM?

    Thanks,
    -Matt

    Reply
  2. James

    Great post. One thing I woud like to do is to create custom groups via PowerCLI or the API. Unfortunately it seems that’s not currently possible 🙁

    I want to create vSphere Virtual Machine Tags that contain application IDs and then create a dynamic group for each App ID so that it will automatically group VMs into the same application. I have tested it on a small scale by manually creating a few custom Groups in vROPS and it works but I need to create hundreds 🙁

    Any idea how his may be achieved?

    Reply
    1. james

      correction, I did not realise this was possible via the internal APIs as I didn’t initially notice. Now got it working but not using powercli. I will certainly be having a plat with this after reading your post again. Thanks for sharing.

      Reply
  3. Pingback: PowerCLI study guide – core concepts - The Crazy Consultant

  4. vikrant

    Great Article, you show how to access the entire vR Ops public rest API via PowerCLI .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 The PowerCLI module for vR Ops is fully capable of leveraging the entire vR Ops public API . Now I completely understood the usage and concepts .With the help of this article I can easily create functions and community modules to open up more of the vR Ops functionality via PowerCLI and automate more of our infrastructure. Thanks for sharing . The way you explained each and everything is really great. Thanks once again .

    Reply
  5. Chris Smith

    I would like to get the summary information (or recommended actions) for an alert using PowerCli. I have some specific requirements around generating a CSV file containing actions that need to be taken for VMs and I have not been able to find any sound way of doing it other than copy and paste from each different summary page. This is time consuming and I need to make this happen quickly for an upcoming maintenance window. How can I do this with the REST API?

    Reply

Leave a Reply

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


*