Documentation
Table of Contents
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
typeis 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
operationtypeis ingesteld op "globaal script" enopcommand_hstniet 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
statusvan 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"?
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"countOutput": true,
"search": {
"host": ["MySQL", "Linux"]
},
"editable": true,
"startSearch": true,
"searchByAny": true
},
"id": 1
}Reactie:
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.
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"countOutput": true,
"search": {
"host": "ubuntu"
},
"excludeSearch": true
},
"id": 1
}Reactie:
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.
{
"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.
{
"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
}