You are viewing documentation for the development version, it may be incomplete.
Join our translation project and help translate Zabbix documentation into your native language.

19. API

Overzicht

De Zabbix API stelt u in staat om programmatisch de configuratie van Zabbix op te halen en aan te passen en biedt toegang tot historische gegevens. Het wordt veel gebruikt om:

  • Nieuwe toepassingen te maken om met Zabbix te werken;
  • Zabbix te integreren in software van derden;
  • Routinetaken te automatiseren.

De Zabbix API is een op HTTP gebaseerde API en wordt geleverd als onderdeel van de webfrontend. Het maakt gebruik van het JSON-RPC 2.0-protocol, wat betekent dat:

  • De API bestaat uit een reeks afzonderlijke methoden.
  • Verzoeken en antwoorden tussen de cliënten en de API worden gecodeerd met behulp van het JSON-formaat.

Meer informatie 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 één specifieke taak uit. Bijvoorbeeld, de methode host.create behoort tot de host API en wordt gebruikt om nieuwe hosts aan te maken. Historisch gezien worden API's soms ook wel "klassen" genoemd.

De meeste API's bevatten minstens vier methoden: get, create, update en delete voor respectievelijk het ophalen, aanmaken, bijwerken en verwijderen van gegevens, maar sommige API's kunnen een compleet andere set methoden bieden.

Het uitvoeren van verzoeken

Nadat je de frontend hebt ingesteld, kun je externe HTTP-verzoeken gebruiken om de API aan te roepen. Om dit te doen, moet je HTTP POST-verzoeken sturen naar het bestand api_jsonrpc.php dat zich bevindt in de frontend-directory. Bijvoorbeeld, als je Zabbix-frontend is geïnstalleerd onder https://example.com/zabbix, dan kan een HTTP-verzoek om de methode apiinfo.version aan te roepen er als volgt uitzien:

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}'

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

Het verzoekobject bevat de volgende eigenschappen:

  • jsonrpc - de versie van het JSON-RPC-protocol dat door de API wordt gebruikt (Zabbix API implementeert JSON-RPC-versie 2.0);
  • method - de opgeroepen API-methode;
  • params - de parameters die aan de API-methode worden doorgegeven;
  • id - een willekeurige identificator van het verzoek.

Als het verzoek correct is, zou het antwoord dat door de API wordt geretourneerd er als volgt uit moeten zien:

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

Het antwoordobject bevat op zijn beurt de volgende eigenschappen:

  • jsonrpc - de versie van het JSON-RPC-protocol;
  • result - de gegevens die door de methode worden geretourneerd;
  • id - een identificator van het overeenkomstige verzoek.

Voorbeeldworkflow

Het volgende gedeelte zal je door enkele voorbeelden van gebruik leiden met meer details.

Authenticatie

Om toegang te krijgen tot gegevens in Zabbix, moet je ofwel:

  • gebruikmaken van een bestaande API-token (aangemaakt in de Zabbix-frontend of met behulp van de Token API);
  • gebruikmaken van een authenticatietoken dat is verkregen met de methode user.login.

Bijvoorbeeld, als je een nieuw authenticatietoken wilt verkrijgen door in te loggen als de standaard gebruiker Admin, dan zou een JSON-verzoek er als volgt uitzien:

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}'

Als je de inloggegevens correct hebt ingevoerd, zou de reactie van de API het gebruikersauthenticatietoken moeten bevatten:

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

Authorization methods

Via "Authorization" koptekst

Alle API-verzoeken vereisen een authenticatie of een API-token. Je kunt de inloggegevens verstrekken door de "Authorization" verzoekskoptekst te gebruiken:

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

Een API-verzoek kan geautoriseerd worden met behulp van de "auth" eigenschap.

Merk op dat de "auth" eigenschap verouderd is. Deze zal in toekomstige versies verwijderd worden.

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"host.get","params":{"output":["hostid"]},"auth":"0424bd59b807674191e7d77572075f33","id":1}'

Een "zbx_session"-cookie wordt gebruikt om een API-verzoek te autoriseren vanuit de Zabbix UI die wordt uitgevoerd met JavaScript (vanuit een module of een aangepaste widget).

