Zabbix API

Was ist die Zabbix-API?

Die Zabbix-API ist eine Schnittstelle, die es Ihnen ermöglicht, Zabbix zu erweitern und Ihren Bedürfnissen anzupassen. Die API wird u.a. für folgende Zwecke genutzt:

  • Applikationen wie Mobile-Apps für Zabbix entwickeln
  • Zabbix in andere Software zu integrieren
  • Zabbix in sogenannte Automatisierungssoftware wie Puppet, Salt-Stack oder cfengine zu integrieren
  • Aufgaben zu automatisieren
  • eigene Informationsbildschirme zu gestalten

Die Zabbix-API ist webbasiert und fester Bestandteil des Zabbix-Webfrontends. Per HTTP(s) können Sie die JSON-RPC-API erreichen. Anfragen müssen json-kodiert sein. Die Antwort der API ist ebenfalls json-kodiert.

Die Kommunikation mit der API besteht immer aus zwei HTTP-Anfragen. Die erste Anfrage sendet die Zugangsdaten bestehend aus Benutzername und Passwort. Die API Liefert eine Authentifizierungs-ID zurück. Unter Angabe der Authentifizierungs-ID können dann in der zweiten Anfrage "Kommandos" abgesetzt werden. Aufgrund dieses Umstandes ist es sehr kompliziert, Anfragen mit Kommadozeilenwerkzeugen wie wegt oder curl an die Zabbix-API zu schicken.

Alle Benutzer, die Zugriff auf das Zabbix-Webinterface haben, sind auch berechtigt, mit der API zu kommunizieren. Die pro Nutzer oder Nutzergruppe eingestellten Berechtigungen gelten auch für alle Zugriffe auf die API.

Anfragen an die API müssen immer eine Methode benennen, welche auf der API ausgeführt werden soll. Je nach Spezifikation der Methode müssen zusätzliche Parameter übergeben werden. Eine Liste und Beschreibung aller Methoden finden Sie in der offiziellen API-Dokumentation.

Kommunikation mit der API

Ein Perl-Beispiel

Nachfolgend finden Sie ein einfaches Beispiel, das die Funktionsweise der Zabbix-API erläutert. Die Antworten der API werden über das Perl-Modul Data::Dumper einfach auf der Konsole ausgegeben.

Installieren Sie das Perl-Modul Json-RPC-Client.

apt-get install libjson-rpc-perl           # Debian, Ubuntu
yum install perl-JSON-RPC perl-Data-Dumper # Red Hat/CentOS

Für CentOS und Red Hat Version 6 steht kein fertiges Paket mit dem Perl-Modul JSON::RPC::Client zur Verfügung. Installieren Sie das Modul stattdessen per CPAN.

yum install perl-CGI perl-YAML perl-CPAN perl-Data-Dumper
cpan App::cpanminus
cpan JSON::RPC::Client

Speichern Sie anschließend das folgende Beispiel unter api-example.pl und führen Sie den Code mit perl api-example.pl aus. Falls Sie das Programm nicht auf dem Zabbix-Server ausführen, müssen Sie noch die URL zum Zabbix-Webfrontend anpassen.

#!/usr/bin/perl
 
use strict;
use warnings;
use JSON::RPC::Legacy::Client;
use Data::Dumper;
 
# Authenticate yourself
my $client = new JSON::RPC::Legacy::Client;
my $url = 'http://localhost/zabbix/api_jsonrpc.php';
my $authID;
my $response;
 
my $json = {
        jsonrpc => "2.0",
        method => "user.login",
        params => {
                user => "admin",
                password => "zabbix" },
        id => 1
};
 
$response = $client->call($url, $json);
# Check if response was successful
die "Authentication failed\n" unless $response->content->{'result'};
# Print full response to console
print Dumper($response);
 
# Extract AuthID from returned object.
$authID = $response->content->{'result'};
print "Authentication successful. Auth ID: " . $authID . "\n";

