childebrandt42

Understanding VMware AppVolumes 4.x API Using Google Chrome or Microsoft Edge (Credge) Developer tools and using PowerShell to run API calls.

Over the last few years I have been spending a ton of time with the VMware AppVolumes APIs in the 2.x and 4.x builds. An amazing article was written by Chris Halsted (follow him on twitter or @chrisdhalstead ) Link way back in 2015. This is where I started working with the API’s. By no means do I think I’m some Jedi API person. It took me many FAILURES to get and understanding of things, and still fail a ton working through this. I fail more than I succeed, but when it works, I don’t touch it! Keep in mind this stuff is pretty much all I have done is just came up with a problem (AKA: Need to automate AppVolumes stuff) and just figure this stuff out. I am the type of person that learns a ton more if you just point me in the right direction and give me some examples and let me go.  As said I failed a ton but stuck with it and managed to make some amazing things work. Along the way I did have to reach out to Chris Halstead and a few others to help on a few things and he was able to point me in the right directions. So many thanks for the help Chris. So here is my attempt of translating my learning to a blog post.

Now off to the VMware AppVolumes 4.x API’s. As said Chris did an amazing job of covering the 2.x but the 4.x are a bit of a hidden black bag of tricks you have to jump through. So here is the results of many hours of trial and error and a bunch of failures and eventual success. Most of the credit to this flows off Chris Halstead’s hard work. I am taking his layout and just adjusting it with Powershell commands and the Chrome / Edge / Credge interface.

Assumptions: That you have and understanding of what API’s are specifically Rest. You can find more info here. Also you have an understanding of what Chrome or Credge (Microsoft Edge) is and how to use it. If not this blog post will not help you much. Understanding and access to a VMware AppVolumes Environment. And have a understanding of what how to use PowerShell.

For me working with Google Chrome is the easiest thing to work with. Chris Halsted used postman maybe I just don’t understand it enough to feel comfortable with it but I prefer Chrome. Either works as long as you get the results you want. Chrome allows me to see the process as I do it in the WebGui and allows me to decode it, and then work backwards to figure out how to do it in PowerShell or any REST call.

Lets get started! If you open Chrome, browse to the AppVolumes server you can click on the three dots in the upper right, go to More Tools, and then Developer Tools. Or Ctrl+Shift+I.

Once You have Developer mode open find the network tab. This is where I spend a ton of my time. This will show all the web calls of the webpage and allow you to decode how things are happening and learn how to decode the process. Should look like below:

The red button on the left is the Record button and the one next to it is the clear button. They will become your best friends. The other button is the Preserve Log check box. I like to have that on so I can see the whole chain as when things switch from frame to frame or from page to page it clears the log and you have a tendency to miss the thing you are wanting to see.

Now on your AppVolumes Logon screen type your creds and hit log on with developer mode on and preserve log enabled. You will see all kinds of things. But really this does not help you with the logon process but shows you some of the process.

A few things we should cover is RestAPI Methods or Verbs. There are 5 verbs but I have only found we use 3 in AppVolumes, but here are the 5.

POST = Create

GET = Read Data

PUT = Update or replace

PATCH = Partial Update or Modify Data

DELETE = Voodo / Delete (Don’t use unless you are sure!)

There can be some more data found here on Rest Methods.

Launching Session With PowerShell

Well going back to 2015 Chris Halstead posted that in order to start a session with AppVolumes manager via API you needed to follow a few things:

So in PowerShell you would use something like this

Invoke-RestMethod -SessionVariable AppVolSession -Method Post -Uri "https://(AppVolumesServerFQDN)/cv_api/sessions" -Body $AppVolRestCreds

Lets break this command up a bit. Invoke-RestMethod is a built in function of Powershell introduced in 3.0. It allows you to run rest commands directly from powershell. More Info Here!

-SessionVariable = This is the command we are using to save the session cookie. Notice we are not using a defined variable. But it is creating the variable called “AppVolSession” for use going forward. And future commands you just add the $AppVolSession varrible for the -SessionVariable

As we dig into the API viewer in Chrome you will see things displayed a bit different in the URL as it wont include cv_api. That is because by default the URL for Sessions is https://(AppVolumesServerFQDN)/sessions but that will do you no good for doing anything useful with the data. As its being displayed as HTML code.

