Die Zabbix API ermöglicht es Ihnen, die Konfiguration von Zabbix programmgesteuert abzurufen und zu ändern, und bietet Zugriff auf historische Daten. 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 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 codiert.

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-Funktionen in Ihre Python-Anwendungen finden Sie in der Python-Bibliothek für Zabbix.

Der Benutzerzugriff in Zabbix, einschließlich Konfiguration und historischer Daten, 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 verwendet, um neue Hosts zu erstellen. Historisch werden APIs manchmal auch als "Klassen" bezeichnet.

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

Anfragen ausführen

Nachdem 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 mit einem der folgenden Werte enthalten: application/json-rpc, application/json oder application/jsonrequest.

Das Anfrageobjekt muss die folgenden Eigenschaften enthalten:

jsonrpc - die vom API verwendete Version des JSON-RPC-Protokolls (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 eine 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.

Authentifizierung

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

ein vorhandenes API-Token verwenden, das im Zabbix-Frontend im Abschnitt Benutzer > API-Token erstellt wurde, oder das über die Token-API erstellt wurde.
ein Authentifizierungstoken verwenden, das mit der Methode user.login abgerufen wurde.

Wenn Sie beispielsweise durch die Anmeldung als normaler Admin-Benutzer ein neues Authentifizierungstoken erhalten möchten, 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 Anmeldedaten korrekt angegeben haben, sollte die von der API zurückgegebene Antwort das Benutzer-Authentifizierungstoken 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).

Beispiel-Workflow

Der folgende Abschnitt führt Sie ausführlicher durch mehrere Anwendungsbeispiele.

Hosts abrufen

Jetzt verfügen Sie über ein gültiges Benutzer-Authentifizierungstoken (in den folgenden Beispielen als Variable dargestellt), mit dem auf die Daten in Zabbix zugegriffen werden kann.
Sie können beispielsweise die Methode host.get verwenden, um die IDs, Hostnamen 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 Objekt-Eigenschaften aufzulisten, die Sie abrufen möchten.
Auf diese Weise vermeiden Sie, dass alles abgerufen wird.

Erstellen eines neuen Datenpunkts

Erstellen Sie nun einen neuen Datenpunkt auf dem Host "Zabbix server" unter Verwendung der Daten, die Sie aus der vorherigen host.get-Anfrage 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 methods können auch Arrays von Objekten akzeptieren und mehrere Datenpunkte mit einem einzigen API-Aufruf erstellen.

Erstellen mehrerer Auslöser

Wenn create methods 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":"Processor load is too high on {HOST.NAME}","expression":"last(/Linux server/system.cpu.load[percpu,avg1])>5"},{"description":"Too many processes on {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 einzigen API-Aufruf aktualisieren.

Aktualisieren mehrerer Auslöser

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 versuchen würden? Versuchen Sie, einen weiteren Host zu erstellen, indem Sie host.create aufrufen, dabei jedoch den obligatorischen 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, solche Fehler elegant 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 so anzupassen, dass versionsspezifische Funktionen verwendet werden.

Zabbix garantiert die Rückwärtskompatibilität von Funktionen innerhalb einer Hauptversion. Bei nicht rückwärtskompatiblen Änderungen zwischen Hauptversionen belässt Zabbix die alten Funktionen in der nächsten Version in der Regel als veraltet und entfernt sie erst in der darauffolgenden Version. Gelegentlich kann Zabbix Funktionen zwischen Hauptversionen auch ohne Rückwärtskompatibilität entfernen. Es ist wichtig, dass Sie sich niemals auf veraltete Funktionen verlassen und so schnell wie möglich auf neuere Alternativen migrieren.

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

Weiterführende Literatur

Nun verfügen Sie über genügend Wissen, um mit der Zabbix API zu arbeiten. Bleiben Sie jedoch nicht hier stehen. Für weiterführende Informationen empfehlen wir Ihnen, sich die Liste der verfügbaren APIs anzusehen.

What’s next?

Methodenreferenz

Docs

16 API

Übersicht