Wenn die Authentifizierung an der Zabbix-API erfolgreich war, erhalten Sie in der Antwort ein Objekt, welches die AuthID für alle weiteren Anfragen an die API enthält.

Erweitern Sie die Datei api-example.pl mit den folgenden Zeilen:

# Get list of all hosts using authID
$json = {
        jsonrpc=> '2.0',
        method => 'host.get',
        params => {
                output => ['hostid','name'], # get only host id and host name
                sortfield => 'name' },       # sort by host name
        id => 1,
        auth => "$authID",
        };
$response = $client->call($url, $json);
# Check if response was successful
die "host.get failed\n" unless $response->content->{result};
print Dumper($response);
Übernehmen Sie die Methoden aus der Zabbix-Dokumentation in Ihren Perl-Code.

Wenn Sie die Liste der Hosts in einer schöneren Formatierung ausgeben möchten, können Sie die Zeilen print Dumper($response); auskommentieren und am Ende der Datei nachfolgende Codezeilen einfügen:

print "List of hosts\n-----------------------------\n";
foreach my $host (@{$response->content->{result}}) {
	print "Host ID: ".$host->{hostid}." Host: ".$host->{name}."\n";
}

Die Ausgabe sollte dann ungefähr wie folgt aussehen:

[root@vm173 ~]# perl api-example.pl 
Authentication successful. Auth ID: 83a74eb7e07b9f35f4b5228ff5f21eeb
List of hosts
-----------------------------
Host ID: 10105 Host: D-Link Smart Switch
Host ID: 10106 Host: Dell ESX Server
Host ID: 10107 Host: Intel Server
Host ID: 10109 Host: Webserver
Host ID: 10084 Host: Zabbix server

PHP-Klassenbibliothek

Auch für die Programmiersprache PHP existieren fertige Klassen, so dass Sie bequem auf die Methoden der Zabbix-API zugreifen können. Laden Sie sich die PHP-Klassenbibliothek PHPZabbixAPI von GitHub herunter.

