Citrix have opened a tech preview for the new REST API for the Citrix Virtual Apps and Desktop Service, and I am excited to start using this. Why you ask? Well, for the simple fact that this is going to make automation with CVADS a heck of a lot easier. Up until now, the only way that you could programmatically interact with the service was using the Remote PowerShell SDK. Yes, there is also the Monitor Service OData API but that is just for reading information. Now don’t get me wrong, the PowerShell SDK has great functionality that allows you to do a lot of things within the service, the problem is that it doesn’t integrate with other programming languages easily, having to call PowerShell isn’t very elegant. Using a REST API means that it doesn’t care what language you are using, if you can do HTTP requests, you can interact with the service. This means that you can use whatever you prefer and are most comfortable with, be that PowerShell, Python or my personal favourite C#.
In the example I am going to show here, I will use PowerShell as it is the easiest way to see and learn how to do the web requests. Just like the Remote PowerShell SDK, you will need to generate a secure client with a client ID and secret. You can find details of how to do that here.
Once you have those, you can then proceed to generate a bearer token. In the code snippet shown below, I create variables for both the client ID and secret. I need to specify a URL for submitting the token request to. I am using the URL that will work for any region, however there are local URL’s that can be used for the EU and APAC regions. Simply change api-us.cloud.com to api-eu.cloud.com for EU, or api-ap-s.cloud.com for Asia Pacific South.
We are ready to submit our web request and the result is then saved to a variable called $response.
After the commend has completed, we can review the contents of the response variable and we can see firstly that it returned a status code 200 which means the request was a success. What we really care about though is the Content section which contains the actual token that we are looking for.
This is in JSON format so we can then take this and convert it into another variable that we can use with greater ease. This is done using the following.
We now have a token to use for our web requests to the CVAD Service and it is valid for one hour. The next thing that we need to get before we can start doing that however is our site ID. To get the site ID we will need not just the access token that we have generated but we will also need our customer ID. This is shown on the API Access tab under the Identity and Access Management page in the Citrix Cloud management console. It is not the Org ID that shows in the top right-hand corner of the console, people often get them mixed up.
First, I put the access token from our $token variable into its own variable called $bearerToken simply just to make it easier to put in to the $headers. We build out the rest of the required information as shown and then invoke the web request.
Just like when we were generating the token, the response come back with a status code of 200 meaning it was successful and the information that we want to view is in the Content section in JSON format.
We can get the site ID to show using the following code. It’s the longer one on the right.
Now we have everything that we need to start working with the CVAD Service. The example that I am going to show here is how we can get the machine catalogs for the site.
The format is that exact same as the one that we used for getting the site ID, the only difference is that we are using a different URI. This is where the site ID is used, and it is inserted into the URI. The format is:
https://api.cloud.com/cvadapis/{siteid}/MachineCatalogs
Just like before, the response comes with a 200 success code and all of the catalog information that we wanted is contained in the Content section, again in JSON.
We can take this then and format it for easy viewing.
You can manipulate these results like you would if you were using the Remote PowerShell SDK and extract whatever information you require from them. I put them in to a variable $machineCatalogs simply to make it easier to follow.
Hopefully this will help you to get started on your first usage of the new REST API for the Citrix Virtual Apps and Desktops Service. I’ll have more examples over the next couple of posts on how we can start to perform actions in the site.
Any questions, please ask!