1. pielikums. Atsauces komentāri

Apzīmējumi

Datu tipi

Zabbix API atbalsta šādus datu tipus kā ievadi:

Type Description
ID Unikāls identifikators, ko izmanto, lai atsauktos uz entītiju.
boolean Būla vērtība (true vai false).
flag Vērtība, kas tiek uzskatīta par true, ja tā ir nodota un nav vienāda ar null; pretējā gadījumā vērtība tiek uzskatīta par false.
integer Vesels skaitlis.
float Peldošā komata skaitlis.
string Teksta virkne.
text Garāka teksta virkne.
timestamp Unix laikspiedols.
array Sakārtota vērtību secība (parasts masīvs).
object Asociatīvs masīvs.
query Vērtība, kas nosaka atgriežamos datus. Vērtību var definēt kā īpašību nosaukumu masīvu (lai atgrieztu tikai noteiktas īpašības) vai kā vienu no iepriekš definētajām vērtībām:
extend - atgriež visas objekta īpašības;
count - atgriež iegūto ierakstu skaitu; to atbalsta tikai noteikti apakšatlases vaicājumi.

Zabbix API vienmēr atgriež vērtības tikai kā virknes vai masīvus.

Īpašību darbība

Dažas objekta īpašības ir apzīmētas ar īsām etiķetēm, lai raksturotu to darbību. Tiek izmantotas šādas etiķetes:

  • tikai lasāms - īpašības vērtība tiek iestatīta automātiski un lietotājs to nevar definēt vai mainīt pat dažos īpašos apstākļos (piemēram, tikai lasāms mantotiem objektiem vai atklātiem objektiem);
  • tikai rakstāms - īpašības vērtību var iestatīt, bet pēc tam tai nevar piekļūt;
  • konstants - īpašības vērtību var iestatīt, veidojot objektu, bet pēc tam to nevar mainīt;
  • atbalstīts - īpašības vērtība nav obligāti jāiestata, taču to ir atļauts iestatīt dažos īpašos apstākļos (piemēram, atbalstīts, ja type ir iestatīts uz "Simple check", "External check", "SSH agent", "TELNET agent" vai "HTTP agent"); tomēr ņemiet vērā, ka atbalstītas īpašības joprojām var tikt iestatītas uz to noklusējuma vērtībām neatkarīgi no apstākļiem;
  • obligāts - īpašības vērtība ir obligāti jāiestata visām operācijām (izņemot iegūšanas operācijas) vai dažos īpašos apstākļos (piemēram, obligāts izveides operācijām; obligāts, ja operationtype ir iestatīts uz "global script" un opcommand_hst nav iestatīts).

Atjaunināšanas operācijām īpašība tiek uzskatīta par "iestatītu", ja tā tiek iestatīta atjaunināšanas operācijas laikā.

Īpašības, kas nav apzīmētas ar etiķetēm, nav obligātas.

Parametru uzvedība

Daži operācijas parametri ir apzīmēti ar īsām etiķetēm, lai raksturotu to uzvedību operācijā. Tiek izmantotas šādas etiķetes:

  • tikai lasāms - parametra vērtība tiek iestatīta automātiski un lietotājs to nevar definēt vai mainīt, pat noteiktos īpašos apstākļos (piemēram, tikai lasāms mantotiem objektiem vai atklātiem objektiem);
  • tikai rakstāms - parametra vērtību var iestatīt, bet pēc tam tai nevar piekļūt;
  • atbalstīts - parametra vērtību nav obligāti jāiestata, taču to ir atļauts iestatīt noteiktos īpašos apstākļos (piemēram, atbalstīts, ja Proxy objekta operating_mode ir iestatīts uz "passive proxy"); tomēr ņemiet vērā, ka atbalstītie parametri joprojām var tikt iestatīti uz to noklusējuma vērtībām neatkarīgi no apstākļiem;
  • obligāts - parametra vērtība ir obligāti jāiestata.

Parametri, kas nav apzīmēti ar etiķetēm, nav obligāti.

Rezervētā ID vērtība "0"

Rezervēto ID vērtību "0" var izmantot, lai filtrētu elementus un noņemtu atsauktos objektus. Piemēram, lai noņemtu atsaukto starpniekserveri no hosta, proxyid ir jāiestata uz 0 ("proxyid": "0") vai, lai filtrētu servera uzraudzītos hostus, opcijai proxyids ir jābūt iestatītai uz 0 ("proxyids": "0").

Biežāk izmantotie "get" metožu parametri

Tālāk norādītie parametri tiek atbalstīti visās get metodēs:

Parametrs Tips Apraksts
countOutput boolean Atgriezt rezultātā esošo ierakstu skaitu faktiskās datu izvades vietā.
editable boolean Ja iestatīts uz true, atgriezt tikai tos objektus, kuriem lietotājam ir rakstīšanas atļaujas.

Noklusējums: false.
excludeSearch boolean Atgriezt rezultātus, kas neatbilst search parametrā norādītajiem kritērijiem.
filter object Atgriezt tikai tos rezultātus, kas precīzi atbilst norādītajam filtram.

Pieņem objektu, kurā atslēgas ir īpašību nosaukumi (piemēram, Host objekta īpašības host.get, Item objekta īpašības item.get utt.), bet vērtības ir vai nu viena vērtība, vai vērtību masīvs, ar ko salīdzināt.

Neatbalsta text datu tipa īpašības.

