Using the API¶
In this document we will see some examples on how to use the vPoller API.
You can use these examples for connecting your project to vPoller and send task requests for processing.
Sending task requests for processing¶
Connecting your Python project to vPoller is easy.
If you only need to be able to talk to vPoller and send task requests
then using the VPollerClient
class is the way to go.
The VPollerClient
sends task requests to the vPoller Proxy
,
which distributes the task requests to the vPoller Workers
.
Here is how you can send task requests from your Python project to vPoller for processing.
>>> from vpoller.client import VPollerClient
>>> msg = {'method': 'vm.discover', 'hostname': 'vc01.example.org'}
>>> client = VPollerClient(endpoint='tcp://localhost:10123')
>>> result = client.run(msg)
>>> print result
The above example code will send a task request for
discovering all Virtual Machine managed objects from the
vc01.example.org
vSphere host.
And here is what the above example code does:
- Imports the
VPollerClient
class from thevpoller.client
module - Creates a message that will be sent to the
vPoller Proxy
endpoint. The message contains information such as themethod
to be processed, the vSphere hostname, and any additional details required for processing the task request. - We instantiate a
VPollerClient
object and set the endpoint to which the client will connect and send the task request for processing. - Using the
run()
method of aVPollerClient
instance we send the task request over the wire and wait for response.
The VPollerClient
class comes with builtin mechanism for automatic
retry if it doesn’t receive a response after some period of time.
In order to control the retry
and timeout
settings of a
VPollerClient
object you can instantiate a client object this way:
>>> client = VPollerClient(
... endpoint='tcp://localhost:10123',
... retries=1,
... timeout=1000
... )
Note, that the timeout
argument used above is in milliseconds.
Here is another example which would get the runtime.powerState
property for a specific Virtual Machine:
>>> import json
>>> from vpoller.client import VPollerClient
>>> msg = {
... 'method': 'vm.get',
... 'hostname': 'vc01.example.org',
... 'name': 'vm01.example.org',
... 'properties': ['name', 'runtime.powerState']
... }
>>> client = VPollerClient(endpoint='tcp://localhost:10123')
>>> result = client.run(msg)
>>> print json.dumps(result, indent=4)
{
"msg": "Successfully retrieved object properties",
"result": [
{
"runtime.powerState": "poweredOn",
"name": "vm01.example.org"
}
],
"success": 0
}
As you can see we have successfully retrieved the
runtime.powerState
property for our Virtual Machine, which shows
that our Virtual Machine is powered on.
For a full list of supported vPoller methods which you can use, please refer to the Supported methods by vPoller documentation.
You are also advised to check the vpoller.agent module, which is pretty well documented and provides information about each vPoller method and the expected message request in order to begin processing the task.
Executing vPoller tasks locally¶
Using the VPollerClient
class as we’ve seen in the previous
section of this document sends task requests to the
vPoller Proxy
, which distributes the tasks to any connected
vPoller Worker
.
This was a remote operation, where a client simply sends a task request and waits for a response.
You could also use vPoller in order to execute tasks locally, which means that no task is send over the wire and all the hard work is done on the local system.
Here is an example of interfacing with the vSphere Agents
, which
provides us with an interface to execute vPoller tasks locally.
The example below is equivalent to the examples in the previous section, except for one thing - it will be executed locally on the system running this code, and it will not be processed by a remote worker.
>>> from vpoller.agent import VSphereAgent
>>> agent = VSphereAgent(
... user='root',
... pwd='p4ssw0rd',
... host='vc01.example.org'
... )
>>> agent.connect()
>>> result = agent.vm_discover(msg={})
>>> print result
Interfacing with vPoller from other languages¶
Connecting to vPoller from other languages is easy as well.
vPoller uses the ZeroMQ messaging library as the communication layer, so in theory every language that comes with ZeroMQ bindings should be able to interface with vPoller.
You can find below a simple example of using Ruby for sending a task request to vPoller:
#!/usr/bin/env ruby
require 'json'
require 'rubygems'
require 'ffi-rzmq'
# Message we send to vPoller
msg = {:method => "vm.discover", :hostname => "vc01.example.org"}
# Create the ZeroMQ context and socket
context = ZMQ::Context.new(1)
socket = context.socket(ZMQ::REQ)
puts "Connecting to vPoller ..."
socket.connect("tcp://localhost:10123")
puts "Sending task request to vPoller ..."
socket.send_string(msg.to_json)
result = ''
socket.recv_string(result)
puts "Received reply from vPoller: #{result}"
You might also want to check the vpoller.client module for example
code that you can use in order to implement a VPollerClient
class
in your language of choice.