Die Zabbix-API ermöglicht es Ihnen, die Konfiguration von Zabbix programmgesteuert abzurufen und zu ändern, und bietet Zugriff auf Verlaufsdaten. Sie wird häufig verwendet, um:

neue Anwendungen zu erstellen, die mit Zabbix arbeiten;
Zabbix in Software von Drittanbietern zu integrieren;
Routineaufgaben zu automatisieren.

Die Zabbix-API ist eine HTTP-basierte API und wird als Teil des Web-Frontend ausgeliefert. Sie verwendet das JSON-RPC-2.0-Protokoll, was zwei Dinge bedeutet:

die API besteht aus einer Reihe separater Methoden;
Anfragen und Antworten zwischen den Clients und der API werden im JSON-Format kodiert.

Weitere Informationen zum Protokoll und zu JSON finden Sie in der JSON-RPC-2.0-Spezifikation und auf der Startseite des JSON-Formats.

Weitere Informationen zur Integration von Zabbix-Funktionalität in Ihre Python-Anwendungen finden Sie unter Python library for Zabbix.

Der Benutzerzugriff in Zabbix, einschließlich Konfigurations- und Verlaufsdaten, hängt vom Benutzertyp, der zugewiesenen Benutzerrolle und den Benutzergruppen ab.

Struktur

Die API besteht aus einer Reihe von Methoden, die nominell in separate APIs gruppiert sind. Jede der Methoden führt eine bestimmte Aufgabe aus. Beispielsweise gehört die Methode host.create zur host API und wird zum Erstellen neuer Hosts verwendet. In der Vergangenheit wurden APIs manchmal als "Klassen" bezeichnet.

Die meisten APIs enthalten mindestens vier Methoden: get, create, update und delete zum Abrufen, Erstellen, Aktualisieren und Löschen von Daten, aber einige APIs können auch einen völlig anderen Satz von Methoden bereitstellen.

Anfragen ausführen

Sobald Sie das Frontend eingerichtet haben, können Sie entfernte HTTP-Anfragen verwenden, um die API aufzurufen. Dazu müssen Sie HTTP-POST-Anfragen an die Datei api_jsonrpc.php senden, die sich im Frontend-Verzeichnis befindet. Wenn Ihr Zabbix-Frontend beispielsweise unter https://example.com/zabbix installiert ist, kann eine HTTP-Anfrage zum Aufruf der Methode apiinfo.version wie folgt aussehen:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'

Die Anfrage muss den Header Content-Type auf einen der folgenden Werte gesetzt haben: application/json-rpc, application/json oder application/jsonrequest.

Das Anfrageobjekt muss die folgenden Eigenschaften enthalten:

jsonrpc - die Version des JSON-RPC-Protokolls, die von der API verwendet wird (die Zabbix-API implementiert JSON-RPC-Version 2.0);
method - die aufgerufene API-Methode;
params - die Parameter, die an die API-Methode übergeben werden;
id - eine beliebige Kennung der Anfrage (wenn sie weggelassen wird, behandelt die API die Anfrage als Benachrichtigung).

Wenn die Anfrage korrekt ist, sollte die von der API zurückgegebene Antwort wie folgt aussehen:

{
    "jsonrpc": "2.0",
    "result": "8.0.0",
    "id": 1
}

Das Antwortobjekt enthält wiederum die folgenden Eigenschaften:

jsonrpc - die Version des JSON-RPC-Protokolls;
result - die von der Methode zurückgegebenen Daten;
id - eine Kennung der entsprechenden Anfrage.

Beispiel-Workflow

Im folgenden Abschnitt werden Sie einige Beispiele für die Verwendung genauer kennenlernen.

Authentifizierung

Um auf beliebige Daten in Zabbix zuzugreifen, müssen Sie entweder:

ein vorhandenes API-Token verwenden (erstellt im Zabbix Frontend oder mithilfe der Token API);
ein Authentifizierungs-Token verwenden, das mit der Methode user.login abgerufen wurde.

Wenn Sie beispielsweise ein neues Authentifizierungs-Token erhalten möchten, indem Sie sich als standardmäßiger Admin-Benutzer anmelden, würde eine JSON-Anfrage wie folgt aussehen:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"user.login","params":{"username":"Admin","password":"zabbix"},"id":1}'

