Undocumented VI and vSphere API Methods: A Little History

Most developers may have noticed the asynchronous methods in vSphere API like PowerOnVM_Task method, but not so many know their synchronous peers like PowerOnVM before 4.1. VMware vSphere API Reference doesn’t mention them at all. But you can find them in WSDL(check out the WSDL snippets at the end of this article).

There is an exception however. In VI Perl, these synchronous methods are exposed. There, you can choose which one to use. In vSphere Java API 2.0, these methods are exposed only in the stub layer but not the object layer. You don’t want to use stub methods directly when you can use objects, therefore I don’t talk much about it even in my book. Somehow I came across a question in the forum asking about this. So I think it may be good to share a little history and insight here.

Bothered by SLOW Web UI to manage vSphere? Want to manage ALL your VMware vCenters, AWS, Azure, Openstack, container behind a SINGLE pane of glass? Want to search, analyze, report, visualize VMs, hosts, networks, datastores, events as easily as Google the Web? Find out more about vSearch 3.0: the search engine for all your private and public clouds.

The differences of these twin methods are minimal. They have exactly same parameters but different returns. The methods whose names include _Task suffix have Task returned. When you have the Task return, the operation may not yet be done at the server side. But with the Task object, you can track the progress, and even get the result data objects.

For the methods without _Task suffixes, they don’t have any object return. When the methods finish, the operation should have been done at the server side.

Functionality wise, the first type is superset and you can easily implement the second one on top of the first. So why was the second one there? Maybe a little convenience. You can think it as a shorthand method in Java.

As of 4.1, the second type of methods have been removed from WSDL because they are not really necessary. Therefore, they are totally a history now.

Listing 1. Snippet from vSphere API 4.0 WSDL

<operation name="PowerOnVM">
 <input message="vim25:PowerOnVMRequestMsg" />
 <output message="vim25:PowerOnVMResponseMsg" />
 <fault name="TaskInProgressFault" message="vim25:TaskInProgressFaultMsg"/>
 <fault name="InvalidStateFault" message="vim25:InvalidStateFaultMsg"/>
 <fault name="InsufficientResourcesFaultFault" message="vim25:InsufficientResourcesFaultFaultMsg"/>
 <fault name="VmConfigFaultFault" message="vim25:VmConfigFaultFaultMsg"/>
 <fault name="FileFaultFault" message="vim25:FileFaultFaultMsg"/>
 <fault name="RuntimeFault" message="vim25:RuntimeFaultFaultMsg"/>
 </operation>
 <operation name="PowerOnVM_Task">
 <input message="vim25:PowerOnVM_TaskRequestMsg" />
 <output message="vim25:PowerOnVM_TaskResponseMsg" />
 <fault name="TaskInProgressFault" message="vim25:TaskInProgressFaultMsg"/>
 <fault name="InvalidStateFault" message="vim25:InvalidStateFaultMsg"/>
 <fault name="InsufficientResourcesFaultFault" message="vim25:InsufficientResourcesFaultFaultMsg"/>
 <fault name="VmConfigFaultFault" message="vim25:VmConfigFaultFaultMsg"/>
 <fault name="FileFaultFault" message="vim25:FileFaultFaultMsg"/>
 <fault name="RuntimeFault" message="vim25:RuntimeFaultFaultMsg"/>
 </operation>

Listing 2. Snippet from vSphere API 4.1 WSDL

<operation name="PowerOnVM_Task">
 <soap:operation soapAction="urn:vim25/4.1" style="document" />
 <input>
 <soap:body use="literal" />
 </input>
 <output>
 <soap:body use="literal" />
 </output>
 <fault name="TaskInProgressFault">
 <soap:fault name="TaskInProgressFault" use="literal" />
 </fault>
 <fault name="InvalidStateFault">
 <soap:fault name="InvalidStateFault" use="literal" />
 </fault>
 <fault name="InsufficientResourcesFaultFault">
 <soap:fault name="InsufficientResourcesFaultFault" use="literal" />
 </fault>
 <fault name="VmConfigFaultFault">
 <soap:fault name="VmConfigFaultFault" use="literal" />
 </fault>
 <fault name="FileFaultFault">
 <soap:fault name="FileFaultFault" use="literal" />
 </fault>
 <fault name="RuntimeFault">
 <soap:fault name="RuntimeFault" use="literal" />
 </fault>
 </operation>

This entry was posted in vSphere API and tagged , , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.

Post a Comment

Your email is never published nor shared. Required fields are marked *

*
*

You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

  • NEED HELP?


    My company has created products like vSearch ("Super vCenter"), vijavaNG APIs, EAM APIs, ICE tool. We also help clients with virtualization and cloud computing on customized development, training. Should you, or someone you know, need these products and services, please feel free to contact me: steve __AT__ doublecloud.org.

    Me: Steve Jin, VMware vExpert who authored the VMware VI and vSphere SDK by Prentice Hall, and created the de factor open source vSphere Java API while working at VMware engineering. Companies like Cisco, EMC, NetApp, HP, Dell, VMware, are among the users of the API and other tools I developed for their products, internal IT orchestration, and test automation.