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.

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.

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

Met Zabbix-cookie

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

{
           "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
       }

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
       }

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
       }

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
       }

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.

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.