Getting APIC objects¶
With the acitoolkit, it is possible to get objects from the APIC either on demand or through object event subscriptions. In most cases, getting the objects on demand will be sufficient. However, in cases where action needs to be taken immediately or to avoid frequent polling of the APIC, event subscriptions can be used.
Objects on demand¶
Getting objects on demand is fairly straightforward. Each class that
allows getting objects from the APIC has a get
class method. This
method will return a list of objects belonging to that class type and
will be retrieved from the APIC immediately upon calling.
Since the acitoolkit can be used to control multiple APICs at the same
time, the Session
class instance representing the connection to
the desired APIC is also passed.
An example is shown in the code snippet below.:
tenants = Tenant.get(session)
for tenant in tenants:
print tenant.name
Event subscriptions¶
Event subscriptions allow immediate notification when an object is created, modified, or deleted. Events will be received only for classes or instances that are subscribed.
Class subscriptions¶
To create a class subscription, the class method subscribe
is
called on the desired class along with the appropriate Session
class instance. This is shown in the code snippet below using the
Tenant
class as the example.:
Tenant.subscribe(session)
To check an event has arrived, the method has_event
can be called
on the subscribed class.:
Tenant.has_event(session)
If there is an event waiting, this will return True
.
Note
While this may look like it requires polling the APIC, it is
actually just checking a local event receive queue. This
event queue is populated by a separate thread receiving
events from the APIC. Thus, calling has_event
will not
result in additional communication with the APIC so that
this call can be run in a tight loop with minimal overhead
and/or spun into a seperate thread if desired.
To retrieve the event, a call is made to the get_event
method as
shown below.:
event = Tenant.get_event(session)
This will return a instance of the object with the appropriate
settings indicating the change. For instance, if the Tenant
named Bob
is deleted, the event will return a Tenant
instance with the name set
to Bob and it will be marked as deleted.
To no longer receive events for this particular class, the class
method unsubscribe
can be called. This will cause the
subscription to be removed from the APIC.:
Tenant.unsubscribe(session)
Under the covers, the event subscriptions use a web socket to communicate with the APIC to receive the events. The events are then collected by a thread and placed into an event queue that is then queried by user code. Event subscriptions are refreshed automatically by the toolkit using a separate thread.
Instance subscriptions¶
Instance subscriptions are the same as class subscriptions except that the events are limited to only that particular object instance such as:
bob = Tenant('bob')
bob.subscribe(session)
bob.has_event(session)
event = bob.get_event(session)
A more useful example would be the following code which will wait for
an event for the instance of Tenant
with the name Bob and then
print a message if the instance was deleted.:
bob = Tenant('Bob')
bob.subscribe(session)
while True:
if bob.has_event(session):
bobs_event = bob.get_event(session)
if bobs_event.is_deleted():
print 'Bob was deleted'