Invoke-vCloud PowerShell Module

Several of the posts on here and many of the internal PowerShell projects I use at work require direct interaction with the vCloud Director REST API. Usually this is because features exposed in the API aren't yet directly implemented as PowerCLI cmdlets. A good example would be the modules I wrote to allow manipulation of independent disks with vCD VMs here: Independent Disks in vCloud via PowerCLI.

As I wrote more and more scripts that require interaction with the vCD API I started to develop a generic function to allow easier interaction with it. I'm intending in future to use this as the basis for future scripts requiring this functionality which should be useful in keeping the script size smaller and provide an easier method of interacting with the API.

PowerShell has a built-in 'Invoke-RestMethod' call which submits a REST request and gathers any responses, but there are a variety of additional parameters required in a typical vCD API call which this method doesn't know about and which need to be supplied with each call. Wrapping Invoke-RestMethod in a function allows us to much more easily consume the API and makes handling calls which return a long-running task much easier to handle by giving the option to return immediately or to wait for the complete interaction to complete before returning.

Typically to call the API we need to provide the following:

In addition to these, I've also included a flag 'WaitforTask' which can either be true or false. If set to 'true' and if the result of the API call is a 'Task' object reference then the script will monitor the task and wait until it has completed (or timeout exceeded) and then return the task status to our script. This can be useful for operations that can take considerable time when it doesn't make sense for your script to continue until the previous action has been completed - e.g. cloning a new vApp and then modifying it's network settings.

I was keen to explore using Microsoft's PowerShell Gallery as a mechanism to distribute modules, this should make it easier to be able to use these modules and functions wherever needed by simply importing the module as required. The process to make a module available in the gallery is reasonably straightforward and documented on the site, but basically once you've signed up and got an API key you simply call Publish-Module and provide the path to your module code and manifest including your API key as an identifier.

So I'm pleased to announce that the initial release version of my Invoke-vCloud module is now available from the PowerShell Gallery and can be included in any scripts using:

1Install-Module -Name Invoke-vCloud -Scope CurrentUser

It can also be downloaded/inspected using:

1Save-Module -Name Invoke-vCloud -Path <path>

Of course if running an administrative PowerShell instance it can also be installed for all users on the system using:

1Install-Module -Name Invoke-vCloud

Once installed, it can be used in your scripts by specifying the required URI parameter and any optional specifications:

1PS C:\> Invoke-vCloud -URI https://my.cloud.com/api/org
2
3xml OrgList
4--- -------
5version="1.0" encoding="UTF-8" OrgList

You will either need to have an existing PowerCLI vCloud session (Connect-CIServer), or have an x-vcloud-authorization token for a valid/authenticated session which you can pass to Invoke-vCloud using the -vCloudToken parameter.

I've included parameter descriptions in the module to assist which can be viewed using the Get-Help cmdlet:

 1PS C:\> Get-Help Invoke-vCloud -detailed
 2
 3NAME
 4    Invoke-vCloud
 5
 6SYNOPSIS
 7    Provides a wrapper for Invoke-RestMethod for vCloud Director API calls
 8
 9
10SYNTAX
11    Invoke-vCloud [-URI]  [[-ContentType] ] [[-Method] ] [[-ApiVersion] ] [[-Body] ] [[-Timeout] ] [[-WaitForTask] ] [[-vCloudToken] ] []
12
13
14DESCRIPTION
15    Invoke-vCloud provides an easy to use interface to the vCloud Director
16    API and provides sensible defaults for many parameters. It wraps the native
17    PowerShell Invoke-RestMethod cmdlet.
18
19
20PARAMETERS
21    -URI 
22        A mandatory parameter which provides the API URI to be accessed.
23
24    -ContentType 
25        An optional parameter which provides the ContentType of any submitted data.
26
27    -Method 
28        An optional parameter to specify the HTML verb to be used (GET, PUT, POST or
29        DELETE). Defaults to 'GET' if not specified.
30
31    -ApiVersion 
32        An optional parameter to specify the API version to be used for the call.
33        Defaults to '27.0' if not specified which is the API version for vCloud
34        Director v8.20.
35
36    -Body 
37        An optional parameter which specifies XML body to be submitted to the API
38        (usually for a PUT or POST action).
39
40    -Timeout 
41        An optional parameter which specifies the time (in seconds) to wait for an API
42        call to complete. Defaults to 40 seconds if not specified.
43
44    -WaitForTask 
45        If the API call we submit results in a Task object indicating an asynchronous
46        vCloud task, should we wait for this to complete before returning? Defaults to
47        $false.
48
49    -vCloudToken 
50        An alternative method of passing a session token to Invoke-vCloud if there is
51        no current PowerCLI session established to a vCloud endpoint. The session must
52        have already been established and be still valid (not timed-out). The value
53        supplied is copied to the 'x-vcloud-authorization' header value in API calls.

I have some new scripts in development against some of the new features in the recently announced vCloud Director v9 which I'm intending to use this module for and will post as soon as v9 is released.

As always I welcome any comments and suggestions for improving this module.

Jon.