Hosts ophalen

Nu heb je een geldige gebruikersauthenticatietoken die kan worden gebruikt om toegang te krijgen tot de gegevens in Zabbix. Bijvoorbeeld, je kunt de methode host.get gebruiken om de ID's, hostnamen en interfaces van alle geconfigureerde hosts op te halen:

Verzoek:

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 is een bestand dat een JSON-query bevat. In plaats van een bestand kun je de query doorgeven in het --data argument.

data.json

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

Het antwoordobject bevat de gevraagde gegevens over de hosts:

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

Voor prestatieredenen wordt altijd aanbevolen om de objecteigenschappen op te sommen die je wilt ophalen. Op die manier vermijd je om alles op te halen.

Een nieuw item maken

Nu kun je een nieuw item maken op de host "Zabbix server" met behulp van de gegevens die je hebt verkregen uit het vorige host.get verzoek. Dit kan worden gedaan met behulp van de item.create methode:

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":"Vrije schijfruimte op /home/joe/","key_":"vfs.fs.size[/home/joe/,free]","hostid":"10084","type":0,"value_type":3,"interfaceid":"1","delay":30},"id":3}'

Een succesvol antwoord zal de ID van het nieuw gemaakte item bevatten, welke gebruikt kan worden om naar het item te refereren in volgende verzoeken:

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

De item.create methode, evenals andere create-methoden, kan ook arrays van objecten accepteren en meerdere items maken met één API-aanroep.

Het maken van meerdere triggers

Als create-methoden arrays accepteren, dan kun je meerdere triggers toevoegen, bijvoorbeeld deze:

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}'

Het succesvolle antwoord zal de ID's bevatten van de nieuw gemaakte triggers:

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

Een item bijwerken

Schakel een item in door de status in te stellen op "0":

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}'

Het succesvolle antwoord zal de ID bevatten van het bijgewerkte item:

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

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

Meerdere triggers bijwerken

Activeer meerdere triggers door hun status in te stellen op "0":

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}'

Het succesvolle antwoord zal de ID's van de bijgewerkte triggers bevatten:

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

Dit is de voorkeursmethode voor bijwerken. Sommige API-methoden, zoals host.massupdate, stellen u in staat om eenvoudiger code te schrijven. Het wordt echter niet aanbevolen om deze methoden te gebruiken, omdat ze in toekomstige releases zullen worden verwijderd.

Foutafhandeling

Tot nu toe heeft alles wat u hebt geprobeerd goed gewerkt. Maar wat gebeurt er als u een onjuiste oproep aan de API probeert te doen? Probeer een andere host te maken door host.create aan te roepen, maar laat het verplichte groups-parameter weg:

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}'

De reactie bevat dan een foutmelding:

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

Als er een fout is opgetreden, zal het antwoordobject in plaats van de eigenschap result de eigenschap error bevatten met de volgende gegevens:

  • code - een foutcode;
  • message - een korte samenvatting van de fout;
  • data - een gedetailleerdere foutmelding.

Fouten kunnen zich voordoen in verschillende situaties, zoals het gebruik van onjuiste invoerwaarden, een sessie-time-out of het proberen toegang te krijgen tot niet-bestaande objecten. Uw applicatie moet deze soorten fouten op een gepaste manier kunnen afhandelen.

API-versies

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

Zabbix garandeert backward compatibiliteit van functies binnen een belangrijke versie. Bij het maken van backward-incompatibele wijzigingen tussen grote releases laat Zabbix meestal de oude functies als verouderd achter in de volgende release en verwijdert ze pas in de release daarna. Af en toe kan Zabbix functies tussen grote releases verwijderen zonder enige backward-compatibiliteit te bieden. Het is belangrijk dat u nooit vertrouwt op enige verouderde functies en zo snel mogelijk migreert naar nieuwere alternatieven.

U kunt alle wijzigingen in de API volgen in de API-wijzigingslog.

Meer lezen

Nu heb je voldoende kennis om aan de slag te gaan met de Zabbix API, maar stop hier niet. Voor meer informatie wordt aangeraden om de lijst met beschikbare API's te raadplegen.