Wenn Sie die Zugangsdaten korrekt angegeben haben, sollte die von der API zurückgegebene Antwort das Benutzerauthentifizierungs-Token enthalten:

{
    "jsonrpc": "2.0",
    "result": "0424bd59b807674191e7d77572075f33",
    "id": 1
}

Autorisierungsmethoden

Über den Header "Authorization"

Alle API-Anfragen erfordern eine Authentifizierung oder ein API-Token. Sie können die Zugangsdaten bereitstellen, indem Sie den Header Authorization in der Anfrage verwenden:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33'

Wenn bei Ihnen Authentifizierungsprobleme auftreten, siehe Weiterleitung des Authorization-Headers.

Die Zabbix API akzeptiert Header ohne Beachtung der Groß-/Kleinschreibung (z. B. werden authorization, Authorization und AUTHORIZATION gleich behandelt).

Der Authorization-Header wird in Cross-Origin-Anfragen unterstützt (CORS).

Über das Zabbix-Cookie

Ein „zbx_session“-Cookie wird verwendet, um eine API-Anfrage aus der Zabbix UI zu autorisieren, die mit JavaScript ausgeführt wird (aus einem Modul oder einem benutzerdefinierten Widget).

Hosts abrufen

Jetzt haben Sie ein gültiges Benutzerauthentifizierungs-Token (in den folgenden Beispielen als Variable dargestellt), das für den Zugriff auf die Daten in Zabbix verwendet werden kann. Sie können zum Beispiel die Methode host.get verwenden, um die IDs, Host-Namen und Schnittstellen aller konfigurierten Hosts abzurufen:

Anfrage:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data @data.json

data.json ist eine Datei, die eine JSON-Abfrage enthält. Anstelle einer Datei können Sie die Abfrage im Argument --data übergeben.

data.json

{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "output": [
            "hostid",
            "host"
        ],
        "selectInterfaces": [
            "interfaceid",
            "ip"
        ]
    },
    "id": 2
}

Das Antwortobjekt enthält die angeforderten Daten zu den Hosts:

{
    "jsonrpc": "2.0",
    "result": [
        {
            "hostid": "10084",
            "host": "Zabbix server",
            "interfaces": [
                {
                    "interfaceid": "1",
                    "ip": "127.0.0.1"
                }
            ]
        }
    ],
    "id": 2
}

Aus Leistungsgründen wird immer empfohlen, die Objekteigenschaften aufzulisten, die Sie abrufen möchten. So vermeiden Sie, alles abzurufen.

Erstellen eines neuen Datenpunkts

Erstellen Sie nun einen neuen Datenpunkt auf dem Host „Zabbix server“ mithilfe der Daten, die Sie aus der vorherigen Anfrage host.get erhalten haben. Dies kann mit der Methode item.create erfolgen:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"item.create","params":{"name":"Free disk space on /home/joe/","key_":"vfs.fs.size[/home/joe/,free]","hostid":"10084","type":0,"value_type":3,"interfaceid":"1","delay":30},"id":3}'

Eine erfolgreiche Antwort enthält die ID des neu erstellten Datenpunkts, die verwendet werden kann, um in den folgenden Anfragen auf den Datenpunkt zu verweisen:

{
    "jsonrpc": "2.0",
    "result": {
        "itemids": [
            "24759"
        ]
    },
    "id": 3
}

Die Methode item.create sowie andere create-Methoden können auch Arrays von Objekten akzeptieren und mit einem API-Aufruf mehrere Datenpunkte erstellen.

Mehrere Auslöser erstellen

Wenn create-Methoden also Arrays akzeptieren, können Sie mehrere Auslöser hinzufügen, zum Beispiel diesen:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"trigger.create","params":[{"description":"Die Prozessorlast ist auf {HOST.NAME} zu hoch","expression":"last(/Linux server/system.cpu.load[percpu,avg1])>5"},{"description":"Zu viele Prozesse auf {HOST.NAME}","expression":"avg(/Linux server/proc.num[],5m)>300"}],"id":4}'

Die erfolgreiche Antwort enthält die IDs der neu erstellten Auslöser:

{
    "jsonrpc": "2.0",
    "result": {
        "triggerids": [
            "17369",
            "17370"
        ]
    },
    "id": 4
}

Aktualisieren eines Datenpunkts

Aktivieren Sie einen Datenpunkt, indem Sie seinen Status auf „0“ setzen:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"item.update","params":{"itemid":"10092","status":0},"id":5}'

Die erfolgreiche Antwort enthält die ID des aktualisierten Datenpunkts:

{
    "jsonrpc": "2.0",
    "result": {
        "itemids": [
            "10092"
        ]
    },
    "id": 5
}

Die Methode item.update sowie andere Aktualisierungsmethoden können auch Arrays von Objekten akzeptieren und mehrere Datenpunkte mit einem API-Aufruf aktualisieren.

Mehrere Auslöser aktualisieren

Aktivieren Sie mehrere Auslöser, indem Sie ihren Status auf „0“ setzen:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"trigger.update","params":[{"triggerid":"13938","status":0},{"triggerid":"13939","status":0}],"id":6}'

Die erfolgreiche Antwort enthält die IDs der aktualisierten Auslöser:

{
    "jsonrpc": "2.0",
    "result": {
        "triggerids": [
            "13938",
            "13939"
        ]
    },
    "id": 6
}

Fehlerbehandlung

Bis zum jetzigen Zeitpunkt hat alles, was Sie ausprobiert haben, einwandfrei funktioniert. Aber was würde passieren, wenn Sie einen fehlerhaften Aufruf an die API senden würden? Versuchen Sie, einen weiteren Host zu erstellen, indem Sie host.create aufrufen, dabei jedoch den verpflichtenden Parameter groups weglassen:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"host.create","params":{"host":"Linux server","interfaces":[{"type":1,"main":1,"useip":1,"ip":"192.168.3.1","dns":"","port":"10050"}]},"id":7}'

Die Antwort enthält dann eine Fehlermeldung:

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Invalid params.",
        "data": "No groups for host \"Linux server\"."
    },
    "id": 7
}

Wenn ein Fehler aufgetreten ist, enthält das Antwortobjekt anstelle der Eigenschaft result die Eigenschaft error mit den folgenden Daten:

code - ein Fehlercode;
message - eine kurze Fehlerzusammenfassung;
data - eine ausführlichere Fehlermeldung.

Fehler können in verschiedenen Fällen auftreten, zum Beispiel bei der Verwendung falscher Eingabewerte, bei einem Sitzungs-Timeout oder beim Versuch, auf nicht vorhandene Objekte zuzugreifen. Ihre Anwendung sollte in der Lage sein, diese Arten von Fehlern zuverlässig zu behandeln.

API-Versionen

Um die API-Versionierung zu vereinfachen, entspricht seit Zabbix 2.0.4 die Version der API der Version von Zabbix selbst. Sie können die Methode apiinfo.version verwenden, um die Version der API zu ermitteln, mit der Sie arbeiten. Dies kann nützlich sein, um Ihre Anwendung für die Verwendung versionsspezifischer Funktionen anzupassen.

Zabbix garantiert die Abwärtskompatibilität von Funktionen innerhalb einer Hauptversion. Wenn zwischen Hauptversionen nicht abwärtskompatible Änderungen vorgenommen werden, lässt Zabbix die alten Funktionen in der Regel in der nächsten Version als veraltet bestehen und entfernt sie erst in der darauffolgenden Version. Gelegentlich kann Zabbix jedoch Funktionen zwischen Hauptversionen entfernen, ohne irgendeine Form von Abwärtskompatibilität bereitzustellen. Es ist wichtig, dass Sie sich niemals auf veraltete Funktionen verlassen und so bald wie möglich auf neuere Alternativen migrieren.

Sie können alle an der API vorgenommenen Änderungen im API-Änderungsprotokoll verfolgen.

Weiterführende Lektüre

Jetzt verfügen Sie über genügend Wissen, um mit der Zabbix-API zu arbeiten. Hören Sie hier jedoch nicht auf. Für weiterführende Informationen empfiehlt es sich, einen Blick auf die Liste der verfügbaren APIs zu werfen.

What’s next?

Anhang 1. Referenzkommentar

Docs

18 API

Überblick