Ņemiet vērā, ka dažām metodēm šim parametram ir specifiska funkcionalitāte, kas ir aprakstīta metodes lapā (piemēram, parametrs filter metodē host.get atbalsta arī Host interfeisa īpašības).
limit integer Ierobežot atgriezto ierakstu skaitu.
output query Atgriežamās objekta īpašības.

Ņemiet vērā, ka objekta ID (t.i., hostid, itemid utt.) vienmēr ir iekļauts atbildē, pat ja tas nav norādīts parametrā output.

Noklusējums: extend.
preservekeys boolean Izmantot ID kā atslēgas rezultējošajā masīvā.
search object Atgriezt rezultātus, kas atbilst norādītajam paraugam (reģistrnejutīgi).

Pieņem objektu, kurā atslēgas ir īpašību nosaukumi (piemēram, Host objekta īpašības host.get, Item objekta īpašības item.get utt.), bet vērtības ir virknes, kuras meklēt. Ja nav norādītas papildu opcijas, tiks veikta LIKE "%…%" meklēšana.

Atbalsta tikai string un text datu tipa īpašības.

Ņemiet vērā, ka dažām metodēm šim parametram ir specifiska funkcionalitāte, kas ir aprakstīta metodes lapā (piemēram, parametrs search metodē host.get atbalsta arī Host interfeisa īpašības).
searchByAny boolean Ja iestatīts uz true, atgriezt rezultātus, kas atbilst jebkuram no filter vai search parametrā norādītajiem kritērijiem, nevis visiem.

Noklusējums: false.
searchWildcardsEnabled boolean Ja iestatīts uz true, parametrā search tiek iespējota "*" izmantošana kā aizstājējzīme.

Noklusējums: false.
sortfield string/array Kārtot rezultātu pēc norādītajām īpašībām. Skatiet konkrētās API get metodes aprakstu, lai iegūtu to īpašību sarakstu, kuras var izmantot kārtošanai. Makrosi pirms kārtošanas netiek izvērsti.

Ja vērtība nav norādīta, dati tiks atgriezti bez kārtošanas.
sortorder string/array Kārtošanas secība. Ja tiek nodots masīvs, katra vērtība tiks piesaistīta atbilstošajai īpašībai, kas norādīta parametrā sortfield.

Iespējamās vērtības:
ASC - (noklusējums) augošā secībā;
DESC - dilstošā secībā.
startSearch boolean Parametrs search salīdzinās lauku sākumu, tas ir, tā vietā veiks LIKE "…%" meklēšanu.

Tiek ignorēts, ja searchWildcardsEnabled ir iestatīts uz true.

Entītiju izcelsmes karodziņi

Get metodes atgriež flags īpašību entītijām, kas saistītas ar zema līmeņa atklāšanu (LLD kārtula/LLD kārtulas prototips, vienums/vienuma prototips utt.). Šī īpašība ir noderīga, lai norādītu, vai entītija ir atklāta vai nav, jo atklāto entītiju rediģēšana ir ierobežota.

Īpašība flags atgriež rezultātu, pamatojoties uz šo vērtību kombināciju (operācija "+"):

Value Description
0 Pamata entītija (vienums, trigeris, grafiks, hosts)
1 Zema līmeņa atklāšanas kārtula
2 Jebkurš prototips (vienuma prototips, trigera prototips, LLD kārtulas prototips utt.)
4 Atklāta entītija (atklāts vienums, trigeris, grafiks, hosts, LLD kārtula)

Ar īpašību flags atgrieztā kombinētā vērtība var būt:

Value Combination of Description
0 0 Parasta entītija (vienums, trigeris, grafiks, hosts).
2 2 Entītijas prototips (vienuma prototips, trigera prototips utt.).
6 2+4 Atklāts vienums, trigeris, grafiks, hosts (pārveidots no prototipa).
1 1 Zema līmeņa atklāšanas kārtula.
3 1+2 Zema līmeņa atklāšanas kārtulas prototips.
5 1+4 Atklāta zema līmeņa atklāšanas kārtula (pārveidota no prototipa).
7 1+2+4 Atklāts zema līmeņa atklāšanas kārtulas prototips.

Piemēri

Lietotāja atļauju pārbaude

Vai lietotājam ir atļauja rakstīt hostos, kuru nosaukumi sākas ar "MySQL" vai "Linux" ?

Pieprasījums:

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

Atbilde:

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

Nulles rezultāts nozīmē, ka nav neviena hosta ar lasīšanas/rakstīšanas atļaujām.

Neatbilstību skaitīšana

Saskaitiet hostus, kuru nosaukumi nesatur apakšvirkni "ubuntu"

Pieprasījums:

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

Atbilde:

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

Hostu meklēšana, izmantojot aizstājējzīmes

Atrodiet hostus, kuru nosaukums satur vārdu "server" un kuriem ir saskarņu porti "10050" vai "10071". Sakārtojiet rezultātu pēc hosta nosaukuma dilstošā secībā un ierobežojiet to līdz 5 hostiem.

Pieprasījums:

{
    "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
    },
    "id": 1
}

Atbilde:

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

Hostu meklēšana, izmantojot aizstājējzīmes ar "preservekeys"

Ja iepriekšējam pieprasījumam pievienojat parametru "preservekeys", rezultāts tiek atgriezts kā asociatīvs masīvs, kur atslēgas ir objektu ID.

Pieprasījums:

{
    "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
    },
    "id": 1
}

Atbilde:

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