Getting started with vCenter server REST APIs using python

You already might have noticed, as part of vSphere 6.5, VMware introduced vCenter Server REST APIs. I really enjoyed playing around them using vCenter apiexplorer as well as Postman REST client. Recently, I wanted to code around these APIs using one of the programming languages and I am happy that I was able to do it using Python. I thought it is worth to share with you. In this blog post, I will take you through all the steps required to get started with vCenter REST API using python. Here we go.

Step 1. First important thing is to get familiar with vCenter server REST API documentation. Similar documentation is available from vCenter apiexplorer as well. I would recommend you to play with apiexplorer, which will not only make you familiar with documentation but also will enable you to quickly invoke these APIs against your vCenter server. I am sure you will be pretty impressed on REST API documentation when compared to older vSphere SOAP API documentation.

Step 2. Once you explore the first step , we can get started with environment creation for REST APIs using python. If you ask me, it is fairly easy and quick, we just need to have python installed machine, where we need to install “requests” python module as follows

$ pip install requests

Step 3. Now let us take a look at below python module developed to simplify REST API usage.

[python]
# Author: Vikas Shitole
# Website: www.vThinkBeyondVM.com
# Product: vCenter server
# Description: Python module for vCenter server REST APIs
# Reference:https://code.vmware.com/apis/191/vsphere-automation
# How to setup vCenter REST API environment?: Just have VM with python and install "requests" python library using pip

import requests
import json
from requests.packages.urllib3.exceptions import InsecureRequestWarning
requests.packages.urllib3.disable_warnings(InsecureRequestWarning)

s=requests.Session()
s.verify=False

