Apèndix 1. Comentari de referència

Notació

Tipus de dades

L'API de Zabbix suporta, com a dades d'entrada, els següents tipus:

Tipus Descripció
boolean Un valor booleà accepta tant true com false.
flag El valor es considera true si no és igual a null, i false en cas contrari.
integer Un nombre sencer.
float Un nombre de coma flotant.
string Una cadena de text.
text Una cadena llarga de text.
timestamp Una marca de temps de Unix.
array Una seqüència ordenada de valors; o sia, una matriu simple.
object Una matriu associativa.
query Un valor que defineix quina informació ha de retornar.

Es pot definir com una matriu de noms de propietats, per tal de retornar només propietats específiques; o com un dels valors predefinits:
extend - retorna totes les propietats de l'objecte;
count - retorna el nombre de registres recuperats, suportats només per algunes subseleccions.

L'API de Zabbix sempre retorna com a valors valors strings o arrays.

Etiquetes de propietat

Algunes propietats d'objectes són marcats amb etiquetes per descriure el seu comportament. Les etiquetes emprades són les següents:

  • readonly - el valor de la propietat s'estableix automàticament i el client no pot pas ni definir-la ni canviar-la;
  • constant el valor de la propietat es pot establir al crear un objecte, però no es pot pas modificar després.

Valor d'ID reservat "0"

El valor "0" d'ID reservat es pot emprar per filtrar elements i esborrar objectes referenciats. Per exemple, per esborrar un proxy referenciat d'un equip, s'ha d'establir proxy_hostid should a 0 ("proxy_hostid": "0"), o per filtrar equips monitorats per l'opció del servidor, s'ha d'establir proxyids a 0 ("proxyids": "0").

Paràmetres comuns del mètode "get"

Es suporten per tots els mètodes get els paràmetres següents:

Paràmetre Tipus Descripció
countOutput boolean Torna el nombre de registres al resultat, enlloc de les dades reals.
editable boolean Si s'estableix a true, només retorna els objectes per als quals l'usuari té permisos d'escriptura.

Per defecte: false.
excludeSearch boolean Retorna els resultats que no corresponen pas als criteris proveïts al paràmetre search.
filter object Retorna els resultats que corresponen al filtre proveït.

Accepta una matriu, on les claus són noms de propietats i els valors són un únic valor o una matriu de valors que corresponen.

No funciona amb camps de tipus text.
limit integer Limita el nombre de registres retornats.
output query Propietats de l'objecte que es retornaran.

Per defecte: extend.
preservekeys boolean Empra els IDs com a claus de la matriu resultant.
search object Retorna els resultats que corresponen a la cerca amb comodins (sensible a mejúscules i minúscules).

Accepta una matriu, on les claus són noms de propietats i els valors són les cadenes que seran cercades. Si no s'especifica cap opció addicional, s'executarà una cerca LIKE "%…%".

Funciona només per a camps string i text.
searchByAny boolean Si s'estableix a true, retorna els resultats que corresponen al criteri donat als paràmetres filter o search, enlloc de retornar-los tots.

Per defecte: false.
searchWildcardsEnabled boolean Si s'estableix a true, permet l'us de "*" com a comodí al paràmetre search.

Per defecte: false.
sortfield string/array Ordena el resultat per les propietats donades. Consulteu una descripció específica del mètode get de l'API per obtindre una llista de propietats que es poden emprar per la classificació. Les macros no són pas ampliades abans d'ordenar.

Si n os'especifiquen valors, la informació es retorna sense ordenar.
sortorder string/array Ordre de classificació. Si es passa una matriu, cada valor correspondrà amb la propietat donada al paràmetre sortfield.

Els valors possibles són:
ASC - (per defecte) ascendent;
DESC - descendent.
startSearch boolean El paràmetre search es compara amb el principi dels camps; és a dir, es farà una cerca LIKE "…%".

S'ignorarà si el searchWildcardsEnabled és establert a true.

Exemples

Verificació dels permisos d'usuari

Té permisos l'usuari per escriure als equips amb noms que comencen amb "MySQL" o "Linux" ?

Petició:

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "countOutput": true,
               "search": {
                   "host": ["MySQL", "Linux"]
               },
               "editable": true,
               "startSearch": true,
               "searchByAny": true
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "id": 1
       }

Resposta:

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

El resultat zero vol dir que no hi ha equips amb permisos de lectura/escriptura.

Recompte d'incompatibilitat

Compta el nombre d'equips amb noms que no tenen pas la subcadena "ubuntu"

Petició:

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "countOutput": true,
               "search": {
                   "host": "ubuntu"
               },
               "excludeSearch": true
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "id": 1
       }

Resposta:

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

Cerca d'equips emprant comodins

Troba els equips amb nom que conté la paraula "servidor" i té ports de xarxa "10050" o "10071". Ordena el resultat per nom d'equip, en ordre decreixent, i limitat a 5 equips.

Petició:

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "output": ["hostid", "host"],
               "selectInterfaces": ["port"],
               "filter": {
                   "port": ["10050", "10071"]
               },
               "search": {
                   "host": "*server*"
               },
               "searchWildcardsEnabled": true,
               "searchByAny": true,
               "sortfield": "host",
               "sortorder": "DESC",
               "limit": 5
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "id": 1
       }

Resposta:

{
           "jsonrpc": "2.0",
           "result": [
               {
                   "hostid": "50003",
                   "host": "WebServer-Tomcat02",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               {
                   "hostid": "50005",
                   "host": "WebServer-Tomcat01",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               {
                   "hostid": "50004",
                   "host": "WebServer-Nginx",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               {
                   "hostid": "99032",
                   "host": "MySQL server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               },
               {
                   "hostid": "99061",
                   "host": "Linux server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               }
           ],
           "id": 1
       }

Cercant equips emprant comodins amb "preservekeys"

Si afegeixes al paràmetre "preservekeys" a la consulta anterior, retorna el resultat com una matriu associativa, on les claus són els id dels objectes.

Petició:

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "output": ["hostid", "host"],
               "selectInterfaces": ["port"],
               "filter": {
                   "port": ["10050", "10071"]
               },
               "search": {
                   "host": "*server*"
               },
               "searchWildcardsEnabled": true,
               "searchByAny": true,
               "sortfield": "host",
               "sortorder": "DESC",
               "limit": 5,
               "preservekeys": true
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "id": 1
       }

Resposta:

{
           "jsonrpc": "2.0",
           "result": {
               "50003": {
                   "hostid": "50003",
                   "host": "WebServer-Tomcat02",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               "50005": {
                   "hostid": "50005",
                   "host": "WebServer-Tomcat01",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },        
               "50004": {
                   "hostid": "50004",
                   "host": "WebServer-Nginx",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               "99032": {
                   "hostid": "99032",
                   "host": "MySQL server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               },
               "99061": {
                   "hostid": "99061",
                   "host": "Linux server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               }
           },
           "id": 1
       }