19. API

Overzicht

De Zabbix API stelt je 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 met software van derden;
• Routinetaken te automatiseren.

De Zabbix API is een op web gebaseerde API en wordt meegeleverd als onderdeel van de webinterface. Het maakt gebruik van het JSON-RPC 2.0-protocol, wat betekent:

• De API bestaat uit een reeks afzonderlijke methoden;
• Verzoeken en antwoorden tussen de klanten 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-formaat startpagina.

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".

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 in de frontend-map bevindt. Als bijvoorbeeld je Zabbix-frontend is geïnstalleerd onder http://voorbeeld.com/zabbix, kan het HTTP-verzoek om de methode apiinfo.version aan te roepen er als volgt uitzien:

POST http://example.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 header Content-Type hebben die is ingesteld op een van deze waarden: application/json-rpc, application/json of application/jsonrequest.

Voorbeeld workflow

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

Authenticatie

Toegang krijgen tot gegevens in Zabbix vereist het volgende:

• Gebruik een bestaande API-token (aangemaakt in de Zabbix-frontend of via de Token API);
• Gebruik een authenticatietoken verkregen met de user.login methode.

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

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

Laten we het aanvraagobject van naderbij bekijken. Het heeft de volgende eigenschappen:

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

Als je de inloggegevens correct hebt ingevoerd, zal het antwoord dat door de API wordt geretourneerd, het gebruikersauthenticatietoken bevatten:

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

Het antwoordobject bevat op zijn beurt de volgende eigenschappen:

• jsonrpc - opnieuw, de versie van het JSON-RPC-protocol;
• result - de gegevens die door de methode zijn geretourneerd;
• id - identificatie van het overeenkomstige 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
       }

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
       }

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
       }

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
       }

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 de versie van de API sinds Zabbix 2.0.4 overeen met de versie van Zabbix zelf. Je kunt de apiinfo.version methode gebruiken om de versie van de API waarmee je werkt te achterhalen. Dit kan handig zijn om je applicatie aan te passen aan versie-specifieke functies.

We garanderen achterwaartse compatibiliteit van functies binnen een hoofdversie. Wanneer we achterwaarts onverenigbare wijzigingen maken tussen hoofdversies, laten we de oude functies meestal als verouderd staan in de volgende release, en verwijderen we ze pas in de release daarna. Af en toe kunnen we functies tussen hoofdversies verwijderen zonder enige achterwaartse compatibiliteit te bieden. Het is belangrijk dat je nooit vertrouwt op verouderde functies en zo snel mogelijk migreert naar nieuwere alternatieven.

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.