This is a translation of the original English documentation page. Help us make it better.

Sidebar

19. API

Overzicht

Met de Zabbix API kunt u programmatisch het ophalen en wijzigen van de Zabbix configuratie en biedt toegang tot historische gegevens. Het is veel gebruikt om:

  • Nieuwe applicaties maken om met Zabbix te werken;
  • Integreren van Zabbix met software van derden;
  • Automatiseren van routinetaken.

De Zabbix API is een webgebaseerde API en wordt geleverd als onderdeel van het web server. Het maakt gebruik van het JSON-RPC 2.0-protocol, wat twee dingen betekent:

  • De API bestaat uit een reeks afzonderlijke methoden;
  • Verzoeken en antwoorden tussen de clients en de API zijn gecodeerd met behulp van het JSON-formaat.

Meer info over het protocol en JSON is te vinden in de JSON-RPC 2.0 specificatie en de JSON format homepage.

Structuur

De API bestaat uit een aantal methoden die nominaal zijn gegroepeerd in afzonderlijke API's. Elk van de methoden voert een specifieke taak uit. Voor de methode host.create hoort bijvoorbeeld bij de host API en wordt gebruikt om nieuwe hosts te maken. Historisch gezien worden API's soms aangeduid als: "klassen".

De meeste API's bevatten ten minste vier methoden: 'get', create, update en delete voor het ophalen, creëren, bijwerken en respectievelijk het verwijderen van gegevens, maar sommige van de API's kunnen een volledig verschillende set methoden ondersteunen.

Verzoeken uitvoeren

Nadat u de frontend heeft ingesteld, kunt u externe HTTP-verzoeken gebruiken om de API aan te roepen. Om dat te doen, moet u HTTP POST-verzoeken naar het api_jsonrpc.php bestand in de frontend directory. Bijvoorbeeld, als uw Zabbix-frontend is geïnstalleerd onder http://company.com/zabbix, ken het HTTP-verzoek om de apiinfo.version-methode aan te roepen er als volgt uitzien:

POST http://company.com/zabbix/api_jsonrpc.php HTTP/1.1
       Content-Type: application/json-rpc

       {"jsonrpc":"2.0","method":"apiinfo.version","id":1,"auth":null,"params":{}}

Het verzoek moet de kop 'Content-Type' hebben ingesteld op een van deze waarden: application/json-rpc, application/json of application/jsonrequest.

U kunt elke HTTP-client of een JSON-RPC-test tool gebruiken om API-verzoeken handmatig uit te voeren, maar voor het ontwikkelen van applicaties stellen we voor dat u een van de door de gemeenschap onderhouden bibliotheken gebruikt.

Voorbeeld workflow

In het volgende gedeelte wordt u door enkele gebruiksvoorbeelden geleid in meer detail.

Authenticatie

Voordat je toegang hebt tot gegevens in Zabbix, moet je inloggen en verkrijg een authenticatie token. Dit kan met behulp van de user.login methode. Laten we veronderstellen dat u als standaard Admin-gebruiker wilt inloggen. Uw JSON-verzoek zal er dan als volgt uitzien:

{
           "jsonrpc": "2.0",
           "method": "user.login",
           "params": {
               "user": "Admin",
               "password": "zabbix"
           },
           "id": 1,
           "auth": null
       }

Laten we het aanvraag object eens nader bekijken. Het heeft de volgende eigenschappen:

  • jsonrpc - de versie van het JSON-RPC-protocol dat door de API wordt gebruikt; de Zabbix API implementeert JSON-RPC versie 2.0;
  • method - de API-methode die wordt aangeroepen;
  • params - parameters die worden doorgegeven aan de API-methode;
  • id - een willekeurige identifier van het verzoek;
  • auth - een token voor gebruikers authenticatie; aangezien we er nog geen hebben, het is ingesteld op 'null'.

Als u de inloggegevens correct hebt opgegeven, bevat het antwoord van de API call het token voor gebruikersverificatie:

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

Het respons object bevat op zijn beurt de volgende eigenschappen:

  • jsonrpc - nogmaals, de versie van het JSON-RPC-protocol;
  • result - de gegevens die door de methode worden geretourneerd;
  • id - identifier van het corresponderende verzoek.

Hosts ophalen

We hebben nu een geldig token voor gebruikersverificatie die kan worden gebruikt om toegang te krijgen de gegevens in Zabbix. Laten we bijvoorbeeld de host.get methode gebruiken om de ID's, hostnamen en interfaces van alle geconfigureerde hosts op te halen:

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

::: noteimportant Merk op dat de eigenschap auth nu is ingesteld op de authenticatie token dat we hebben verkregen door de user.login methode. :::

Het respons object zal de gevraagde gegevens over de hosts bevatten:

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

Om prestatieredenen raden we aan om altijd om alleen objecteigenschappen die u wilt op te halen. Vermijd het ophalen alles.

Een nieuw item maken

