How to interact with the Cloud Director REST API using PowerShell and Python
Pre Work
Useful Links
You can find the schema reference for version 34.0 of the Cloud Director API here:
https://code.vmware.com/apis/912/vmware-cloud-director
PowerShell
With PowerShell, you'll need v3 or higher. To check this, open PowerShell and enter $psversiontable
at the prompt. You should see something like the following:
If PSVersion
is less than 3.0, you'll need to upgrade. The v4 package is available here: https://www.microsoft.com/en-gb/download/details.aspx?id=40855.
Python
Install Python 3.10: https://www.python.org/downloads
Then, install the package: https://pypi.org/project/requests/
You can check your version of Python and whether the requests package is installed by typing the following commands:
Getting your credentials
The first thing you'll need to do is log in to the Portal and get your API credentials:
Select API from the menu on the top right, you'll then get all of the credentials for each of the Cloud Director organisations that you have access to. Note down the API URL and API Username for the organisation you want to interact with.
For more detailed instructions, see How to access VMware Cloud Director through the Cloud Director API.
Getting Started
PowerShell
Copy and paste the following script into a .psm1 file:
$Global:SkyscapeURL = "https://<api-url>/api" $Global:Authorization = "" $Global:Accept = "application/*+xml;version=34.0" $Global:xvCloudAuthorization = "" Function New-vCloudLogin($Username,$Password) { $Pair = "$($Username):$($Password)" $Bytes = [System.Text.Encoding]::ASCII.GetBytes($Pair) $Base64 = [System.Convert]::ToBase64String($Bytes) $Global:Authorization = "Basic $base64" $headers = @{ Authorization = $Global:Authorization; Accept = $Global:Accept} $Res = Invoke-WebRequest -Method Post -Headers $headers -Uri "$($Global:SkyscapeURL)/sessions" $Global:xvCloudAuthorization = $res.headers["x-vcloud-authorization"].tostring() } Function Get-vCloudRequest($EndPoint) { $headers = @{"Accept" = $Global:Accept; "x-vcloud-authorization" = $Global:xvCloudAuthorization} [xml]$Response = Invoke-WebRequest -Method Get -Headers $headers -Uri "$($Global:SkyscapeURL)/$EndPoint" Return $Response }
You'll now have two new functions available to you;
New-vCloudLogin
andGet-vCloudRequest
.In a new PowerShell window, run the following command to import the file:
Import-Module <Path to .psm1 file>
To log in enter:
New-vCloudLogin –Username "myuser@org" –Password "yourportalpassword"
Use the username that you copied from the Portal earlier and your Portal password. This will log in to Cloud Director and add your authorisation header to a global variable for use in the next function:
$VMS = Get-vCloudRequest –EndPoint "query?type=vm"
This will get the first 25 VMs in your Org and store them in
$VMS
as an XML output, which you can inspect or export as you want.
Other examples
$VMS = Get-vCloudRequest –EndPoint "query?type=vm&pageSize=128"
Returns 128 VMs rather than 25
$VMS = Get-vCloudRequest –EndPoint "query?type=vm&page=2"
Returns the second page of 25 VMs
$VAPPS = Get-vCloudRequest –EndPoint "query?type=vApp"
Returns the first 25 vApps in an Org
$VDC = Get-vCloudRequest –EndPoint "query?type=orgVdc"
Returns the first 25 VDCs in an Org
Python
Save the following into a file, for example:
c:\vcloud_demo.py
:import base64 import requests SkyscapeURL = "https://<api-url>/api" Authorization = "" Accept = "application/*+xml;version=34.0" xvCloudAuthorization = "" def New_vCloudLogin(username,password): global Authorization global Accept global SkyscapeURL global xvCloudAuthorization Pair = "{username}:{password}".format(username=username,password=password) {{EncodedPair }}= base64.b64encode(Pair.encode('utf-8')).decode() Authorization = "Basic %s" % str(EncodedPair) apiheaders = {"Authorization" : Authorization, "Accept" : Accept} res = requests.post(SkyscapeURL + '/sessions',headers=apiheaders, verify=False) xvCloudAuthorization = res.headers['x-vcloud-authorization'] def Get_vCloudRequest(endpoint): global Authorization global Accept global SkyscapeURL global xvCloudAuthorization apiheaders = {"Accept" : Accept, "x-vcloud-authorization" : xvCloudAuthorization} res = requests.get(SkyscapeURL + '/' + endpoint,headers=apiheaders, verify=False) return (res.content) # login to Cloud Director New_vCloudLogin("user@org","mypassword") # demo query, get all VMs and print them to screen data = Get_vCloudRequest("query?type=vm") print data
Now, click Start and enter
cmd
. This will bring up a command prompt.You can run this script by entering:
C:\python310\python.exe c:\vcloud_demo.py
The above example will log you into Cloud Director and return an XML representation of the first 25 VMs in your VDC. You can adjust the script to use the same parameters as the examples in the PowerShell script above.
Feedback
If you find a problem with this article, click Improve this Doc to make the change yourself or raise an issue in GitHub. If you have an idea for how we could improve any of our services, send an email to feedback@ukcloud.com.