Working with the JSON API

From Zenoss Wiki
This is the approved revision of this page, as well as being the most recent.
Jump to: navigation, search

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.

There is an updated version for Zenoss 5 now too. v5 json_api.sh

Once you have it, source it at your shell to get the zenoss_api function:

$ source json_api.sh

Examples

Conventional Naming of "Routers" in examples below

You'll see in the example below reference e.g. device_router. 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:

Products.Zuul.routers.device -> device_router
Products.Zuul.routers.users -> users_router
Products.Zuul.routers.triggers -> triggers_router.

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

zenoss_api users_router UsersRouter addUser '{"id":"myusername","password":"mypassword","email":"my@email.address","roles":["ZenUser"]}'

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

List of Router Endpoints

application_router
detailnav_router
devicedumpload_router
devicemanagement_router
device_router
evclasses_router
evconsole_router
host_router
introspection_router
jobs_router
manufacturers_router
messaging_router
mib_router
monitor_router
network_6_router
network_router
process_router
properties_router
report_router
search_router
service_router
settings_router
template_router
triggers_router
users_router
zenpack_router

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.

#!/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\":\"\"}"
}