[comment]: # ({7cef99ec-92f30379}) # 20 API [comment]: # ({/7cef99ec-92f30379}) [comment]: # ({d9e959c3-13405b49}) ### Überblick 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](http://www.jsonrpc.org/specification) und auf der [Startseite des JSON-Formats](http://json.org/). Weitere Informationen zur Integration von Zabbix-Funktionalität in Ihre Python-Anwendungen finden Sie unter [Python library for Zabbix](/devel/python). ::: noteclassic Der Benutzerzugriff in Zabbix, einschließlich Konfigurations- und Verlaufsdaten, hängt vom [Benutzertyp](/manual/config/users_and_usergroups/permissions#user-types), der zugewiesenen [Benutzerrolle](/manual/config/users_and_usergroups/permissions#user-roles) und den [Benutzergruppen](/manual/config/users_and_usergroups/usergroup) ab. ::: [comment]: # ({/d9e959c3-13405b49}) [comment]: # ({76e2a1dd-9cb56d09}) ### 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. ::: notetip 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. ::: [comment]: # ({/76e2a1dd-9cb56d09}) [comment]: # ({d3a7ab69-9cb2f5ca}) ### Ausführen von Anfragen Nachdem Sie das Frontend eingerichtet haben, können Sie Remote-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: ```bash 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 Version des von der API verwendeten 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 [Benachrichtigung](https://www.jsonrpc.org/specification#notification)). Wenn die Anfrage korrekt ist, sollte die von der API zurückgegebene Antwort wie folgt aussehen: ```json { "jsonrpc": "2.0", "result": "7.4.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. [comment]: # ({/d3a7ab69-9cb2f5ca}) [comment]: # ({c36376e5-ec5a9f60}) ### Beispiel-Workflow Im folgenden Abschnitt werden Sie einige Beispiele für die Verwendung genauer kennenlernen. [comment]: # ({/c36376e5-ec5a9f60}) [comment]: # ({17ec6118-ef3f5841}) #### Authentifizierung Um auf beliebige Daten in Zabbix zuzugreifen, müssen Sie entweder: - ein vorhandenes [API-Token](/manual/web_interface/frontend_sections/users/api_tokens) verwenden (erstellt im Zabbix Frontend oder mithilfe der [Token API](/manual/api/reference/token)); - ein Authentifizierungs-Token verwenden, das mit der Methode [user.login](/manual/api/reference/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: ```bash 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: ```json { "jsonrpc": "2.0", "result": "0424bd59b807674191e7d77572075f33", "id": 1 } ``` [comment]: # ({/17ec6118-ef3f5841}) [comment]: # ({d920bab8-37011a71}) #### Autorisierungsmethoden [comment]: # ({/d920bab8-37011a71}) [comment]: # ({78bcb6bc-130188f5}) ##### Ü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: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33' ``` ::: noteimportant Wenn bei Ihnen Authentifizierungsprobleme auftreten, siehe [Weiterleitung des Authorization-Headers](/manual/installation/known_issues#authorization-header-forwarding). ::: 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)). [comment]: # ({/78bcb6bc-130188f5}) [comment]: # ({8a583b03-8950965e}) ##### Ü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). [comment]: # ({/8a583b03-8950965e}) [comment]: # ({7f924528-f572ecc2}) #### 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](/manual/api/reference/host/get) verwenden, um die IDs, Host-Namen und Schnittstellen aller konfigurierten [Hosts](/manual/api/reference/host/object) abzurufen: Anfrage: ```bash 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 ``` ::: notetip `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 ```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: ```json { "jsonrpc": "2.0", "result": [ { "hostid": "10084", "host": "Zabbix server", "interfaces": [ { "interfaceid": "1", "ip": "127.0.0.1" } ] } ], "id": 2 } ``` ::: notetip Aus Leistungsgründen wird immer empfohlen, die Objekteigenschaften aufzulisten, die Sie abrufen möchten. So vermeiden Sie, alles abzurufen. ::: [comment]: # ({/7f924528-f572ecc2}) [comment]: # ({c9fda4ae-ee2c324f}) #### Erstellen eines neuen Datenpunkts Erstellen Sie nun einen neuen [Datenpunkt](/manual/api/reference/item/object) 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](/manual/api/reference/item/create) erfolgen: ```bash 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: ```json { "jsonrpc": "2.0", "result": { "itemids": [ "24759" ] }, "id": 3 } ``` ::: notetip Die Methode `item.create` sowie andere *create-Methoden* können auch Arrays von Objekten akzeptieren und mit einem API-Aufruf mehrere Datenpunkte erstellen. ::: [comment]: # ({/c9fda4ae-ee2c324f}) [comment]: # ({49a2cbe1-5ed44978}) #### Mehrere Auslöser erstellen Wenn *create-Methoden* also Arrays akzeptieren, können Sie mehrere [Auslöser](/manual/api/reference/trigger/object) hinzufügen, zum Beispiel diesen: ```bash 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: ```json { "jsonrpc": "2.0", "result": { "triggerids": [ "17369", "17370" ] }, "id": 4 } ``` [comment]: # ({/49a2cbe1-5ed44978}) [comment]: # ({07f914b6-aa174634}) #### Aktualisieren eines Datenpunkts Aktivieren Sie einen Datenpunkt, indem Sie seinen Status auf „0“ setzen: ```bash 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: ```json { "jsonrpc": "2.0", "result": { "itemids": [ "10092" ] }, "id": 5 } ``` ::: notetip Die Methode `item.update` sowie andere *Aktualisierungsmethoden* können auch Arrays von Objekten akzeptieren und mehrere Datenpunkte mit einem API-Aufruf aktualisieren. ::: [comment]: # ({/07f914b6-aa174634}) [comment]: # ({bfbd84bd-e217b4a2}) #### Mehrere Auslöser aktualisieren Aktivieren Sie mehrere Auslöser, indem Sie ihren Status auf "0" setzen: ```bash 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: ```json { "jsonrpc": "2.0", "result": { "triggerids": [ "13938", "13939" ] }, "id": 6 } ``` ::: notetip Dies ist die bevorzugte Methode zum Aktualisieren. Einige API-Methoden, wie `host.massupdate`, ermöglichen einfacheren Code. Es wird jedoch nicht empfohlen, diese Methoden zu verwenden, da sie in zukünftigen Versionen entfernt werden. ::: [comment]: # ({/bfbd84bd-e217b4a2}) [comment]: # ({a9952ff9-7665e280}) #### 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](/manual/api/reference/host/create) aufrufen, dabei jedoch den verpflichtenden Parameter `groups` weglassen: ```bash 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: ```json { "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. [comment]: # ({/a9952ff9-7665e280}) [comment]: # ({0de672ce-c1074d48}) ### 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](/manual/api/reference/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. ::: notetip Sie können alle an der API vorgenommenen Änderungen im [API-Änderungsprotokoll](/manual/api/changes) verfolgen. ::: [comment]: # ({/0de672ce-c1074d48}) [comment]: # ({77690bd2-dfd7315f}) ### 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](/manual/api/reference) zu werfen. [comment]: # ({/77690bd2-dfd7315f})