See www.zabbix.com for the official Zabbix site.

Docs/howto/Perl Zabbix::Tiny API

From Zabbix.org
Jump to: navigation, search

The Perl module Zabbix::Tiny was created as a simple wrapper to eliminate boilerplate that might otherwise need to be created when interfacing with the Zabbix API. Login to the Zabbix server is handled with the constructor. There is no need to track the auth, id, or json values for the JSON-RPC message, as these are handled by the module. This leaves the programmer free to concentrate only on the Zabbix method and it's parameters. The user.logout method is implemented in the object destructor as well, so there should be no need to explicitly logout of Zabbix.

This module was developed against Zabbix 2.4, and is expected to work with Zabbix 2.2, and likely 2.0 as well. It has also been successfully used with Zabbix 1.8 and 3.0. Please refer to the API section of the Zabbix manual for details on its methods.

Installation

Zabbix::Tiny can be installed from CPAN, via the usual methods. For example:

#> cpan Zabbix::Tiny

Usage

use strict;
use warnings;
use Zabbix::Tiny;

my $username = 'zabbix_user';
my $password = 'secretpassword';
my $url = 'https://zabbix.domain.com/zabbix/api_jsonrpc.php';

my $zabbix = Zabbix::Tiny->new(
    server   => $url,
    password => $password,
    user     => $username
);

my $hosts = $zabbix->do(
    'host.get',  # First argument is the Zabbix API method
    {
        # Remaining parameters to 'do' are the params for the zabbix method.
        output    => [qw(hostid name host)],  
        monitored => 1,
        limit     => 2,
        ## Any other params desired
    }
);

# Print some of the retrieved information.
for my $host (@$hosts) {
    print "Host ID: $host->{hostid} - Display Name: $host->{name}\n";
}

The above example retrieves the hostid, name (display name), and host (Zabbix host name) for all enabled hosts from the Zabbix server as an arrayref called $hosts using the host.get method. The $hosts array ref is then looped though to print the host ID, and display name for the hosts retrieved.

Methods

Primary Methods

new
my $zabbix = Zabbix::Tiny->new( server => $url, password => $password, user => $username, [ssl_opts => {%ssl_opts}]);

The constructor requires server, user, and password. It will create the Zabbix::Tiny object, and log in to the server all at once. The ssl_opts argument can be set to the LWP::UserAgent ssl_opts attribute when connecting to https with a self-signed or otherwise un-trusted certificate (see note about untrusted certificates below).

do
my $hosts = $zabbix->do('zabbix.method', {%params});
my $hosts = $zabbix->do('zabbix.method', [@params]);
my $hosts = $zabbix->do('zabbix.method', %params); ## Deprecated

This will execute any defined Zabbix method, with the corresponding params. Refer to the Zabbix manual for a list of available methods. If the Zabbix method is of a *.get flavor, the return is an arrayref data structure containing the response from the Zabbix server. Starting with v1.05, it is preferred to pass parameters as a hashref or an arrayref, since a few Zabbix API methods take an array, rather than a hash of parameters. Params as a hash are still supported for backwards compatibility.

Debugging Methods

The Zabbix::Tiny do method contains a very succinct array ref that should contain only the data needed for interacting with the Zabbix server, so there should be little need to worry about serializing JSON, managing the Zabbix auth token, etc., however these methods are provided for convenience.

my $auth = $zabbix->auth;

The main purpose of this module is to hide away the need to track the authentication token in the script. With that in mind, the token used can be retrieved with this method if needed.

my $json_request = $zabbix->json_request;

Used to retrieve the last raw JSON message sent to the Zabbix server, including the "jsonrpc", "id", and "auth".

my $json_response = $zabbix->json_response;

Used to retrieve the last raw json message from the zabbix server, including the "jsonrpc", "id", and "auth".

my $verbose = $zabbix->last_response;

Similar to json_response, but the last response message as a perl data structure (hashref).

my $post_response = $zabbix->post_response;

The HTTP::Response from the Zabbix server for the most recent request.

To Do:

Add some more useful real-world examples of usage.