But if you add the “cv_api” to it, it will change it from HTML to JSON/Text output allowing you to read and parse the data for other automations. So same URL https://(AppVolumesServerFQDN)/cv_api/sessions with the “cv_api” in it will allow you to get JSON data out of it.

URL = https://(AppVolumesServerFQDN)/cv_api/sessions enter your AppVolumes server FQDN and lets see how well it goes.

-Body = Oh wait forgot to tell you about the creds. I found this out the hard way after trial and error a bit. You must use Clear text Username and Password (if someone knows of another way please let me know) so this is what I do typically.

# Get Credentials
$Credentials = Get-Credential
$RESTAPIUser = $Credentials.UserName
$RESTAPIPassword = $Credentials.GetNetworkCredential().password
$AppVolRestCreds = @{
    username = $RESTAPIUser
    password = $RESTAPIPassword
}

This will form the credentials portion of the body correctly and allow you to authenticate session.

Now you can authenticate like below. Once you establish a session cookie it will look like below slowing:

Success

OK

From this point forward you can start doing other things in the AppVolumes Manager as you have an authenticated session cookie saved. If you check the session cooking by typing: $AppVolSession as that was what we used as a variable to save it in it will look something like below:

Getting AppVolumes version with API’s and Powershell

Here is my method. As explained I like the function of Invoke-RestMethod so to get Version data in powershell it would look something like this:

Invoke-RestMethod -WebSession $AppVolSession -Method Get -Uri https://(AppVolumesServerFQDN)/cv_api/version

Notice this time we called the variable “$AppVolSession as we want to use the session cookie, and we did not use the credentials body as we already have an authenticated session. And last thing you notice we switched the Method to “Get”. As we are getting data from the API. For more info on Rest Verbs Look here! Your output should look like below:

Most of the stuff Chris has called out in his blog about this still works today in the 4.x, the core calls work and the 2.x functions work but the 4.x they decided to change a ton of this stuff. And working with PowerShell you can just substitute the URL found in his blog with the Invoke-Reset command used for getting version data. For example Get AD Settings:

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri https://(AppVolumesServerFQDN)/cv_api/ad_settings

But as you see below the format is in JSON so easy way to deal with it is to save the contents to a variable.

Saved contents to variable $ADsettings and Now you can see the data below:

We are just changing the last portion of the URL to reach different things.

Directory Tab

# Get Online Entities
Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri “<a href="https://(AppVolumesServerFQDN)/cv_api/online_entities">https://(AppVolumesServerFQDN)/cv_api/online_entities</a>”

You Know you can take my word these records exist but that is not what this post exist for. Now lets open your AppVolumes URL to Directory and then Online. Now open your developer tab. Then click on the online tab to refresh the page. It should look something like below:

From here on the Developer Tab on the right side click on “Online_Entities” Like below

From here you can see the web details on the rendering of the webpage. Hmmm…… That URL looks a bit like what we are using for our API calls except we are adding “/cv_api” in there.

By paying attention to this you can use Get calls to get all the data in the tabs in the same fashion. Just going to the WebGUI and finding out the URL and just adding the /cv_api page infront of it.

Below is the data in my variable $OnlineEntities.online.records

Now with he short learning out of the way, lets get to figuring out what all the others are. Below is a good list but not all of the API calls.

Get Users

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/users"

Get Computers

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/computers"

Get Groups

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/groups"

Get OUs

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/org_units"

Infrastructure Tab

Get Storage

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/storages"

Get Storage Groups

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/storage_groups"

Get Managed Machines

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/machines"

Inventory Tab

Get AppStack Applications (Products)

Invoke-RestMethod -WebSession $AppVolSession -Method get -Uri "https://(AppVolumesServerFQDN)/cv_api/app_volumes/app_products"

Get Packages

Invoke-RestMethod -WebSession $AppVolSession -Method get -Uri "https://(AppVolumesServerFQDN)/cv_api/packages"

Get Packages with all the data

Invoke-RestMethod -WebSession $AppVolSession -Method get -Uri "https://(AppVolumesServerFQDN)/app_packages?include=app_markers%2Clifecycle_stage%2Cbase_app_package%2Capp_product"

Get Lifecycle Data

Invoke-RestMethod -WebSession $AppVolSession -Method get -Uri "https://(AppVolumesServerFQDN)/cv_api/app_volumes/lifecycle_stages"

Get All 4.x Programs

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/programs"

Get App Assignments

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/app_assignments"

Get App Assignments All the details

