AccessGrid.org

Calling Access Grid Web services

The Access Grid is built atop SOAP-based web services. SOAP will not be covered in this document in any more detail than is necessary, and need not be. For the sake of Access Grid development, client classes have been generated and ship with the software. These classes simplify the task of making remote method calls significantly, so in most cases one need only instantiate an object with a valid web service URL and begin executing methods on it.

In cases where the generated client is not appropriate for the development task, a client can be generated from the WSDL. The WSDL for any running Access Grid service can be retrieved by appending "?WSDL" to the service url; for example

https://vv3.mcs.anl.gov:8000/Venues/default?WSDL

will return the WSDL for an Access Grid Venue.

Web Services example

As an example of a web service call, imagine that one wanted to retrieve the list of clients (users) in an Access Grid Venue. Considering that the list of clients is information about a Venue, one would expect to find a method for retrieving the list of clients in the Venue class.

To instantiate a Venue object, one needs the Venue URL:

venue = VenueIW('https://vv3.mcs.anl.gov:8000/Venues/default')

Given a Venue object, retrieving the list of clients is simple:

venueState = venue.GetState()
clientList = venueState.clients

Note that all the details around SOAP and data serialization/deserialization are handled internal to this method call, so the caller passes in Python objects (none in this case) and receives Python objects in return (the venue state).

Adding some preliminary code to this yields a minimal functional example:

import agversion
agversion.select(3)
from AccessGrid.interfaces.Venue_client import VenueIW
venue = VenueIW('https://vv3.mcs.anl.gov:8000/Venues/default')
venueState = venue.GetState()
for client in venueState.clients:
print client

Note: On OSX, an additional step is needed before executing any Python program that uses the Access Grid Python module. See Prerequisites for more information.

The result of running this program is a list of clients, as you would expect. For each client in the list, something like the following will be printed:

 Profile Type: user 
 Name: Tom Uram
 Email: turam@mcs.anl.gov 
 Phone Number:  
 Location:  
 Venue Client URL: http://isar.mcs.anl.gov:11000/VenueClient 
 Public ID: c0a8fe0210d66704fe6bbf15d743c8ab 
 Home Venue: https://vv3.mcs.anl.gov:8000/Venues/default

Component architecture

The Access Grid architecture is given (roughly) in the figure below. Each of the components in this diagram has a web services interface and is, therefore, callable as in the example above.

 

 

Web service clients and where to find them

The generated web service client classes reside in the AccessGrid Python module in the AccessGrid.interfaces module. Note the import of the VenueIW client class above, according to a pattern which can be described as:

from AccessGrid.interfaces.COMPONENT_client import COMPONENTIW

Here COMPONENT could be any of the Access Grid web service components.

The service components in the Access Grid--most notably Venues and VenueServers--use SOAP/SSL for communication. This section of the guide describes the available services and gives examples of calls that can be made against them.

VenueServer
https://hostname:8000/VenueServer
Note: The default port is 8000, but VenueServers can be run on any port

Venue
Note: The default port is 8000, but VenueServers (and hence Venues) can be run on any port

VenueClient
http://hostname:11000/VenueClient
Note: The default port is 11000, but the VenueClient can be run on any port, and in some cases, will be by default. Use VenueClient.GetVenueClientUrls to determine the URL of locally running VenueClients.

NodeService
http://hostname:11000/NodeService
Note: The default port is 11000, but NodeServices can be run on any port

ServiceManager
http://hostname:11000/ServiceManager
Note: The default port is 11000, but ServiceManagers can be run on any port

Service (e.g., AudioService, VideoService, etc.)
http://hostname:port/Service.serviceid
Up to AG3.1, services run on a random port
Starting with AG3.2, services can be run internal to the node service, in which case the port is 11000.
Either way, service URLs (which include the port) should be determined by a call to AGServiceManager.GetServices

Examples of Calling AG Services

To run any of these examples, save the code to a file and run the following command:

python code.py

Example: Getting Venues from a VenueServer

GetVenues.py

import agversion
agversion.select(3)
from AccessGrid.interfaces.VenueServer_client import VenueServerIW
venueServerUrl = 'https://vv3.mcs.anl.gov:8000/VenueServer'
venueServer = VenueServerIW(venueServerUrl)
venueList = venueServer.GetVenues()
for venue in venueList:
print venue.name

Example: Getting clients from a Venue

GetClients.py

import agversion
agversion.select(3)
from AccessGrid.interfaces.Venue_client import VenueIW
venueUrl = 'https://vv3.mcs.anl.gov:8000/Venues/default'
venue = VenueIW(venueUrl)
venueState = venue.GetState()
clientList = venueState.clients
for client in clientList:
print client.name

Example: Messaging a VenueClient to enter a Venue

EnterVenue.py

With this example, one could control VenueClients across the network

import agversion
agversion.select(3)
from AccessGrid.interfaces.VenueClient_client import VenueClientIW
venueClientUrl = 'http://hostname:11000/VenueClient'
venueUrl = 'https://vv3.mcs.anl.gov:8000/Venues/default'
venueClient = VenueClientIW(venueClientUrl)
venueClient.EnterVenue(venueUrl)

Example: Calling services that require authentication (a certificate)

GetDefaultVenue.py

import traceback
import agversion
agversion.select(3)
from AccessGrid.interfaces.VenueServer_client import VenueServerIW
from AccessGrid import Toolkit
venueServerUrl = 'https://vv3.mcs.anl.gov:8000/VenueServer'
venueServer = VenueServerIW(venueServerUrl)
try:
print 'This call should fail with a RuntimeError'
venueServer.GetDefaultVenue()
except RuntimeError:
print '* * Failed'
traceback.print_exc()
# Initialize the AG toolkit
app = Toolkit.Application.instance()
app.Initialize()
# Get the default identity and use the cert and key files
# Note: This uses the default cert/key directly with Python's integrated SSL support.
id = app.GetCertificateManager().GetDefaultIdentity()
venueServer = VenueServerIW(venueServerUrl,transdict={'cert_file':id.GetPath(),'key_file':id.GetKeyPath()})
defaultVenue = venueServer.GetDefaultVenue()
print defaultVenue
# Set up ZSI to use M2Crypto's httpslib instead of Python's SSL
from ZSI import client
from M2Crypto import httpslib, SSL
client.Binding.defaultHttpsTransport = httpslib.HTTPSConnection
# disable SSL post connection checks
SSL.Connection.clientPostConnectionCheck = None
SSL.Connection.serverPostConnectionCheck = None
# Get the default identity and use the resulting SSL context
ssl_context = app.GetContext()
venueServer = VenueServerIW(venueServerUrl,transdict={'ssl_context':ssl_context})
defaultVenue = venueServer.GetDefaultVenue()
print defaultVenue

Conclusion

Calling Access Grid services is trivial and powerful. The core AG tools use these calls for their communication, and its the preferred mechanism for applications to interoperate with the AG services.

Suggested Further Work

  • Venue access control tools
  • Suite of command-line tools for Venue Management
  • Scripts to query venue state and present as HTML for use in widgets (for example, OSX dashboard or iGoogle)


Supporting Code

GetVenues.py

GetClients.py

EnterVenue.py

GetDefaultVenue.py

 

 

 

login or register to post comments