wget "https://github.com/confirm/PhpZabbixApi/archive/v2.4.5.zip"
unzip v2.4.5.zip */build/*
mv PhpZabbixApi-2.4.5/build/* .
rm -rf PhpZabbixApi-2.4.5
ls *.php

Alle Methoden der Zabbix-API sind als Methoden in der Klasse ZabbixApi enthalten. Die PHP-Methoden entsprechen den in der Dokumentation genannten Methoden, werden aber in Camelcase und ohne Punkt geschrieben. Aus host.get wird hostGet().

Die Optionen geben Sie nicht json-kodiert, sondern als PHP-Arrays an. Ein Beispiel:

# Raw json
"params": {
        "output": "extend",
        "filter": {
            "host": ["Zabbix server" ]
        }

# PHP Arrays
$params = array('output' => 'extend',
                'filter' => array('host' => 'Zabbix server')
                )
Übertragung der Dokumentation in PHP-Code

Beispiel 1: Trigger abrufen

Im folgenden Beispiel ruft das PHP-Skript mit wenigen Zeilen Code alle Trigger ab, die sich im Status "Problem" befinden.

<?php
require 'ZabbixApi.class.php'; // load ZabbixApi
use ZabbixApi\ZabbixApi;
 
$username = 'Admin';
$password = 'zabbix';
$api_url  = 'http://localhost/zabbix/api_jsonrpc.php';
 
try {
    // connect to Zabbix-API
    $api = new ZabbixApi($api_url, $username, $password);
 
    $params = array(   'monitored'         =>TRUE,
                        'active'            =>TRUE, 
                        'only_true'         =>TRUE,
                        'expandData'        =>TRUE,
                        'expandDescription' => TRUE,
                        'expandExpression'  => FALSE,
                        'selectFunctions'   => 'extend',
                        'output'            => 'extend', 
                        'sortfield'         => 'priority' );
 
    $triggers = $api->triggerGet($params); // get data from api
 
    foreach($triggers as $trigger)  {       // loop through the returned data
        print_r($trigger);
        echo "\n";
    }
 
} catch(Exception $e) {
 
    // Exception in ZabbixApi catched
    echo $e->getMessage();
}
?>

Beispiel 2: Einen neuen Host anlegen

Im nachfolgenden Beispiel wird per Zabbix-API ein neuer Host angelegt.

<?php
// load ZabbixApi
require 'ZabbixApi.class.php';
use ZabbixApi\ZabbixApi;
 
$username = 'Admin';
$password = 'zabbix';
$api_url  = 'http://localhost/zabbix/api_jsonrpc.php';
 
try {
    // connect to Zabbix-API
    $api = new ZabbixApi($api_url, $username, $password);
 
    $interfaces = array('type' => '1',
                        'main' => '1',
                        'useip' => '1',
                        'ip'    => '192.168.152.200',
                        'dns'   => '',
                        'port'  => '10050' );
 
    $params = array(   'host'              => 'Ein super Host',
                        'interfaces'        => $interfaces,
                        'groups'            => array(array('groupid' => '5')),
                    );
 
    $api_return = $api->hostCreate($params); // get data from api
 
    foreach($api_return as $item)  {       // loop through the returned data
        echo "<pre>".print_r($item,TRUE)."</pre>";
        echo "\n";
    }
 
} catch(Exception $e) {
 
    // Exception in ZabbixApi catched
    echo $e->getMessage();
}

Ein Python-Beispiel

Für die Programmiersprache Python existieren mehrere Klassenbibliotheken, die das Abfragen der Zabbix-API vereinfachen. Im folgenden Beispiel werden die Klassen aus dem pyzabbix-Projekt (https://github.com/lukecyca/pyzabbix/) verwendet.

Die Klassenbibliotheken können Sie einfach per PIP installieren:

pip install pyzabbix

Alternativ laden Sie den Quellcode in Form des Master-ZIP-Files von GitHub herunter und installieren Sie dann die Bibliotheken wie folgt:

unzip pyzabbix-master.zip
cd pyzabbix-master
python setup.py install

Nun können Sie folgendes Beispiel anlegen, welches alle Trigger auflistet, die sich im Status „Problem“ befinden:

#!/usr/bin/env python
"""
Shows a list of all current issues (AKA tripped triggers)
"""
from pyzabbix import ZabbixAPI
 
# The hostname at which the Zabbix web interface is available
ZABBIX_SERVER = 'http://localhost/zabbix/api_jsonrpc.php'
 
zapi = ZabbixAPI(ZABBIX_SERVER)
 
# Login to the Zabbix-API (User/Login)
zapi.login('Admin', 'zabbix')
 
# Get a list of all issues (AKA tripped triggers)
triggers = zapi.trigger.get(only_true=1,
    skipDependent=1,
    monitored=1,
    active=1,
    output='extend',
    expandDescription=1,
    expandData='host',
)
 
# Do another query to find out which issues are Unacknowledged
unack_triggers = zapi.trigger.get(only_true=1,
    skipDependent=1,
    monitored=1,
    active=1,
    output='extend',
    expandDescription=1,
    expandData='host',
    withLastEventUnacknowledged=1,
)
unack_trigger_ids = [t['triggerid'] for t in unack_triggers]
for t in triggers:
    t['unacknowledged'] = True if t['triggerid'] in unack_trigger_ids\
    else False
 
# Print a list containing only "tripped" triggers
for t in triggers:
    if int(t['value']) == 1:
        print("{0} - {1} {2}".format(
            t['host'],
            t['description'],
            '(Unack)' if t['unacknowledged'] else '')
        )

Die Klasse zapi stellt Methoden bereit, mit denen Sie direkt auf die Methoden der API zugreifen können. Die von der Zabbix-API erwarteten Parameter übergeben Sie der Python-Methode als Python-Dictionary.