Getting Started with Horizon Cloud Service - next-gen Supported REST APIs with PowerShell

Welcome, are you interested in getting started with scripting automation with Horizon Cloud Service - next-gen (HCS-NG)?  If so, then this blog is for you as I will demonstrate how I went about getting started with using the APIs myself.

If you have not yet seen it, a great resource to ensure you bookmark is the current list of supported Rest API’s for Horizon Cloud Service – next-gen.  The guide is updated as new or changed features are added to the platform.

The two core areas we will tackle in this blog are:

·       How do I get authorized to use the REST API’s?

·       How do I run a REST API with an example?

I focused on using PowerShell as this is a widely used scripting language at all my customers and is a great way to ease into automation development with its approachability.

Let’s Get Authorized

One of the main concepts I had to understand before I started building my automation is that I first needed to be authorized to be able to communicate with the HCS-NG service at all and ask it to do things on my behalf.

Looking through details in Identity and Access Management - Cloud Services Platform, we provide examples using Curl, but that did not translate into something useful to me as the automation I wanted to develop would be with PowerShell, not Curl.  I found that getting an authorization to the HCS-NG service is quite easy.

Authorization is a way to prove to the system that I have the appropriate credentials and entitlement to talk to the service and leverage the REST API.  This Authorization comes from the VMware Cloud Services platform (CSP) which manages your identity and access to the VMware Cloud services portfolio across hybrid and native public clouds. You use the Cloud Services Console to login to all of your VMware Cloud Services, including Horizon Cloud Service – next-gen.

For scripting purposes, CSP provides a mechanism to get an Authorization called a CSP Authorization Token (also known as an API Token).

You will need to generate an API Token within CSP for your account.  I followed the process outlined on our Developer documentation: VMware Cloud Services Platform Authorization using API Token.

During the API Token generation, I wanted to also limit the scope of my API token to be as minimal as possible and to do this I aligned the role assigned to it to be the same as what we document in Use the VMware Cloud Services Console to Assign Roles

I typed ‘horizon’ in the search box, expanded Workspace ONE, expanded Horizon Cloud Service, and selected Administrator service role.

Proceeding through the rest of the wizard generates a token for scripting purposes like I used.

With an API Token generated, I had the necessary data I needed to authorize me to the CSP through my script.  Once authorized by the service, I am allowed to run any REST API that the HCS-NG service provides.  Each time the script runs, it will re-authenticate and authorize to allow it to do the work set out for it in the script code.  

Let’s see the code I wrote in PowerShell ISE to get that authorization in PowerShell.  If you are not familiar with writing and running PowerShell code, please check out How to Write and Run Scripts in the Windows PowerShell ISE for Windows based guest OS.  If your using a Mac, you can use Visual Studio Code as an example IDE for PowerShell script editing and use Installing PowerShell on macOS for running PowerShell scripts on Mac.

param($apiToken = "YOUR_SAVED_API_TOKEN_HERE")
$jsonOutput = @()
$cspAuthUri = "https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize"
$cspAuthJSON = "refresh_token=" + $apiToken
$accessToken = @()
try {
    $jsonOutput = Invoke-RestMethod -Uri $cspAuthUri -Method Post -ContentType "application/x-www-form-urlencoded" -Body $cspAuthJSON
    if ($jsonOutput.access_token) {
        $accessToken = $jsonOutput.access_token
        Write-Host "Successfully Authorized!!!"
    }
} catch {
    Write-Host "ERROR: Could not get authorized:" $Error[0].Exception.Message
}

When I run the example code, I see the following in the PowerShell console which indicates a successful authorization from CSP.

If this script failed to authenticate, the most common issue would be an incorrect value in the ‘apiToken’ variable such as a mis-typed token value, or an extra space character on the end, you just need to be careful to copy the value as it is with no extra characters, special characters or spaces, on the end.

