Invoke-vCloud.psm1

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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
## Invoke-vCloud.psm1 - Wrapper for Invoke-RestMethod for consuming VMware vCloud Director API

# Main function to interact with the vCloud Director REST API from within PowerShell
# Note: Does not require PowerCLI, but without it you'll need to specify a valid x-vcloud-authorization token to authenticate
# against the vCloud API.

Function Invoke-vCloud(
[Parameter(Mandatory=$true)][uri]$URI,      # We must specify the API endpoint
[string]$ContentType,                       # Optional ContentType for returned XML
[string]$Method = 'GET',                    # HTTP verb to use (default 'GET')
[string]$ApiVersion = '27.0',               # vCloud Director API version (default to vCD 8.20 - version 27.0)
[string]$Body,                              # Any body document to be submitted to the API
[int]$Timeout = 40,                         # Timeout in seconds to wait for API response (by default)
[boolean]$WaitForTask = $false,             # Should we wait for task completion if reponse includes a task href?
[string]$vCloudToken                        # If not already authenticated using Connect-CIServer (PowerCLI) allow us to specify a token
)
{
<#
.SYNOPSIS
Provides a wrapper for Invoke-RestMethod for vCloud Director API calls
.DESCRIPTION
Invoke-vCloud provides an easy to use interface to the vCloud Director
API and provides sensible defaults for many parameters. It wraps the native
PowerShell Invoke-RestMethod cmdlet.
.PARAMETER URI
A mandatory parameter which provides the API URI to be accessed.
.PARAMETER ContentType
An optional parameter which provides the ContentType of any submitted data.
.PARAMETER Method
An optional parameter to specify the HTML verb to be used (GET, PUT, POST or
DELETE). Defaults to 'GET' if not specified.
.PARAMETER ApiVersion
An optional parameter to specify the API version to be used for the call.
Defaults to '27.0' if not specified which is the API version for vCloud
Director v8.20.
.PARAMETER Body
An optional parameter which specifies XML body to be submitted to the API
(usually for a PUT or POST action).
.PARAMETER Timeout
An optional parameter which specifies the time (in seconds) to wait for an API
call to complete. Defaults to 40 seconds if not specified.
.PARAMETER WaitForTask
If the API call we submit results in a Task object indicating an asynchronous
vCloud task, should we wait for this to complete before returning? Defaults to
$false.
.PARAMETER vCloudToken
An alternative method of passing a session token to Invoke-vCloud if there is
no current PowerCLI session established to a vCloud endpoint. The session must
have already been established and be still valid (not timed-out). The value
supplied is copied to the 'x-vcloud-authorization' header value in API calls.
.OUTPUTS
An XML document returned from the vCloud API (if not waiting for task), or a
success/failure indication if waiting for a task to complete.
.EXAMPLE
Returns list of Organizations to which my current vCloud Session has access
> $orgs = Invoke-vCloud -URI https://my.cloud.com/api/org
> $orgs.InnerXML
<?xml version="1.0" encoding="UTF-8"?>
<OrgList xmlns="http://www.vmware.com/vcloud/v1.5" href="https://my.cloud.com/api/org/" type="application/vnd.vmware.vcloud.orgList+xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1.5 http://my.cloud.com/api/v1.5/schema/master.xsd">
    <Org href="https://my.cloud.com/api/org/6f14c081-3728-4918-a5cc-bb756452f485" name="MyDemoOrg" type="application/vnd.vmware.vcloud.org+xml" />
</OrgList>
.NOTES
You must either have an existing PowerCLI connection to vCloud Director
(Connect-CIServer) in your current PowerShell session, or provide a valid token
(using the -vCloudToken parameter) in order to authenticate against the API for
calls to suceed.
#>

    $mySessionID = ($Global:DefaultCIServers | Where-Object { $_.Name -eq $URI.Host }).SessionID
    if (!$mySessionID) {                    # If we didn't find an existing PowerCLI session for our URI
        if ($vCloudToken) {                 # But we have been passed a x-vcloud-authorization token, use that
            $mySessionID = $vCloudToken
        } else {                            # Otherwise we have no authentication mechanism available so quit
            Write-Error ("No existing session found and no vCloudToken specified, cannot authenticate, exiting.")
            Return
        }
    } # $mySessionID not set

    # If ContentType or Body are not specified, remove the variable definitions so they won't get passed to Invoke-RestMethod:
    if (!$ContentType) { Remove-Variable ContentType }
    if (!$Body) { Remove-Variable Body }

    # Configure HTTP headers for this request:
    $Headers = @{ "x-vcloud-authorization" = $mySessionID; "Accept" = 'application/*+xml;version=' + $ApiVersion }

    # Submit API request:
    Try {
        [xml]$response = Invoke-RestMethod -Method $Method -Uri $URI -Headers $Headers -Body $Body -ContentType $ContentType -TimeoutSec $Timeout
    }
    Catch {                                 # Something went wrong, so return error information and exit:
        Write-Warning ("Invoke-vCloud Exception: $($_.Exception.Message)")
        if ( $_.Exception.ItemName ) { Write-Warning ("Failed Item: $($_.Exception.ItemName)") }
        Return
    }

    if ($WaitForTask) {                     # If we've requested to wait for the task to complete
        if ($response.Task.href) {          # and we have a task href in the document returned

            Write-Host ("Task submitted successfully, waiting for result")
            Write-Host ("q=queued, P=pre-running, .=Task Running:")

            while($timeout -gt 0) {
                $taskxml = Invoke-RestMethod -Uri $response.Task.href -Method 'Get' -Headers $Headers -TimeoutSec 5        # Get/refresh our task status
                switch ($taskxml.Task.status) {
                    "success" { Write-Host " "; Write-Host "Task completed successfully"; return $true; break }
                    "running" { Write-Host -NoNewline "." }
                    "error" { Write-Host " "; Write-Warning "Error running task"; return $false; break }
                    "canceled" { Write-Host " "; Write-Warning "Task was cancelled"; return $false; break }
                    "aborted" { Write-Host " "; Write-Warning "Task was aborted"; return $false; break }
                    "queued" { Write-Host -NoNewline "q" }
                    "preRunning" { Write-Host -NoNewline "P" }
                } # switch on current task status
                $timeout -= 1                                           # Decrease our timeout
                Start-Sleep -s 1                                        # Pause 1 second
            } # Timeout expired
            Write-Warning "Task timeout reached (task may still be in progress)"
            return $false
        } else {
            Write-Warning 'Wait for task requested, but no task returned by vCloud API'
        }
    } # WaitForTask

    # Return API response to caller
    Return $response

} # Invoke-vCloud Function end

# Export function from module
Export-ModuleMember -Function Invoke-vCloud