Difference between revisions of "Working with the JSON API"

From Zenoss Wiki
Jump to: navigation, search
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
[https://www.zenoss.com/sites/default/files/documentation/Zenoss_JSON_API_r5.0.4_d28.15.180_0.zip API documentation for the Zenoss JSON API].  
+
[https://www.zenoss.com/sites/default/files/documentation/Zenoss_JSON_API_r5.0.4_d28.15.180_0.zip API documentation for the Zenoss JSON API]. The [https://dl.dropbox.com/u/50577/json_api.sh json_api.sh] provides a "zenoss_api" function to access the various JSON APIs exposed by Zenoss. Once you have it, source it at your shell to get the zenoss_api function:
 
+
The [http://wiki.zenoss.org/json_api.sh json_api.sh] provides a "zenoss_api" function to access the various JSON APIs exposed by Zenoss.
+
 
+
There is an updated version for Zenoss 5 now too. [[Working_with_the_JSON_API#v5_version_of_the_json_api.sh|v5 json_api.sh]]
+
 
+
Once you have it, source it at your shell to get the zenoss_api function:
+
  
 
<pre>
 
<pre>
Line 12: Line 6:
  
 
= Examples =  
 
= Examples =  
 
== Conventional Naming of "Routers" in examples below ==
 
You'll see in the example below reference e.g. <tt>device_router</tt>. The correct value here is NOT consistently documented in the API docs, but it is CONVENTIONALLY derivable from the name of the Router class.
 
 
For example:
 
<pre>
 
Products.Zuul.routers.device -> device_router
 
Products.Zuul.routers.users -> users_router
 
Products.Zuul.routers.triggers -> triggers_router.
 
</pre>
 
 
You get the idea? This is the magic you need for the first parameter. For the rest, read and understand the API docs at docs.zenoss.com.
 
See the "List of Router Endpoints" section below for a list of all these "router" names. Definitive source is the API docs however.
 
 
 
 
 
 
== Add a user ==
 
 
Add a user with ZenUser role
 
 
<pre>
 
zenoss_api users_router UsersRouter addUser '{"id":"myusername","password":"mypassword","email":"my@email.address","roles":["ZenUser"]}'
 
</pre>
 
  
 
== Get List of Graph URLS for a Device or Component of a Device ==
 
== Get List of Graph URLS for a Device or Component of a Device ==
Line 88: Line 57:
 
Use DeviceRouter moveDevices method.
 
Use DeviceRouter moveDevices method.
  
  zenoss_api "device_router" "DeviceRouter" "moveDevices" '{"uids":["/zport/dmd/Devices/Server/Windows/devices/testdevice"],"hashcheck":"","target":"/zport/dmd/Systems/Webservers"}'
+
  zenoss_api "device_router" "DeviceRouter" "moveDevices" '{"uids":["/zport/dmd/Devices/Server/Windows/devices/testdevice"],"hashcheck":"","uid":"/zport/dmd/Systems/Webservers"}'
  
 
== Remove a Device from a System or Group ==
 
== Remove a Device from a System or Group ==
Line 176: Line 145:
 
== API documentation ==
 
== API documentation ==
  
* [https://www.zenoss.com/services-support/documentation Look for the latest API documentation for Zenoss 5.X here. ]
+
* [https://www.zenoss.com/sites/default/files/documentation/Zenoss_JSON_API_r5.0.4_d28.15.180_0.zip API documentation for the Zenoss 5.X]
 
* [http://monitoringartist.github.io/community.zenoss.org/community/documentation/official_documentation/api.html API documentation for the Zenoss 4.X]
 
* [http://monitoringartist.github.io/community.zenoss.org/community/documentation/official_documentation/api.html API documentation for the Zenoss 4.X]
  
== List of Router Endpoints ==
 
application_router<br />
 
detailnav_router<br />
 
devicedumpload_router<br />
 
devicemanagement_router<br />
 
device_router<br />
 
evclasses_router<br />
 
evconsole_router<br />
 
host_router<br />
 
introspection_router<br />
 
jobs_router<br />
 
manufacturers_router<br />
 
messaging_router<br />
 
mib_router<br />
 
monitor_router<br />
 
network_6_router<br />
 
network_router<br />
 
process_router<br />
 
properties_router<br />
 
report_router<br />
 
search_router<br />
 
service_router<br />
 
settings_router<br />
 
template_router<br />
 
triggers_router<br />
 
users_router<br />
 
zenpack_router<br />
 
 
== v5 version of the json_api.sh ==
 
Zenoss Version 5 had some changes that reqired a couple of small tweaks to the json_api.sh script.
 
 
<pre>#!/bin/sh
 
 
# Your Zenoss server settings.
 
# The URL to access your Zenoss5 Endpoint
 
ZENOSS_URL="https://zenoss5.<your FQDN>"
 
ZENOSS_USERNAME="admin"
 
ZENOSS_PASSWORD="zenoss"
 
 
# Generic call to make Zenoss JSON API calls easier on the shell.
 
zenoss_api () {
 
    ROUTER_ENDPOINT=$1
 
    ROUTER_ACTION=$2
 
    ROUTER_METHOD=$3
 
    DATA=$4
 
 
    if [ -z "${DATA}" ]; then
 
        echo "Usage: zenoss_api <endpoint> <action> <method> <data>"
 
        return 1
 
    fi
 
# add a -k for the curl call to ignore the default cert
 
    curl \
 
        -k \
 
        -u "$ZENOSS_USERNAME:$ZENOSS_PASSWORD" \
 
        -X POST \
 
        -H "Content-Type: application/json" \
 
        -d "{\"action\":\"$ROUTER_ACTION\",\"method\":\"$ROUTER_METHOD\",\"data\":[$DATA], \"tid\":1}" \
 
        "$ZENOSS_URL/zport/dmd/$ROUTER_ENDPOINT"
 
}
 
 
# Helper call to send an event.
 
#
 
# Example usage:
 
#  zenoss_send_event device1 component1 5 key1 test
 
zenoss_send_event() {
 
    DEVICE=$1
 
    COMPONENT=$2
 
    SEVERITY=$3
 
    EVENT_CLASS_KEY=$4
 
    SUMMARY=$5
 
 
    if [ -z "$SUMMARY" ]; then
 
        echo "Usage: zenoss_send_event <device> <component> <severity> <eventClassKey> <summary>"
 
        return 1
 
    fi
 
 
    zenoss_api evconsole_router EventsRouter add_event \
 
        "{\"device\":\"$DEVICE\",\"summary\":\"$SUMMARY\",\"component\":\"$COMPONENT\",\"severity\":\"$SEVERITY\",\"evclasskey\":\"$EVENT_CLASS_KEY\"}"
 
}
 
 
# Helper call for adding standard device types.
 
zenoss_add_device() {
 
    DEVICE_HOSTNAME=$1
 
    DEVICE_CLASS=$2
 
 
    if [ -z "$DEVICE_CLASS" ]; then
 
        echo "Usage: zenoss_add_device <host> <device class>"
 
        return 1
 
    fi
 
 
    zenoss_api device_router DeviceRouter addDevice "{\"deviceName\":\"$DEVICE_HOSTNAME\",\"deviceClass\":\"$DEVICE_CLASS\",\"collector\":\"localhost\",\"model\":true,\"title\":\"\",\"productionState\":\"1000\",\"priority\":\"3\",\"snmpCommunity\":\"\",\"snmpPort\":161,\"tag\":\"\",\"rackSlot\":\"\",\"serialNumber\":\"\",\"hwManufacturer\":\"\",\"hwProductName\":\"\",\"osManufacturer\":\"\",\"osProductName\":\"\",\"comments\":\"\"}"
 
}
 
</pre>
 
  
 
[[Category:Tips]]
 
[[Category:Tips]]
 
[[Category:Development]]
 
[[Category:Development]]

Revision as of 18:12, 31 March 2016

API documentation for the Zenoss JSON API. The json_api.sh provides a "zenoss_api" function to access the various JSON APIs exposed by Zenoss. Once you have it, source it at your shell to get the zenoss_api function:

$ source json_api.sh

Examples

Get List of Graph URLS for a Device or Component of a Device

Uses the DeviceRouter getGraphDefs method. Returns JSON that contains the title and graph URL for every graph on the device identified by the uid parameter.

zenoss_api device_router DeviceRouter getGraphDefs '{"uid":"/zport/dmd/Devices/Server/Linux/devices/zenosstrain6.zenoss.com","drange":129600}'

zenoss_api device_router DeviceRouter getGraphDefs '{"uid":"/zport/dmd/Devices/Server/Linux/devices/zenosstrain6.zenoss.com/os/filesystems/var"}'

Get a List of Devices

zenoss_api device_router DeviceRouter getDevices '{"keys":["list of keys"],"uid":"some zenoss organizer"}'

uid is optional, will list everything unless you narrow it. The "organizer" is a device class, group, system, or location, specified like "/zport/dmd/Groups/Production" or "/zport/dmd/Devices/Server/Windows"

keys is optional, if you leave it out you get a set of information that includes device UID, name, managedIp, priority, prodstate, hwModel, hwManufacturer, osModel, osManufacturer, systems, groups, collector, location, serial number, tag number, and a count of events. You can also ask for uuid, uptime, snmpCommunity, snmpVersion, snmpSysName, snmpDescription, id, device, comments, memory, and deviceClass.

"start" and "limit" params can be used to retrieve the result set in batches.

Get a List of Device Components

zenoss_api device_router DeviceRouter getComponents '{"uid":"/zport/dmd/Devices/Server/Linux/devices/zenosstrain6.zenoss.com"}'

  • Get Filesystems only
zenoss_api device_router DeviceRouter getComponents '{"uid":"/zport/dmd/Devices/Server/Linux/devices/zenosstrain6.zenoss.com","meta_type":"FileSystem"}'
  • Get CPU List
zenoss_api device_router DeviceRouter getComponents '{"uid":"/zport/dmd/Devices/Server/Linux/devices/zenosstrain6.zenoss.com","meta_type":"CPU","name":null}'
  • Other "meta_types"

Meta_types for components depend on what components are modeled onto your devices but here are some common ones: FileSystem, HardDisk, IpInterface, IpService, IpRouteEntry, CPU, OsProcess

Set Description field on an Ip Interface

  • Get the uids of the interfaces:
zenoss_api device_router DeviceRouter getComponents '{"uid":"/zport/dmd/Devices/Server/Windows/devices/SERVER","meta_type":"IpInterface","keys":["uid"]}'
  • Set the description on a given interface:
zenoss_api device_router DeviceRouter setInfo '{"uid":"/zport/dmd/Devices/Server/Windows/devices/SERVER/os/interfaces/VMware Accelerated AMD PCNet Adapter","description":"test"}'

Add Device to a System or Group

Use DeviceRouter moveDevices method.

zenoss_api "device_router" "DeviceRouter" "moveDevices" '{"uids":["/zport/dmd/Devices/Server/Windows/devices/testdevice"],"hashcheck":"","uid":"/zport/dmd/Systems/Webservers"}'

Remove a Device from a System or Group

Use DeviceRouter/removeDevices method. It's ok if the Device isn't actually in the System or Group that you try to remove it from.

zenoss_api "device_router" "DeviceRouter" "removeDevices" '{"uids":["/zport/dmd/Devices/Server/Windows/devices/testdevice"],"hashcheck":"","uid":"/zport/dmd/Systems/systemtoremove"}'

Set ProductionState or Priority on a Device

Uses DeviceRouter setInfo method.

zenoss_api "device_router" "DeviceRouter" "setInfo" '{"uid":"/zport/dmd/Devices/Server/Windows/devices/testdevice","productionState":$numericvalue}'
zenoss_api "device_router" "DeviceRouter" "setInfo" '{"uid":"/zport/dmd/Devices/Server/Windows/devices/testdevice","priority":$numericvalue}'

List Available ProductionStates or Priorities

Uses DeviceRouter getProductionStates and getPriorities method. Returns JSON.

zenoss_api "device_router" "DeviceRouter" "getProductionStates" '{}'
zenoss_api "device_router" "DeviceRouter" "getPriorities" '{}'

Create/Update Events

  • Severities are 0 thru 5 (0 is "Clear" and the others are ascending level of priority). See API doc for more fields.
zenoss_api evconsole_router EventsRouter add_event '{"summary":"$summary","device":"$device","component":"$component","severity":$severity,"evclasskey":"$evkey","evclass":"$evclass"}'

List Events

Uses EventsRouter query method. Returns JSON.

  • eventState 0,1 = New, Acknowledged
zenoss_api evconsole_router EventsRouter query '{"limit":2000,"params":{"eventState":[0,1]}}'
  • uid can be a specific device or a deviceClass, or a group or system organizer...
zenoss_api evconsole_router EventsRouter query '{"limit":2000,"uid":"/zport/dmd/Devices/Server/Windows"}'

Manipulate Events

Uses EventsRouter methods: close|reopen|acknowledge|unacknowledge. Requires an Event UUID which you can get from the query method.

zenoss_api evconsole_router EventsRouter (close|reopen|acknowledge|unacknowledge) '{"evids":["eventuuid"]}'
zenoss_api evconsole_router EventsRouter detail '{"evid":"eventuuid"}'

Working With Triggers

  • Return a JSON array of all triggers and their configurations
zenoss_api Events/triggers_router TriggersRouter getTriggers '{}'
  • Return a JSON array of just the trigger names
zenoss_api Events/triggers_router TriggersRouter getTriggerList '{}'
  • Get the details of one specific trigger (use getTriggerList to find the uuid)
zenoss_api Events/triggers_router TriggersRouter getTrigger '{"uuid":"0e3398a1-d732-404f-92d7-384c0917aa91"}'
  • Create a new trigger (with defaults)
zenoss_api Events/triggers_router TriggersRouter addTrigger '{"newId":"testtrigger"}'
  • Updating trigger parameters (use getTriggerList to find the uuid)
zenoss_api Events/triggers_router TriggersRouter updateTrigger '{"uuid":"314b77fa-f440-4e42-8701-ab0e92873eaf","enabled":true,"name":"testtrigger","rule":{"source":"(dev.production_state == 1000) and (evt.severity >= 4)"},"globalRead":false,"globalWrite":false,"globalManage":false,"users":[]}'

Working With Notifications

  • Return a JSON array of all notifications and their configurations
zenoss_api Events/triggers_router TriggersRouter getNotifications '{}'
  • Get the details of one specific notification
zenoss_api Events/triggers_router TriggersRouter getNotification '{"uid":"/zport/dmd/NotificationSubscriptions/Help_Desk_Master_Notification"}'

Find Template that is bound to a particular component

zenoss_api template_router TemplateRouter getObjTemplates '{"uid":"/zport/dmd/Devices/Storage/NetApp/devices/NETAPP2/os/filesystems/RES_LUN02_vol"}'|grep uid
'uid' => '/zport/dmd/Devices/Storage/NetApp/devices/NETAPP2/os/filesystems/RES_LUN02_vol/FileSystem',
zenoss_api template_router TemplateRouter getObjTemplates '{"uid":"/zport/dmd/Devices/Storage/NetApp/devices/NETAPP2/os/filesystems/RES_LUN03_vol"}'|grep uid
'uid' => '/zport/dmd/Devices/Storage/NetApp/rrdTemplates/FileSystem',

API documentation