Invoke-RestMethod -WebSession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/app_volumes/app_assignments?include=entities,filters,app_package,app_marker&"

Get App Attachments

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/app_attachments"

Get Writable Volumes

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/writeables"

Config Tab

Get License Usage

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/license"

Get Ad Domains

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/domains"

Get AD Domain More info

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/ldap_domains/$DomainID"

Get Administrators

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/administrators"

Get Machine Managers

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/configuration/hypervisor"

Get Storage

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/configuration/storage"

Get Managers

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/configuration/manager_services"

Get Settings

Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/configuration/settings"

Okay lets see if anyone ran into issues. I bet some of you ran into an issue like below:

If you look at the URL in the command you see that “Users” is capital. That is the issue. You must do these things to match case. I think they are all lower case, so when in doubt, make all the case lower case. It will work much better for you. I made this mistake a ton!

Dive into Put and Post

Now that we have covered all the boring Get info stuff lets go off the deep end a start causing damage. Lets head off to the Put and Post world. This where things begin to get interesting.

The variable $GroupID is the ID number of the group you want to import. So if you use the  command from above to get Storage groups put it into a variable this will allow you to parse it. Using something like below:

$StorageGroups = Invoke-RestMethod -Websession $AppVolSession -Method Get -Uri "https://(AppVolumesServerFQDN)/cv_api/storage_groups"

From there you can type $StorageGroups.Storage_Groups and it will tell you all the storage groups with full details. From there you can use  $StorageGroups.storage_groups.id and it will tell you all the storage group ID’s out there. And from there when you now the Group IDs you can do things like Import, Replicate and Rescan.

You can see below the name and ID. AppVolumes calls all the changes via Group ID. As you see my Group ID is “1”

For the examples below $GroupID is the ID of the storage group you want to do something with.

Import from Storage Group

Invoke-RestMethod -Websession $AppVolSession -Method Post -Uri https://(AppVolumesServerFQDN)/storage_groups/$GroupID/import

Replicate Storage Group

Invoke-RestMethod -Websession $AppVolSession -Method Post -Uri "https://(AppVolumesServerFQDN)/storage_groups/$GroupID/replicate"

Rescan

Invoke-RestMethod -Websession $AppVolSession -Method Post -Uri “https://(AppVolumesServerFQDN)/cv_api/storage_groups/$GroupID/rescan”

And if you want to do something with all the storage groups you can throw in my favorite thing the For loop. So example like this:

foreach($GroupID in $StorageGroups.Storage_Groups.ID){

    Invoke-RestMethod -SessionVariable $AppVolSession -Method Post -Uri "https://(AppVolumesServerFQDN)/storage_groups/$GroupID/import"

    Invoke-RestMethod -SessionVariable $AppVolSession -Method Post -Uri "https://(AppVolumesServerFQDN)/storage_groups/$GroupID/Replicate"

    Invoke-RestMethod -SessionVariable $AppVolSession -Method Post -Uri "https://(AppVolumesServerFQDN)/cv_api/datastores/rescan"

}

This will Import, Replicate and Rescan each of the storage groups.

Working with Applications. In working with applications you need to get a bunch of data before you can do things with it. Using your learning from above you need to get things like “Package ID” and “Lifecycle ID”

Get Package Data from Source and Target

$Packages = (Invoke-RestMethod -WebSession $AppVolSession -Method get -Uri "https://( AppVolumesServerFQDN)/app_volumes/app_packages?include=app_markers%2Clifecycle_stage%2Cbase_app_package%2Capp_product").data

Noticed I put “().data” around the command. That is to get your right inside the data subset. If you look at the variable “$Packages” it will hold all the data of your packages. Will look something like below, Notice my package ID is “2”.

Next thing you will need is Lifecycle Data. Really this is the Lifecycle master DB. Yes it changes between versions and is growing.

$Lifecycle = (Invoke-RestMethod -WebSession $AppVolSession -Method get -Uri "https://(AppVolumesServerFQDN)/app_volumes/lifecycle_stages").data

Again going right into the data and saving to a variable.

Below is the base command to set the Lifecycle of any Package.

Set Lifecycle Data

Invoke-RestMethod -WebSession $AppVolSession -Method put -Uri "https://(AppVolumesServerFQDN)/app_volumes/app_packages/$($Package.id)?data%5Blifecycle_stage_id%5D=$($Lifecycle.id)"

