VI3 SDK programming in PHP – Part 1

Hello fellow programmers 🙂

VMware Infrastructure 3 has as you probably already know a very extensive SDK which allows you to write your own software that can talk to any ESX3 or VirtualCenter 2 server and retrieve information or execute tasks. The SDK is based on a web service that is integrated in the VirtualCenter Server and any ESX Server. The new VI3 SDK is significantly different than the previous SDK. It has much more methods (function calls) and uses a different model to query information.

In this first part we are going to look at how to make a basic connection to VC2 and how to login to the service. To help you setup your own development environment you have 2 options.

1. Install and setup your own PHP environment, running on any OS you prefer and download this nusoap library.
2. Download the VI3 SDK Development Virtual Machine (119MB). This virtual machine runs linux and already has Apache, PHP with the right libraries installed.

Your choice 🙂

In the virtual machine, there is already a sample application that queries all running virtual machines and requests how much free disk space these virtual machines have and displays this information using nice looking pie charts.

Using the nusoap library

To write SOAP you will need the NUSOAP PHP library. This library can take care of creating the needed XML documents and handle the communication between your application and the VirtualCenter Server.

So the first line in your code should include this library. This can be done like this:

< ?php require_once("lib/nusoap.php">;

Creating a connection to your VirtualCenter Server (or ESX server)

One difference between the older SDK and this new VI3 SDK is the port you connect to. In the old SDK (VC1.x) you would make a HTTP or HTTPS connection to port 8443, this port has changed to the default industry standard ports. So for HTTP port 80 and for HTTPS port 443. Instead of using a different port, you will need to connect to a specific web page. For example if we use HTTPS which is by default only enabled you would connect to https://your_VCserver/sdk

So how do you setup this connection in PHP. First we need to create a handle to this connection that we can later use to send our command to. This is done with the following code:

$myconnection = new soapclient(“https://myVCserverIP/sdk”);

This first command after creating the connection is a call to check if we are talking to the right VirtualCenter server environment and also to retrieve the main root path of the data structure. (more on this later on). This command is called “RetrieveServiceContent”. If you read the SDK manual, you will see that it requires one single parameter. This parameter is called “_this” and requires a ManagedObjectReference. It took me a while to understand this concept, but I now think that I have figured out what they mean with this. There are different kinds of information we can request and by specifying the “_this” parameter we are telling it what kind of data structure we think we should get back. In this case the are requesting the data structure type “ServiceInstance”.

One final thing before we can make this first call, I need to explain to you the concept of namespaces. Every call we make we need to specify a namespace. A namespace is just a prefix for all our variable names, this concept is designed to allow multiple services to use the same name of variables, but by using this different prefix (namespace) we can still keep them apart. VMware tells us to use the “vim2” name space when talking to their software.

So what does this now look like in php:


It should provide you with the following result:

SDK Example

Just some extra explanations; Using the $soapmsg[data] means we are creating an array in PHP. Unlike many other languages we do not have to define the array first and we can call our fields what ever we like. The NUSOAP library uses the field name as the XML field name.

Another command we are using here is the “new soapval”, this is not always needed, unless the XML we need to spit out need some special parameter, like in this case it does. It needs to tell that the field “_this” is of the type “ServiceInstance” and that it contains the value “ServiceInstance”.

Not all fields require a specific type to be specified, so we can leave out the “new soapval” command and just define normal variables in an array. See the next example when we login.

Login to the VirtualCenter Environment

So now we have made a connection and we have retrieved some basic information about the VirtualCenter server. As you can see, we did not have to login as any specific user yet. Of course if we would like to start sending command and retrieve information about our Virtual Machine environment we of course need to have the right credentials. To login to the VC environment, the SDK manual tell us to use the command “Login”. It now tells use to specify the following parameters; _this, username, password and optionally the locale (for telling what character set we want to use).

The “_this” parameter this time should be of the type “SessionManager” and should contain the value “SessionManager”. The other parameters are just plain strings and the NUSOAP library will take care of that and therefore do not have to be created with the SOAPVAL command.

So let’s send the login command:

The unset($soapmsg) command just first clears the array, so it does not contain any previous data. When this command is send the results are stored in the $result variable and will most likely be an array (if things went well). To display this array we use the “print_r” command in PHP, it will print out the contents or the array. Around this we stick normal HTML code of an textarea to make it nice and readable, as the array will not contain any HTML code and therefore line breaks will not work.

In the upcoming part II, I will go into how to actually retrieve information and send some basic commands.