This is a translation of the original English documentation page. Help us make it better.

Bijlage 1. Referentie commentaar

Notatie

Gegevenstypen

De Zabbix API ondersteunt de volgende gegevenstypen als invoer:

Type Beschrijving
boolean Een booleaanse waarde, accepteert zowel true als false.
flag De waarde wordt beschouwd als true als deze wordt doorgegeven en niet gelijk is aan null; anders wordt deze beschouwd als false.
integer Een geheel getal.
float Een zwevend kommagetal.
string Een tekststring.
text Een langere tekststring.
timestamp Een Unix-tijdstempel.
array Een geordende reeks waarden, dat wil zeggen een gewone array.
object Een associatieve array.
query Een waarde die bepaalt welke gegevens moeten worden teruggegeven.

Kan worden gedefinieerd als een array van eigenschapsnamen om alleen specifieke eigenschappen terug te geven, of als een van de vooraf gedefinieerde waarden:
extend - geeft alle objecteigenschappen terug;
count - geeft het aantal opgehaalde records terug, wordt alleen ondersteund door bepaalde subselects.

De Zabbix API geeft altijd waarden terug als strings of alleen arrays.

Eigenschapsgedrag

Sommige eigenschappen van het object zijn gemarkeerd met korte labels om hun gedrag te beschrijven. De volgende labels worden gebruikt:

  • alleen-lezen - de waarde van de eigenschap wordt automatisch ingesteld en kan niet door de gebruiker worden gedefinieerd of gewijzigd, zelfs niet onder bepaalde specifieke omstandigheden (bijv. alleen-lezen voor geërfde objecten of ontdekte objecten);
  • alleen-schrijven - de waarde van de eigenschap kan worden ingesteld, maar kan niet worden opgehaald na het instellen;
  • constant - de waarde van de eigenschap kan worden ingesteld bij het maken van een object, maar kan daarna niet meer worden gewijzigd;
  • ondersteund - de waarde van de eigenschap hoeft niet te worden ingesteld, maar mag in sommige specifieke omstandigheden worden ingesteld (bijv. ondersteund als type is ingesteld op "Eenvoudige controle", "Externe controle", "SSH-agent", "TELNET-agent" of "HTTP-agent");
  • vereist - de waarde van de eigenschap moet worden ingesteld voor alle bewerkingen (behalve get-bewerkingen) of in sommige specifieke omstandigheden (bijv. vereist voor aanmaakbewerkingen; vereist als operationtype is ingesteld op "globaal script" en opcommand_hst niet is ingesteld).

Voor update-bewerkingen wordt een eigenschap als "ingesteld" beschouwd wanneer deze wordt ingesteld tijdens de update-bewerking.

Eigenschappen die niet zijn gemarkeerd met labels zijn optioneel.

Parametergedrag

Sommige van de bewerkingsparameters zijn gemarkeerd met korte labels om hun gedrag voor de bewerking te beschrijven. De volgende labels worden gebruikt:

  • alleen-lezen - de waarde van de parameter wordt automatisch ingesteld en kan niet door de gebruiker worden gedefinieerd of gewijzigd, zelfs niet onder bepaalde specifieke omstandigheden (bijv. alleen-lezen voor geërfde objecten of ontdekte objecten);
  • alleen-schrijven - de waarde van de parameter kan worden ingesteld, maar kan niet worden opgehaald na het instellen;
  • ondersteund - de waarde van de parameter hoeft niet te worden ingesteld, maar mag in sommige specifieke omstandigheden worden ingesteld (bijv. ondersteund als status van een Proxy-object is ingesteld op "passieve proxy");
  • vereist - de waarde van de parameter moet worden ingesteld.

Parameters die niet zijn gemarkeerd met labels zijn optioneel.

Voorbehouden ID-waarde "0"

