I needed to update a few bits of information for the networks in my on-prem Aria Automation deployment.  It would have been pretty easy to update via the GUI.  I thought this was a great opportunity to start learning about using Aria Automation APIs with PowerShell.

I thought I would share what I found to hopefully help someone new to APIs. This could also be useful if someone needed to make these changes in bulk.    Let’s take a look!

Figuring things out

I started by reviewing the Aria Automation API Documentation (also known as the Swagger UI) built into each vRA install (in your environment go to https://your-vra-fqdn.com/automation-us/api/docs).

The Swagger UI will help describe how to use the APIs and even provides an interface to test them out.

Under the Infrastructure As A Service category, I found APIs for Cloud Accounts.

Once the proper API call is known, you can turn your attention to how to make the call and get data back.  I like using Postman for modeling and testing:

• It gives me the ability to save collections of API calls so I can re-use them
• Using the editor I can determine the correct format for the API call and input
• The output window makes it easy to understand how the data returned will be formatted

Using the Cloud Accounts API call details from Swagger, I was able to construct the call in Postman and see what data was returned.  The top half describes the API call and the bottom half shows the return after the API call was sent.

Having this info helps me understand what data structures are returned from the API call. I can now start to craft some PowerShell around it

Writing PowerShell Code to interact with APIs

PowerShell does include cmdlets to interact with APIs – check out invoke-rest method.   These work but can be complicated.  Using the Cloud Account use case and the native PowerShell invoke-rest method:

#Grab the bearer token for use with invoke-restmethod (which is needed for queries with more than 100 results)
$APItoken= $vRA.token | ConvertTo-SecureString -AsPlainText -Force

$Body = @{
    '$top' = $QueryLimit
}
$APIparams = @{
    Method = "GET"
    Uri = "https://$vRAServer/iaas/api/cloud-accounts"
    Authentication = "Bearer"
    Token = $APItoken
    Body = $Body
}

try{
    $CloudAccounts = (Invoke-RestMethod @APIparams -SkipCertificateCheck).Content
} catch {
    Write-Host $("    Unable to get Cloud Accounts from Aria Automation")
    Write-Host $Error
    Write-Host $Error[0].Exception.GetType().FullName
}

Write-Host "Cloud Accounts found - " $CloudAccounts.Count

In the case of Aria Automation, there is a project called PowervRA (project page / documentation).  The cmdlets provided by PowervRA can make it much easier to automate Aria Operation from PowerShell. It vastly simplifies the process of authenticating and making the necessary API calls.

Using our Cloud Account example from earlier, I can connect to Aria Automation, and return all configured Cloud Accounts in just a couple of lines of traditional PowerShell code

Shoutout to the PowervRA Team

I wanted to take a moment and give the maintainers of the PowervRA project some thanks.  This group of people volunteer their time to work on code that many use and benefit from. This is a community project and not sponsored by VMware or any other company.   This is difficult work that is probably not the job paying their bills. This project started in earlier versions of the product and had to pivot hard when the product went through a major roadmap shift that had drastic impact to its APIs.

I wouldn’t have had the courage to try much of my recent work had it not been for their efforts.  If you look at my recent projects, you will notice I have been writing a lot on using PowerShell to automate Aria Automation.    My understanding and code have evolved over the past few months. There are two things I would share:

• Be sure to read the correct version of PowervRA  and its documentation (project page / documentation).   It was not clear to me initially and I wasted some time.  you will want to look at  versions past 4.0 as those have been updated to work with the new APIs in Aria Automation 8.x.
• Don’t be afraid to use what works.  I use a bit of everything in my code  – from native invoke-restmethod, to PowervRA’s cmdlet to connect to vRA (connect-vraserver) to the PowervRA invoke-vrarestmethod so I can access APIs that do not yet have a cmdlet.