Laten we een nieuw item maken op "Zabbix server" met behulp van de gegevens die we hebben verkregen van het vorige host.get verzoek. Dit kan met behulp van de item.create methode:

{
           "jsonrpc": "2.0",
           "methode": "item.create",
           "params": {
               "name": "Vrij schijfruimte op /home/joe/",
               "key_": "vfs.fs.size[/home/joe/,free]",
               "hostid": "10084",
               "type": 0,
               "value_type": 3,
               "interfaceid": "1",
               "delay": 30
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 3
       }

Een succesvol antwoord bevat de ID van het nieuw gemaakte item, die kan worden gebruikt om naar het item te verwijzen in de volgende verzoeken:

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

De item.create-methode en andere aanmaakmethoden kunnen ook arrays van objecten accepteren en meerdere items maken met één API call.

Meerdere triggers maken

Dus als maakmethoden arrays accepteren, kunnen we meerdere triggers als volgt toevoegen:

{
           "jsonrpc": "2.0",
           "method": "trigger.create",
           "params": [
               {
                   "description": "De processorbelasting is te hoog op {HOST.NAME}",
                   "expression": "last(/Linux server/system.cpu.load[percpu,avg1])>5",
               },
               {
                   "description": "Te veel processen op {HOST.NAME}",
                   "expression": "avg(/Linux-server/proc.num[],5m)>300",
               }
           ],
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 4
       }

Een succesvol antwoord bevat de ID's van de nieuw aangemaakte triggers:

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

Een item bijwerken

Schakel een item in, dat wil zeggen, stel de status in op "0":

{
           "jsonrpc": "2.0",
           "method": "item.update",
           "params": {
               "itemid": "10092",
               "status": 0
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 5
       }

Een succesvolle reactie bevat de ID van het bijgewerkte item:

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

De item.update-methode en andere update-methoden kunnen ook arrays van objecten accepteren en meerdere items bijwerken met één API call.

Meerdere triggers bijwerken

Schakel meerdere triggers in, dat wil zeggen, stel hun status in op 0:

{
           "jsonrpc": "2.0",
           "method": "trigger.update",
           "params": [
               {
                   "triggerid": "13938",
                   "status": 0
               },
               {
                   "triggerid": "13939",
                   "status": 0
               }
           ],
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 6
       }

Een succesvolle reactie bevat de ID's van de bijgewerkte triggers:

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

Dit is de voorkeursmethode voor bijwerken. Sommige API methoden zoals host.massupdate maken het mogelijk om meer eenvoudige code te schrijven, maar het is niet aanbevolen om deze methoden te gebruiken, omdat ze worden verwijderd in de toekomstige releases.

Fout afhandeling

Tot nu toe heeft alles wat we hebben geprobeerd goed gewerkt. Maar wat gebeurt er als we een onjuiste call naar de API proberen te doen? Laten we proberen om maak een andere host door host.create aan te roepen maar de verplichte parameter groepen weg te laten.

{
           "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,
           "auth": "0424bd59b807674191e7d77572075f33"
       }

Het antwoord zal dan een foutmelding bevatten:

{
           "jsonrpc": "2.0",
           "error": {
               "code": -32602,
               "message": "Ongeldige parameters.",
               "data": "Geen groepen voor host \"Linux server\"."
           },
           "id": 7
       }

Als er een fout is opgetreden, wordt in plaats van de result eigenschap een error eigenschap in het antwoord meegegeven met de volgende gegevens:

  • code - een foutcode;
  • bericht - een korte samenvatting van de fouten;
  • data - een meer gedetailleerde foutmelding.

Fouten kunnen in verschillende gevallen voorkomen, bijvoorbeeld bij het gebruik van onjuiste invoer waarden, een sessie time-out of het proberen toegang te krijgen tot niet-bestaande objecten. Je applicatie zou dit soort fouten netjes moeten kunnen afhandelen.

API-versies

Om API-versiebeheer te vereenvoudigen, komt sinds Zabbix 2.0.4, de versie van de API overeen met de versie van Zabbix zelf. U kunt de apiinfo.version methode gebruiken om de versie van de API waarmee u werkt te vinden. Dit kan handig zijn voor uw toepassing voor aanpassen van versie specifieke functies.

We garanderen achterwaartse compatibiliteit van functies binnen een hoofdversie. Bij het maken van achterwaarts onverenigbare wijzigingen tussen grote releases, laten we meestal de oude functies in de volgende release, en verwijderen deze pas in de release daarna. Af en toe verwijderen we functies tussen grote releases zonder enige achteruit compatibiliteit te garanderen. Het is belangrijk dat u nooit vertrouwt op verouderde functies en migreer zo snel mogelijk naar nieuwere alternatieven.

U kunt alle wijzigingen in de API volgen in de API changelog.

Verder lezen

Je weet nu genoeg om met de Zabbix API aan de slag te gaan, maar stop niet hier. Voor meer informatie raden we u aan een kijkje te nemen in de lijst van beschikbare API's.