Using the PCL to Make SOAP Requests

Using the PCL to Make SOAP Requests

Authentication Example

Below is a more complete example of the list_tails function. It authenticates against a Splunk Pro server, which could be elsewhere on the network, passes the authentication token with the list_tails request, and prints the contents of the returned dictionary.

#!/opt/splunk/bin/python -u
# splunk api
import splunk.clilib.control_api as ca
import splunk.clilib.cli_common  as comm
# splunk exception handling
# use "from ... import ..." to avoid namespace problems
from splunk.clilib import control_exceptions
# for exit()
import sys
# optionally connect to another server at hostname:port
# 8089 is the default Splunk SOAP port
# comm.setURI("https://testserver:8089")
try:
# send the username/password, get back the auth token
  authString = comm.getAuthInfo("admin", "changeme")
except control_exceptions.AuthError:
  print "Authentication failed."
  sys.exit(1)
# make a dictionary with the auth token
argsDict = {
  "authstr" : authString
}
# PCL call, returns list of tails
results = ca.tail_list(argsDict)
# output the results
for key, values in results.items():
  print "%s: %s" % (key, values)

Run against a Splunk Pro server, the output looks like this:

dirs: ['/var/log/httpd']

dynamic: ['/var/log/httpd/error_log', '/var/log/httpd/access_log']

static: ['/var/log/system.log']

If this example is run against a free server, an exception is raised because it can't handle the call to getAuthInfo.

Traceback (most recent call last):
  File "./listTails.py", line 18, in ?
    authString = comm.getAuthInfo("admin", "changeme")
  File "/opt/splunk/lib/python2.4/site-packages/splunk/clilib/cli_common.py", line 135, in getAuthInfo
    retStr = callAPI(block)
  File "/opt/splunk/lib/python2.4/site-packages/splunk/clilib/cli_common.py", line 180, in callAPI
    raise InvokeAPI, str(root.documentElement.firstChild.data)
splunk.clilib.control_exceptions.InvokeAPI: 'badparams'

The message "badparams" is a generic error. In this case it indicates that the requested operation, authentication against a free server, does not exist.

Search Example

Here is an example of a search. The key "terms" is the same as what you would type in the Splunk Box to do a search. For more on what you can specify here, see the Language Reference.

#!/opt/splunk/bin/python -u
# splunk api
import splunk.clilib.control_api as ca
import splunk.clilib.cli_common  as comm
# splunk exception handling
# use "from ... import ..." to avoid namespace problems
from splunk.clilib import control_exceptions
# for exit()
import sys
try:
# send the username/password, get back the auth token
  authString = comm.getAuthInfo("admin", "changeme")
except control_exceptions.AuthError:
  print "Authentication failed."
  sys.exit(1)
# make a dictionary with the auth token and the search string
argsDict = {
  "authstr" : authString,
  "terms"   : "404"
}
results = ca.search(argsDict)
print results

The output when run against the same minimal Splunk Pro server is this:

127.0.0.1 - - [07/Feb/2007:10:28:33 -0800] "GET /favicon.ico HTTP/1.1" 404 302

To get the full event, including metadata, specify you want XML by adding "format" to the dictionary:

argsDict = {
  "authstr" : authString,
  "terms"   : "404",
  "format"  : "xml"
}

Now the result is this:

<queryResult><ids>
</ids>
<results type="events"> <result cd="0:2891"><segtext xml:space="preserve">127.0.0.1 - - [07/Feb/2007:10:28:33 -0800] "GET /favicon.ico HTTP/1.1" 404 302<meta></meta></segtext>               <timestamp>1170872913</timestamp>               <source cd="2">/var/log/httpd/access_log</source>
                <host cd="1" name="test.splunk.com" >                 <tags></tags>
</host>         <sourcetype cd="2" base="too_small">too_small</sourcetype>
                <type cd="9" wob=" v:226e b1:110 a1:49 j1:4111519 k2:529728502 h2:2550214376 g1:2550123436  ">
                        <tags></tags>
</type>
</result></results></queryResult>

For more about the search function, you can look at the Python code in the file searchizzle.py. The function definition begins like this:

def search(args, fromCLI):
  paramsReq = ("terms", "authstr")
  paramsOpt = ("output", "format", "get")

which shows the required and optional parameters. "output" is the output type, the default is "splunkui" (and this is almost always the correct choice.) "format" was mentioned above, and "get" is the type of data to return.

The default for get is "events", to return matching events. You could also specify "hosts" to return a list of hosts with matching events and so on. The list of possible values is defined in validGetTypes a few lines below:

  validGetTypes     = ("events", "hosts", "sources", "sourcetypes", "types")

• Was this topic useful?
• Post a comment