You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Here's a simple program using the Python SDK. Obviously you'll have to change the host, username, password, and any other data that you may have customized. And don't experiment on your production Splunk server! Install the free version of Splunk on your own machine to experiment.::
5
+
6
+
import splunklib.client as client
7
+
c = client.connect(host="localhost",
8
+
port=8089,
9
+
scheme="https",
10
+
username="admin",
11
+
password="changeme")
12
+
saved_searches = c.saved_searches
13
+
mss = saved_searches.create("my_saved_search", "search * | head 10")
14
+
assert "my_saved_search" in saved_searches
15
+
saved_searches.delete("my_saved_search")
16
+
17
+
It's worth spending a few minute in ``ipython`` examining the objects produced in this example. ``c`` is a ``Service``[[TODO: link to reference docs]], which has [fields](link to list of fields in Service's docs) that provide access to most of Splunk's contents. ``saved_searches`` is a ``Collection``, and each entity in it is identified by a unique name (``"my_saved_search"`` in the example). All the names should be alphanumeric plus ``_`` and ``-``; no spaces are allowed[#]_.
18
+
19
+
.. [#] Splunk has two names for each entity: the pretty one meant to be displayed to users in the web browser, and the alphanumeric one that shows up in the URL of the REST call. It is the latter that is used in the SDK. Thus the Search app in Splunk is called "Search" in the web interface, but to fetch it via the SDK, you would write ``c.apps['search']``, not ``c.apps['Search']``. The "Getting Started" app is ``c.apps['gettingstarted']``, not ``c.apps['Getting Started']``.
20
+
21
+
A ``Collection`` acts like a dictionary. You can call ``keys``, ``iteritems``, and ``itervalues`` just like on a dictionary. However, you cannot assign to keys. ``saved_searches['some_name'] = ...`` is nonsense. Use the ``create`` method instead. Also, ``del saved_searches['some_name']`` does not currently work. Use the ``delete`` method instead.
22
+
23
+
Note that in the example code we did not assert::
24
+
25
+
mss == saved_searches["my_saved_search"]
26
+
27
+
The Python objects you are manipulating represent snapshots of the server's state at some point in the past. There is no good way of defining equality on these that isn't misleading in many cases, so we have made ``==`` and ``!=`` raise exceptions for entities.
28
+
29
+
Another side effect of using snapshots: after we delete the saved search in the example, ``mss`` is still bound to the same local object representing that search, even though it no longer exists on the server. If you need to update your snapshot, call the ``refresh`` method[#]_. For more on caching and snapshots, see [[TODO: link to section on roundtrips and caching]]
30
+
31
+
.. [#] Calling ``refresh`` on an entity that has already been deleted raises an ``HTTPError``.
32
+
33
+
You can access the fields of an entity either as if they were keys in a dictionary, or fields of an object::
34
+
35
+
mss['search'] == "search * | head 10"
36
+
mss.search == "search * | head 10"
37
+
38
+
mss['action.email'] == '0'
39
+
mss.action.email == '0'
40
+
41
+
A ``.`` isn't a valid character in identifiers in Python. The second form is actually a series of field lookups. As as side effect, you can get groups of fields that share prefixes.::
42
+
43
+
mss['action'] == {'email': '0',
44
+
'populate_lookup': '0',
45
+
'rss': '0',
46
+
'script': '0',
47
+
'summary_index': '0'}
48
+
mss.action == {'email': '0',
49
+
'populate_lookup': '0',
50
+
'rss': '0',
51
+
'script': '0',
52
+
'summary_index': '0'}
53
+
54
+
Those look like dictionaries, but they're actually a subclass called ``Record`` [[TODO: link to reference documentation]] that allows keys to be looked up as fields. [[TODO: Implement keys() on entities, and document it here]] In addition to fields, each kind of entity has a range of methods.::
55
+
56
+
mss.dispatch() # Runs the saved search.
57
+
mss.suppress(30) # Suppress all alerts from this saved search for 30 seconds
58
+
59
+
This should be enough information to understand the reference documentation and start using the SDK productively.
60
+
61
+
Roundtrips and caching
62
+
----------------------
63
+
64
+
The rate limiting step in most programs that call REST APIs is calls to the server. The SDK is designed to minimize and postpone these as much as possible. When you fetch an object from the SDK, you get a snapshot. If there are updates on the server after that snapshot, you won't know about them until you call ``refresh`` on your object. The object might even have been deleted.
0 commit comments