Quick Guide to the Horizon 7 API with VMware PowerCLI

Posted on 03 May 2017 by Ray Heffer

Horizon API module for PowerCLI 6.5 (R1), so I thought I’d share some of my notes on getting started with this incredibly useful new API for Horizon. It is hard to imagine working with any virtualization or cloud technology without adding API functionality into the mix. I use the Dropbox API to store database backups for this very blog. I heavily rely on the API provided by DigitalOcean, who hosts the Linux VPS this blog is running on. After speaking to some of my friends in VMware Professional Services, it suddenly dawned on me how a large part of their day is helping customers use APIs for our products. It has come along in leaps and bounds compared to the older SDKs and APIs available a few years back.

You don’t need to be a coder to take advantage of the Horizon API, but mastering the basics of scripting and API interaction is key to becoming a successful VMware guru!

Let me introduce the super easy guide on getting started with the Horizon API using PowerCLI. Pre-requisites

  • vSphere 5.5 or higher
  • Horizon 7.0.2 or higher
  • PowerCLI 6.5 Release 1
  • A beverage of some kine (coffee is preferred)

Getting started

If you are new to PowerCLI, don’t panic! Here are the basics:

  1. First download and install PowerCLI 6.5 Release 1
  2. Open PowerCLI (as Administrator) and run Set-ExecutionPolicy RemoteSigned so you can execute your scripts:

Set-ExecutionPolicy RemoteSigned

Step 1: Importing the Horizon API Module

Providing you have PowerCLI 6.5 R1 installed, you should also have the new Horizon API module (VMware.VimAutomation.HorizonView). You can check this using the following:

Get-Module –ListAvailable VMware*Horizon*

Next, import the module so we can start using it!

Get-Module –ListAvailable VMware*Horizon* | Import-Module

Notice how the same command was used? By piping the object from the previous command (VMware.VimAutomation.HorizonView) the Import-Module action was taken.

If you already know the name of the module you want to import, you could also run Import-Module VMware.VimAutomation.HorizonView.

Step 2: Establish Connection to Horizon

Now we have the Horizon module imported, we can use the Connect-HVServer cmdlet to establish a connection to the Horizon API service of the Horizon Connection server.

Connect-HVServer -server cs1.domain.local -User user -Password password -Domain domain.local

If it has authenticated successfully you should now have a connection to your Horizon Connection server.

Note: Something I prefer to do is substitute the username, password, domain and Connection server with variables. I will cover that in more detail later (See Using Variables)

Step 3: Listing the Horizon API services with ExtensionData

The Horizon API contains a long list of services we can use, contained in the ExtensionData property. We will add this to a variable $hzServices that we can use in our script.

$hzServices = $Global:DefaultHVServers.ExtensionData

Now enter $hzServices and you’ll see all of the services available with the Horizon API module!

Step 4: Using Get-Member to List Methods and Properties of an Object

Ok, so you can see a bunch of services using the $hzServices variable. Let’s pick one at random and see what we can actually do with it: ConnectionServer

$hvServices.ConnectionServer | Get-Member

Expected Output

Name                    MemberType Definition
----                    ---------- ----------
ConnectionServer_Get    Method     VMware.Hv.ConnectionServerInfo ConnectionServer_Get(VMware.Hv.ConnectionServerId id)
ConnectionServer_List   Method     VMware.Hv.ConnectionServerInfo[] ConnectionServer_List()
ConnectionServer_Update Method     void ConnectionServer_Update(VMware.Hv.ConnectionServerId id, VMware.Hv.MapEntry[...
Equals                  Method     bool Equals(System.Object obj)
GetHashCode             Method     int GetHashCode()
GetType                 Method     type GetType()
ToString                Method     string ToString()
Client                  Property   VMware.Hv.HviClient Client {get;}
MoRef                   Property   VMware.Hv.ManagedObjectReference MoRef {get;}

Note: The Get-Member cmdlet lists the Methods and Properties of an object. In this example our object is ConnectionServer.

Step 5: Let’s try it! – Listing Horizon Connection Servers

Great! We know what we can do with ConnectionServer, now let’s use our example to list the Connection servers in our environment using the ConnectionServer_List method.

$hzServices.ConnectionServer.ConnectionServer_List()

Id                    : VMware.Hv.ConnectionServerId
General               : VMware.Hv.ConnectionServerGeneralData
Authentication        : VMware.Hv.ConnectionServerAuthenticationData
Backup                : VMware.Hv.ConnectionServerBackupData
SecurityServerPairing :
MessageSecurity       : VMware.Hv.ConnectionServerMessageSecurityData

Oh wait! All that did is list some more objects. Actually this is very cool, we can see what our MessageSecurity is set to, or take a look at the backup data. For now, let’s just list our Connection servers, so the General object is worth looking at.

$hzServices.ConnectionServer.ConnectionServer_List().General

Now you should see a list of your Connection servers, along with the Name, ServerAddress, Version and a bunch of other useful data.

Note: In this example we are using our $hzServices variable with the ConnectionServer object and ConnectionServer_List method.

Using Variables

As we drill down into an objects Methods and Properties, your scripts can often benefit from using variables. As you can see in the previous examples, I used $hzServices to store the ExtensionData ($Global:DefaultHVServers.ExtensionData). We can make further use of variables to make our scripts a little easier to work with.

Looking back at Step 5, we could add a variable that contains our Connection servers.

$CServers = $hzServices.ConnectionServer.ConnectionServer_List().General

Now using $CServers on its own will simply list our Connection servers without having to type out the entire command. You can then drill down further. Try $CServers.Name and see what happens!

When working with scripts I also prefer to assign variables to information such as the username, password, domain, and so on.

$hzUser = "Administrator"
$hzPass = "VMware1!"
$hzDomain = "domain.local"
$hzConn = "connect01.domain.local"

Example Script

This basic script takes everything that we have learned here. It retrieves the Horizon usage statistics, which is the same metrics listed under View Configuration > Product Licensing and Usage. Service providers can use this script or incorporate it with their existing scripts to automate the reporting of Horizon usage.

# User Configuration
$hzUser = "Administrator"
$hzPass = "VMware1!"
$hzDomain = "domain.local"
$hzConn = "connect01.domain.local"

# Import the Horizon module
Import-Module VMware.VimAutomation.HorizonView

# Establish connection to Connection Server
$hzServer = Connect-HVServer -server $hzConn -User $hzUser -Password $hzPass -Domain $hzDomain

# Assign a variable to obtain the API Extension Data
$hzServices = $Global:DefaultHVServers.ExtensionData

# Retrieve Connection Server Health metrics
$hzHealth =$hzServices.ConnectionServerHealth.ConnectionServerHealth_List()

# Display ConnectionData (Usage stats)
$hzHealth.ConnectionData

Summary

If you want to learn more, I recommend you head over to GitHub and check out some of the sample PowerCLI scripts, many of which are for Horizon 7, including my script used here. Another useful resource is the VMware API Explorer where you will find the Horizon 7 API reference.

Tagged with: vmware scripts code devops