# Function to get the vCenter server session
def get_vc_session(vcip,username,password):
s.post(‘https://’+vcip+’/rest/com/vmware/cis/session’,auth=(username,password))
return s

# Function to get all the VMs from vCenter inventory
def get_vms(vcip):
vms=s.get(‘https://’+vcip+’/rest/vcenter/vm’)
return vms

#Function to power on particular VM
def poweron_vm(vmmoid,vcip):
s.post(‘https://’+vcip+’/rest/vcenter/vm/’+vmmoid+’/power/start’)

# Function to power off particular VM
def poweroff_vm(vmmoid,vcip):
s.post(‘https://’+vcip+’/rest/vcenter/vm/’+vmmoid+’/power/stop’)

[/python]
Above vcrest.py module is available on my github repo.

Let us understand above code.

Line 8: Imported powerful “requests” python library required to make API calls
Line 9: Imported “json” library required to parse json response we get from REST APIs
Line 10/11: Here we are disabling warnings related to SSL connection. In production, we should not disable it.
Line 13/14: Here we are creating Session object to have session persisted during the current request. If you see “s.verify” is set to False, it does mean that we are ignoring verifying SSL certificates. If you want to set it to true, please take a look at SSL Cert Verification section
Line 16 to 32: I have added 4 methods i.e. get_vc_session(), get_vms(), poweron_vm() & poweroff_vm(). We would be calling these methods from below sample script. If you see, in all the methods, I have used REST API documentation and called these APIs using “requests” library.

Step 4. Now that we understood above “vcrest.py” module, let us import above module into our script to demonstrate its usage.

[python]
# Description: Python sample to get VMs and its moid using vCenter server REST API.
# Reference:https://code.vmware.com/apis/191/vsphere-automation
# Make sure you have "rest.py" file into your python directory.

import vcrest
import json
vcip="10.192.23.143" # vCenter server ip address/FQDN

#Get vCenter server session and can be used as needed. pass vcenter username & password
vcsession = vcrest.get_vc_session(vcip,"Administrator@vsphere.local","VMware1!")

#Get all the VMs from inventory using below method from "vcrest" module.
vms = vcrest.get_vms(vcip)

# Parsing the JSON response we got from above function call (it has all the Vms present in inventory
vm_response=json.loads(vms.text)
json_data=vm_response["value"]

print "VM names and its unique MOID"
print "============================"
for vm in json_data:
print vm.get("name")+" :: "+vm.get("vm")
#We are powering on all the VMs those are in powered off state
if vm.get("power_state") == "POWERED_OFF":
vcrest.poweron_vm(vm.get("vm"),vcip)

[/python]
Above script i.e. vcrestsample.py is available on my github repo as well

Output :
vmware@localhost:~$ python vcrestsample.py
VM names and its unique MOID
============================
NTP-India-1 :: vm-42
NTP-PA-2 :: vm-43
WebApp-1 :: vm-44
vThinkBeyondVM :: vm-45
vmware@localhost:~$

Let us understand above script.

Line 5: Imported “vcrest” module we just discussed above.
Line 10: We are getting vCenter server session by calling function defined in “vcrest” module. We can use this session object as needed.
Line 13: We are getting all the VMs from inventory using “get_vms() function defined in “vcrest” module. Note that with this call, we will get JSON response as shown below, which we need to parse to fetch useful information.

[python]
{
"value": [
{
"memory_size_MiB": 512,
"vm": "vm-42",
"name": "NTP-India-1",
"power_state": "POWERED_OFF",
"cpu_count": 1
},
{
"memory_size_MiB": 512,
"vm": "vm-43",
"name": "NTP-PA-2",
"power_state": "POWERED_OFF",
"cpu_count": 1
},
{
"memory_size_MiB": 512,
"vm": "vm-44",
"name": "WebApp-1",
"power_state": "POWERED_ON",
"cpu_count": 1
},
{
"memory_size_MiB": 512,
"vm": "vm-45",
"name": "vThinkBeyondVM",
"power_state": "POWERED_ON",
"cpu_count": 1
}
]
}
[/python]

Line 16/17: As we got JSON response as pointed above, here we parsed it so that we can easily access as part of python dictionary.
Line 21 to 25: Iterating through dictionary and printing vm names & its moid (managed object id). Finally powering on VMs those are off.

That is all, is not it cool? Since we have REST APIs available for vCenter VM life cycle, VCSA, content library, tagging etc, there is lot to learn and play around. I will keep adding more methods to vcrest.py module. If you are interested in contributing to this module, let me know, it would be really great. In case, you would like to explore vCenter SOAP based APIs, please refer my last post

26 thoughts on “Getting started with vCenter server REST APIs using python

  1. Thanks for this write up , nice one , i am new to python , i am trying to understand below statement ,

    vm_response=json.loads(vms.text)

    how is that we know , that we need to call vms.text ? “text” ? From where do we understand that there is parameter call text ?

  2. How can i connect to an ESXi host using rest API and get the status of services running on the host ? i am basically looking to enable ssh on each host using python script and use paramiko

    1. REST APIs are not available on ESXi host at the moment. Initial focus looks like on most used workflows from vCenter. We may see more REST APIs release over release. vSphere 6.7 also added good bunch of REST APIs.

  3. Easy to understand. Though what kind of rights should the account which make the connection to the vCenter, have ?

    Cheers

    1. Roles and permission remains same as earlier i.e. If you are powering on a VM, we needed user with specific roles/permission earlier with SOAP APIs or from web client, same applies here

  4. Tried it but getting an error:

    Traceback (most recent call last):
    File “./vcrest_main.py”, line 14, in
    json_data=vm_response[“value”]
    KeyError: ‘value’

    Using python3

  5. Awesome. Thank you so much.
    I was searching the python api vcenter access method for a long time……

  6. Nice Article Vikas. Do you have any idea of boostrapping VCSA on single node vsancluster using Python API. Please let me know if you have any script around it. Thanks!

    1. Sorry for late response. I think single node VSAN cluster is not supported. There is REST API to reboot the appliance i.e. POST /appliance/shutdown/reboot . You can check REST API documentation https://VCIP/apiexplorer (in dropdown select “appliance”). vCenter must be 6.5 and above

  7. Hello,
    It’s not working for vCenter and vSphere 6.0.
    Am I doing something wrong or it’s only available for 6.5 version?

    Thanks!

  8. Hello,
    I am searching a rest api to do the same thing like vm.MarkAsTemplate().
    Anyone found it?

    Thx

  9. Hi, Vikas, It is very good article Just i want to know that how to delete the vcenter vm

  10. Hey Sandip, How do i get the vm ip address. Once i will call to the rest api for get the vm?

Comments are closed.