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 a programari de tercers;
• Automatitzar les tasques rutinàries.

L'API Zabbix és una API HTTP, inclosa a la 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.

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:

curl --request POST \
            --url 'http://exemple.com/zabbix/api_jsonrpc.php'
            --header 'Content-Type: application/json-rpc'
            --data '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'

La petició ha de tindre la capçalera "Tipus de contingut" establerta en un d'aquests valors: application/json-rpc, application/json o aplicació/jsonrequest.

L'objecte de petició conté les propietats següents:

-jsonrpc - la versió del protocol JSON-RPC emprada per l'API (l'API Zabbix implementa JSON-RPC versió 2.0); -method - el mètode de l'API que s'està cridant; -params - els paràmetres que es passaran al mètode API; -id - un identificador arbitrari de la petició.

Si la petició és correcta, la resposta retornada per l'API hauria de ser així:

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

L'objecte de resposta conté les propietats següents:

-jsonrpc - la versió del protocol JSON-RPC; -result - les dades retornades pel mètode; -id - un identificador de la petició corresponent.

Exemple de flux de treball

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

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í:

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

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
       }

Mètodes d'autorització

Capçalera "Autorització"

Totes les peticions d'API requereixen una autenticació o un testimoni d'API. Podeu proporcionar les credencials emprant la capçalera de petició "Autorització":

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

Propietat "auth"

Una petició API es pot autoritzar per la propietat "auth".

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

Per cookie de Zabbix

Una cookie "zbx_session" s'empra per autoritzar una petició d'API des de la interfície d'usuari de Zabbix feta amb JavaScript (des d'un mòdul o giny personalitzat).

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:

Petició:

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
       }

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:

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":"Free disk space on /home/joe/","key_":"vfs.fs.size[/home/joe/,free]","hostid":"10084","type":0,"value_type":3,"interfaceid":"1","delay":30},"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:

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

Una resposta correcta contindrà els IDs 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":

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

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

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

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.

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

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

Zabbix garanteix la compatibilitat enrere de les funcions dins d'una versió important. Quan fem canvis incompatibles entre versions principals, normalment Zabbix deixa 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 Zabbix tregui 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.