De voorbehouden ID-waarde "0" kan worden gebruikt om elementen te filteren en om gekoppelde objecten te verwijderen. Bijvoorbeeld, om een gekoppelde proxy van een host te verwijderen, moet proxy_hostid worden ingesteld op 0 ("proxy_hostid": "0") of om hosts die worden bewaakt door de server te filteren, moet proxyids worden ingesteld op 0 ("proxyids": "0").

Algemene parameters voor de "get" methode

De volgende parameters worden ondersteund door alle get methoden:

Parameter Type Beschrijving
countOutput boolean Geef het aantal records in het resultaat terug in plaats van de feitelijke gegevens.
editable boolean Als ingesteld op true, geef alleen objecten terug waarvoor de gebruiker schrijfrechten heeft.

Standaard: false.
excludeSearch boolean Geef resultaten terug die niet overeenkomen met de criteria die zijn opgegeven in de search parameter.
filter object Geef alleen resultaten terug die exact overeenkomen met de opgegeven filter.

Accepteert een array, waarbij de sleutels eigenschapnamen zijn en de waarden een enkele waarde of een array van waarden zijn om mee te matchen.

Ondersteunt geen velden van het gegevenstype text.
limit integer Beperk het aantal teruggegeven records.
output query Objecteigenschappen die moeten worden teruggegeven.

Standaard: extend.
preservekeys boolean Gebruik IDs als sleutels in de resulterende array.
search object Geef resultaten terug die overeenkomen met het opgegeven patroon (hoofdletterongevoelig).

Accepteert een array, waarbij de sleutels eigenschapnamen zijn en de waarden strings zijn om naar te zoeken. Als er geen aanvullende opties worden opgegeven, wordt er een LIKE "%…%" zoekopdracht uitgevoerd.

Ondersteunt alleen velden van het gegevenstype string en text.
searchByAny boolean Als ingesteld op true, geef resultaten terug die voldoen aan een van de criteria die zijn opgegeven in de filter of search parameter in plaats van aan allemaal.

Standaard: false.
searchWildcardsEnabled boolean Als ingesteld op true, wordt het gebruik van "*" als jokerteken in de search parameter ingeschakeld.

Standaard: false.
sortfield string/array Sorteer het resultaat op basis van de opgegeven eigenschappen. Raadpleeg de beschrijving van een specifieke API get methode voor een lijst van eigenschappen die kunnen worden gebruikt voor sorteren. Macro's worden niet uitgebreid vóór het sorteren.

Als er geen waarde is opgegeven, worden de gegevens ongesorteerd teruggegeven.
sortorder string/array Sorteervolgorde. Als een array wordt doorgegeven, wordt elke waarde gematcht met de overeenkomstige eigenschap die is opgegeven in de sortfield parameter.

Mogelijke waarden:
ASC - (standaard) oplopend;
DESC - aflopend.
startSearch boolean De search parameter zal het begin van velden vergelijken, dat wil zeggen, een LIKE "…%" zoekopdracht uitvoeren.

Genegeerd als searchWildcardsEnabled is ingesteld op true.

Voorbeelden

Controle op gebruikersmachtigingen

Heeft de gebruiker toestemming om te schrijven naar hosts waarvan de namen beginnen met "MySQL" of "Linux"?

Verzoek:

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

Reactie:

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

Een resultaat van nul betekent dat er geen hosts zijn met lees/schrijfmachtigingen.

Aantal afwijkingen tellen

Tel het aantal hosts waarvan de namen de subreeks "ubuntu" niet bevatten.

Verzoek:

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

Reactie:

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

Zoeken naar hosts met behulp van wildcards

Vind hosts waarvan de naam het woord "server" bevat en die interfacepoorten "10050" of "10071" hebben. Sorteer het resultaat op hostnaam in aflopende volgorde en beperk het tot 5 hosts.

Verzoek:

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

Reactie:

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

Zoeken naar hosts met behulp van wildcards met "preservekeys"

Als je de parameter "preservekeys" toevoegt aan het vorige verzoek, wordt het resultaat geretourneerd als een associatieve array, waarbij de sleutels de id's van de objecten zijn.

Verzoek:

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

Reactie:

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