But lets take this to my example. I want to set my package “2” to Published. So in order to do that we can do that with variables or with just numbers. Below is the example with variables. Variables work nice when you are want to do many of these things. And if you want to do a huge set just throw it in a for loop.

Below we are setting the Package “7zip” or ID “2” to “Published” that equals “3” in the AppVolumes DB.

$Package = ‘2’
$LifeCyclePublished = ‘3’

Invoke-RestMethod -WebSession $AppVolSession -Method put -Uri "https://(AppVolumesServerFQDN)/app_volumes/app_packages/$($Package.id)?data%5Blifecycle_stage_id%5D=$($LifecyclePublished)"

Now pull the package’s again, and it will show updated Lifecycle Stage ID. Like below:

Now lets take the same Package, And lets set it as current as its our production package. The below command will set it as current.

Set Source Current Status

Invoke-RestMethod -WebSession $AppVolSession -Method put -Uri "https://(AppVolumesServerFQDN)/app_volumes/app_products/$($Package.app_product_id)/app_markers/CURRENT?data%5Bapp_package_id%5D=$($Package.id)"

Well congrats you just set the Package as Current. Now if you Get the package data again you will see something like below: (The Current marker is hidden under the “App_Marker”)

Below is broken out “App Markers”.

Now lets work on the fun mess of Assigning users. This one threw me through a loop for a few hours then it just clicked. It did take some help from Chris. I think the email said something like “Im so confused on assigning a user and can’t make it work. HELP!, can you give me a hint on how to make this work, not the answer!” Something to that extent, as cant find the email anymore. But for assigning users there are some specific data you need. The key parts you need to assign a user are the following:

• App Product ID
• Entities
• Path
• Entity Type
• App Package ID
• App Marker ID

-App Product ID – This comes from the Products. Below is the command to get Products.

Get Product Data from Source and Target

$Products = (Invoke-RestMethod -WebSession $AppVolSession -Method get -Uri "https://$AppVolServer/app_volumes/app_products").data

You will need to use a for loop to get this to a single product. Or you can just use the $Products.ID value. Below is an excerpt of my $Product variable.

-Entities (Who you are assigning and has to match specific form) This is a fun one, but in order to assign a user it HAS to be in this format:

CN=AD User,CN=User,CN=Users,DC=corp,DC=local

Now if you have OU’s you need to add all that fun stuff in there too.

Easy way to see this is to do the assignment with the Development tab open, once you hit complete find the call named “app_addignments” and click on that scroll all the way to the bottom and expand all the stuff under “Request Payload”

It will look something like this:

-Path = Meaning is it a User or Group

-Entity Type – This is either “User” or “Group”

-App Package ID – Can use “null” if you are not assigning to a package ID and just using current. For 90% of the people out there you are not assigning groups or users directly to a Package you are assigning it to the package marked as “Current”. If that is your case you can use “null”.

-App Marker ID – This is the Application Marker ID. This comes from the Packages, and we are just using the value $Package.app_markers.id

Below we are building the Body for the assignment. This is the part that messed me up with the whole thing. Until I realized that in the Developer tab it gave me the answer. If you look at the Payload Break down it gives you the answer. Then you just need to translate it a bit.

From there you build this:

# Assign User to AppStack
$AssignUserOrGroup = “CN=AD User,CN=Users,DC=corp,DC=local”
$EntityType = “Group”
$AssignmentJsonBody = "{""data"":[{""app_product_id"":$($Product.id),""entities"":[{""path"":""$AssignUserOrGroup"",""entity_type"":""$EntityType""}],""app_package_id"":null,""app_marker_id"":$($Package.app_markers.id)}]}"

Now that you have the body built you can assign the user! That part is simple.

Invoke-RestMethod  -WebSession $AppVolSession -Method Post -Uri "https://(AppVolumesServerFQDN)/app_volumes/app_assignments" -Body $AssignmentJsonBody -ContentType 'application/json'

Then to unassign you can just find out the Assignment ID from the commands we covered early and boom. User is unassigned.

Un-assign user to AppStack

Invoke-RestMethod  -WebSession $AppVolSession -Method Post -Uri "https://(AppVolumesServerFQDN)/app_volumes/app_assignments/delete_batch?ids%5B%5D=$($Assignment.id)"

There are many more things that can be accomplished with this. But this is just the start. I hope this helps you to understand how I figured out the API, and how the little things help you going forward. Look for some more blog posts to do with this.