posted by C.J. Taylor
VMWare has provided several SDKs for vCloud API. The API documentation is mainly beneficial to a lower level of coding or reference. For Java, .NET and PHP however the documentation and support is much greater. The examples provided below are using the PHP SDK. Comprehensive guidelines on the objects that are used to prepare requests and process responses can be found in the documentation that comes with your SDK. Additionally, there’s an HTML based REST guide for the API that I often found a bit more useful than the pdf.
Let’s retrieve information starting with an organization’s data centers drilling down to a VM.
First, I’m creating a class to handle some calls we’re going to make regularly throughout this demo.
- Define connection/authentication parameters.
- Create a method we’ll use in subsequent methods that authenticates us with vCloud and returns the http client object. For more information on the Service SDK object, see the PHP SDK docs on our API page.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
|
class
vCloudWrap {
//authentication information
static
$host
=
"vcloud.caro.net/org/caroCloud"
;
static
$user
= “user@vApp Author";
static
$pass
=
"myPass"
;
//simpleton design pattern for service SDK
static
$client
= NULL;
//retrieve authorized service sdk
public
static
function
getService() {
if
(self::
$serviceObj
!= null) {
return
self::
$serviceObj
;
}
$auth
=
array
(
'username'
=>self::
$user
,
'password'
=>self::
$pass
);
$httpConfig
=
array
(
'ssl_verify_peer'
=>false,
'ssl_verify_host'
=>false
);
try
{
self::
$serviceObj
= VMware_VCloud_SDK_Service::getService();
self::
$serviceObj
->login(self::
$host
,
$auth
,
$httpConfig
);
}
catch
(Exception
$e
) {
//your exception routine here.
}
return
self::
$serviceObj
;
}
}
?>
|
Now that we have some of the redundancy out of the way, let’s start digging. A very practical explanation of Vcloud’s layering or container system is: organization->VDC->VApp->VM. As a Vapp Author we already know the name of the organization.
Let’s start in establishing that Organization SDK object to use in subsequent calls by adding this to our wrapper class.
|
1
2
3
4
5
6
|
public
static
function
getOrganization() {
$service
= self::getService();
$orgsRefs
=
$service
->getOrgRefs(
'myOrg'
);
$sdkOrg
=
$service
->createSDKObj(
$orgsRefs
[0]);
return
$sdkOrg
;
}
|
Now we add a routine to pull in our VDCs (virtual datacenters). This will be a list of all VDCs found withing the organization.
|
1
2
3
4
|
public
static
function
getVDCs() {
$sdkOrg
= self::getOrganization();
return
$sdkOrg
->getVdcs();
}
|
Next we add a routine that will retrieve all the Vapps in our selected datacenter. For clarity, I’m simply going to use the first item returned by the getVDCs method. Most list items can be retrieved by their objects or references.
Requesting a list of objects can get very large in memory quickly since these SDK objects are significant in size. But we can use references for quick portability and using a single reference at a time to create a single SDK object or reference object. In my initial development, my php script choked from memory allocation at around only 30-40 vApps! I highly recommend using references anytime you anticipate a list of any respectable size to be returned. Let’s do that here.
|
1
2
3
4
5
6
|
public
function
getVappRefs() {
$service
= self::getService();
$vdcs
= self::getVDCs();
$vdc
=
$vdcs
[0];
return
$vdc
->getVappRefs();
}
|
To use refs efficiently let’s add a utility method to our class that will retrieve SDKs based on the ref value.
|
1
2
3
4
5
6
7
8
|
public
static
function
getSDKByRef(
$ref
) {
if
(!method_exists(
$ref
,
'get_href'
)) {
//throw a custom exception
return
NULL;
}
$service
= self::getService();
return
$service
->createSDKObj(
$ref
->get_href());
}
|
And, we’ll pull it all together to retrieve the VMs from the first Vapp we receive from the list. Use something like the following outside of the class to call what’s been constructed.
|
1
2
3
4
5
|
$service
= vCloudWrap::getService();
$vappRefs
=
$service
->getVappRefs();
$vappSDK
= vCloudWrapp::getSDKByRef(
$vappRefs
[0]);
//get VMs contained in Vapp:
$vmRefs
=
$vappSDK
->getContainedVmRefs();
|
If you’re following the html docs that come along with the SDK while studying this article, you should be getting pretty familiar with some of the main objects as well as how the SDK uses reference objects which can provide granular specific data related to what the object represents: Vapp, VM, VDC, Organization, User, Catalog Items are to name a few.
This article also only covered getting data. Modifying items such as a Vapp or VM can also be done by these same objects. Such methods are typically prepended with “modify” (e.g., modifyNetworkConfigSettings()).
For more information on api operations or links to the most current copies of VMware’s documentation, please check out our API page.
Hope this was helpful. Feel free to ask questions in the comments!
CJ
Reference Links
- Vcloud SDK for PHP
- vCloud SDK for Java
- vCloud SDK for .NET