To dig in a little further into the script code above, this script obtains an Authorization from CSP using the API token you configure in the ‘apiToken’ variable in the 1^st line against the CSP REST API for Authorization.

As documented in the Developer site, this REST API is of a ‘POST’ type and requires a small piece of data to be submitted with it which I generate in the ‘cspAuthJSON’ variable. 

Please Note – Be careful whether a PUT or POST type is specified for an API.  Failure to use the correct one will result in a failed REST API trigger if the wrong type is used (a PUT when a POST is required or vice versa).

I leveraged the PowerShell ‘Invoke-RestMethod’ to trigger the REST API (-Uri $cspAuthUri), with the API Token passed to the REST API in the format it needed it in (-Body $cspAuthJSON), and I specified it as the POST type (-Method Post).  The PowerShell Method REST API response I receive back from the CSP service is stored in the ‘jsonOutput’ variable.

The script checks the ‘jsonOutput’ variable response data to see if it received a ‘access_token’.  If it does have one that means the authorization was successful, and then it saves this authorization into a variable called ‘accessToken’.  The authorization is stored in the ‘accessToken’ variable and is used to provide the REST API service of HCS-NG proof of authorization so I can run any API. 

Ready, Set, Go!

So, I have my authorization, how do I use it to do something in HCS-NG REST API? Let’s look!

$getPoolsUri = "https://cloud.vmwarehorizon.com/portal/v2/pools"
$pools = @()
try {
    $pools = Invoke-RestMethod -Uri $getPoolsUri -Method Get -Headers @{ 'Accept' = 'application/json, text/plain, */*' ; 'Authorization' = 'Bearer ' + $accessToken}
    if ($pools.content) {
        foreach ($pool in $pools.content) {
            Write-Host "Pool Name:" $pool.name "| Display Name:" $pool.displayName "| Type:" $pool.templateType
        }
    }
} catch {
    Write-Host "ERROR: Could not get the pools:" $Error[0].Exception.Message -ForegroundColor Red
}

When I run the script code from both examples together, I get a list of pools currently in my lab environment.

The example code in the table uses the HCS-NG REST API for Get All Pools is used to build what you can see in the Desktops & Applications section of Universal Console.

This API is of a GET type  and it provides a response in JSON format of a data structure called PagePool.

The code runs the ‘Invoke-RestMethod’ to trigger the REST API (-Uri $getPoolsUri) with a GET type (-Method Get) and in specific it submits headers which are required as this is how I provide that Authorization I previously obtained from CSP in the earlier code (-Headers @{ 'Accept' = 'application/json, text/plain, */*' ; 'Authorization' = 'Bearer ' + $accessToken}).

The header is built with the previous Authorization I received from CSP with the ‘Authorization’ header.  An additional ‘Accept’ header is specified to tell the service what format I need the response data format back in which is the format that the service supports, in this case ‘application/json, text/plain, */*’.

Please Note – Be careful to use the correct ‘Accept’ header values for the REST API you are using as incorrect settings can cause a REST API failure.  Generally, ‘application/json’ or ‘application/json, text/plain, */*’ are usually standard types that I like to try if I am not sure and do not see it documented.

If you want to re-use this code, for any additional APIs you run with your own automation you develop, you will need to ensure you add the Headers content in the example given (adjusting the ‘Accept’ header value if necessary) and you will be able to run any REST APIs that you need against the HCS-NG service.

What’s Next?

Now you know how I learned to utilize the HCS-NG REST API in PowerShell.  Hopefully this example will provide you a starting point to start developing your own automation for HCS-NG with PowerShell.

There are plenty of exciting automation opportunities at your fingertips and I encourage you to explore and be creative with what you can build to help save you time with operational processes, minimize human element issues, and help you evolve your organization on its Digital Workspace journey. 

Keep an eye on our Digital Workspace Tech Zone Blog RSS and follow us on Twitter @EUCTechZone to stay in the loop on latest EUC content.