Working with the JSON API

From Zenoss Wiki
Jump to: navigation, search

API documentation for the Zenoss JSON API. The accompanying files for this document include a shell script called json_api.sh. 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

API documentation for the Zenoss 5.X API documentation for the Zenoss 4.X