19. API

Vista general

L'API de Zabbix us permet recuperar i modificar la configuració de Zabbix amb programació i proporciona accés a dades històriques. S'utilitza molt per a:

• Crear noves aplicacions per connectar amb Zabbix;
• Integrar Zabbix amb programari de tercers;
• Automatitzar les tasques rutinàries.

L'API Zabbix és una API web i inclou interfície web. Empra el protocol JSON-RPC 2.0, que vol dir dues coses:

• L'API consta d'un conjunt de mètodes diferents;
• Les peticions i respostes entre clients i l'API són codificades en format JSON.

Trobareu més informació sobre el protocol i JSON a l'especificació JSON-RPC 2.0 i a la pàgina oficial del format JSON.

Per obtindre més informació sobre com integrar la funcionalitat de Zabbix a les vostres aplicacions de Python, consulteu la biblioteca de Python zabbix_utils per a l'API Zabbix.

Estructura

L'API consta d'una sèrie de mètodes que s'agrupen en API separades. Cadascun dels mètodes realitza una tasca específica. Per exemple, el mètode 'host.create' pertany a l'API Equip i s'empra per crear nous equips. Històricament, les API de vegades s'anomenen "classes".

Fer peticions

Un cop hàgiu configurat la interfície web, podeu fer peticions HTTP remotes per cridar a l'API. Per fer-ho, heu d'enviar peticions HTTP POST al fitxer api_jsonrpc.php situat al directori de la interfície. Per exemple, si la vostra interfície Zabbix és instal·lada a http://example.com/zabbix, la sol·licitud HTTP per trucar al mètode apiinfo.version pot assemblar-se a:

POST http://exemple.com/zabbix/api_jsonrpc.php HTTP/1.1
       Content-Type: application/json-rpc
       
       {
           "jsonrpc": "2.0",
           "method": "apiinfo.version",
           "id": 1,
           "auth": null,
           "params": {}
       }

La capçalera Content-Type de la petició s'ha de definir amb un dels segúents valors: application/json-rpc, application/json o application/jsonrequest.

Exemple de flux de treball

La secció següent us guiarà per alguns exemples d'ús més detallats.

Autenticació

Per accedir a dades de Zabbix, heu de:

• Emprar un [token API] existent (/manual/web_interface/frontend_sections/administration/general#api-tokens) (creat a la interfície Zabbix o emprant l'API Token);
• Emprar un token d'autenticació obtingut amb el mètode user.login.

Per exemple, si voleu obtindre un token d'autenticació nou iniciant la sessió com a usuari Admin estàndard, la petició JSON seria així:

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

Fem una ullada detallada a l'objecte de la petició. Té les propietats següents:

• jsonrpc - la versió del protocol JSON-RPC emprat per l'API; l'API Zabbix implementa JSON-RPC versió 2.0;
• method - el mètode API al que es crida;
• params - paràmetres que es passaran a l'API;
• id - un identificador arbitrari de la petició;
• auth - un token d'autenticació d'usuari; des que no en tenim cap, s'estableix a null.

Si proporcioneu les credencials correctes, la resposta de l'API contindrà el token d'autenticació de l'usuari:

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

L'objecte de resposta contindrà les següents propietats:

• jsonrpc - altre cop la versió del protocol JSON-RPC;
• result - les dades retornades per el mètode;
• id - identificador de la petició corresponent.

Recuperació d'equips

Ara tenim un token d'autenticació d'usuari vàlid que es pot emprar per accedir a les dades a Zabbix. Per exemple, emprem el mètode host.get per recuperar els ID, els noms d'equips i les interfícies de tots els equips:

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

L'objecte de resposta contindrà les dades demanades sobre els equips:

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

Creació d'un element nou

Creem un nou element a l'equip "Servidor Zabbix" emprant les dades que vam obtindre de la petició host.get anterior. Això es pot fer mitjançant el mètode item.create:

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

Una resposta correcta contindrà l'ID de l'element que s'acaba de crear, que es pot emprar per fer referència a l'element en peticions posteriors:

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

Crear múltiples triggers

Si els mètodes de creació admeten matrius, podem afegir diversos triggers, com ara:

{
           "jsonrpc": "2.0",
           "method": "trigger.create",
           "params": [
               {
                   "description": "La càrrega del processador és massa alta a {HOST.NAME}",
                   "expression": "last(/Linux server/system.cpu.load[percpu,avg1])>5",
               },
               {
                   "description": "Massa processos a {HOST.NAME}",
                   "expression": "avg(/Linux server/proc.num[],5m)>300",
               }
           ],
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 4
       }

Una resposta correcta contindrà els identificadors dels triggers acabats de crear:

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

Actualitzar un element

Activa un element; és a dir, defineix el seu estat a "0":

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

Una resposta correcta contindrà l'ID de l'element actualitzat:

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

Actualització de diversos triggers

Activar múltiples triggers; és a dir, definir el seu estat a "0":

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

Una resposta correcta contindrà els identificadors dels triggers actualitzats:

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

Gestió d'errors

Fins ara, tot el que hem provat ha funcionat bé. Però, què passa si provem a fer una crida incorrecta de l'API? Provem de crear un altre equip cridant al mètode host.create però ometent el paràmetre necessari groups.

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

La resposta contindrà, doncs, un missatge d'error:

{
           "jsonrpc": "2.0",
           "error": {
               "code": -32602,
               "message": "Paràmetres incorrectes.",
               "data": "No hi ha grups per l'equip \"Linux server\"."
           },
           "id": 7
       }

Si es produeix un error, en lloc de la propietat result, l'objecte de resposta contindrà una propietat error amb les dades següents:

• code - un codi d'error;
• message - un breu resum de l'error;
• data - un missatge d'error més detallat.

Es poden produir errors en diferents casos, com ara emprar valors d'entrada incorrectes, esgotar el temps d'espera d'una sessió o provar d'accedir a objectes que no existeixen. La vostra aplicació ha d'ésser capaç de gestionar aquests errors.

Versions de l'API

Per simplificar la gestió de versions de l'API, des de la versió de Zabbix 2.0.4 l'API té la mateixa versió que Zabbix. Podeu emprar el mètode apiinfo.version per esbrinar la versió de l'API amb la qual treballeu. Això pot ésser útil per refinar la vostra aplicació per emprar funcions específiques de la versió.

Garantim la compatibilitat enrere de les funcions dins d'una versió important. Quan fem canvis incompatibles entre versions principals, normalment deixem les funcions antigues com a obsoletes a la versió següent i després les suprimim una segona versió més enllà. De vegades és possible que traiem la funcionalitat entre les versions principals sense proporcionar compatibilitat amb versions anteriors. És important que mai confieu en funcions obsoletes i migreu cap a noves tan bon punt us sigui possible.

Lectures complementàries

Ara coneixeu força bé com treballar amb l'API Zabbix, però no us atureu pas! Per aprendre'n més, us recomanem consultar la llista d'APIs disponibles.