Appendice 1. Commento di riferimento

Notazione

Tipi di dati

L'API di Zabbix supporta i seguenti tipi di dati come input:

Type Description
ID Un identificatore univoco utilizzato per fare riferimento a un'entità.
boolean Un valore booleano (true oppure false).
flag Un valore considerato true se passato e diverso da null; altrimenti, il valore è considerato false.
integer Un numero intero.
float Un numero in virgola mobile.
string Una stringa di testo.
text Una stringa di testo più lunga.
timestamp Un timestamp Unix.
array Una sequenza ordinata di valori (un array semplice).
object Un array associativo.
query Un valore che definisce i dati da restituire. Il valore può essere definito come un array di nomi di proprietà (per restituire solo proprietà specifiche), oppure come uno dei valori predefiniti:
extend - restituisce tutte le proprietà dell'oggetto;
count - restituisce il numero di record recuperati, supportato solo da alcune sotto-selezioni.

L'API di Zabbix restituisce sempre valori solo come stringhe o array.

Comportamento delle proprietà

Alcune proprietà dell'oggetto sono contrassegnate con brevi etichette per descriverne il comportamento. Vengono utilizzate le seguenti etichette:

  • sola lettura - il valore della proprietà viene impostato automaticamente e non può essere definito o modificato dall'utente, nemmeno in alcune condizioni specifiche (ad esempio, sola lettura per oggetti ereditati o oggetti individuati);
  • sola scrittura - il valore della proprietà può essere impostato, ma non può essere successivamente consultato;
  • costante - il valore della proprietà può essere impostato durante la creazione di un oggetto, ma non può essere modificato in seguito;
  • supportata - non è necessario impostare il valore della proprietà, ma è consentito farlo in alcune condizioni specifiche (ad esempio, supportata se type è impostato su "Simple check", "External check", "SSH agent", "TELNET agent" o "HTTP agent"); si noti tuttavia che le proprietà supportate possono comunque essere impostate ai loro valori predefiniti indipendentemente dalle condizioni;
  • obbligatoria - il valore della proprietà deve essere impostato per tutte le operazioni (eccetto le operazioni di get) oppure in alcune condizioni specifiche (ad esempio, obbligatoria per le operazioni di creazione; obbligatoria se operationtype è impostato su "global script" e opcommand_hst non è impostato).

Per le operazioni di aggiornamento, una proprietà è considerata "impostata" quando viene impostata durante l'operazione di aggiornamento.

Le proprietà non contrassegnate con etichette sono facoltative.

Comportamento dei parametri

Alcuni parametri dell'operazione sono contrassegnati con brevi etichette per descriverne il comportamento per l'operazione. Vengono utilizzate le seguenti etichette:

  • sola lettura - il valore del parametro viene impostato automaticamente e non può essere definito o modificato dall'utente, nemmeno in alcune condizioni specifiche (ad esempio, sola lettura per oggetti ereditati o oggetti individuati);
  • sola scrittura - il valore del parametro può essere impostato, ma successivamente non può essere consultato;
  • supportato - non è necessario impostare il valore del parametro, ma è consentito farlo in alcune condizioni specifiche (ad esempio, supportato se operating_mode dell'oggetto Proxy è impostato su "passive proxy"); si noti tuttavia che i parametri supportati possono comunque essere impostati ai loro valori predefiniti indipendentemente dalle condizioni;
  • obbligatorio - è necessario impostare il valore del parametro.

I parametri che non sono contrassegnati con etichette sono facoltativi.

Valore ID riservato "0"

Il valore ID riservato "0" può essere utilizzato per filtrare gli elementi e per rimuovere gli oggetti referenziati. Ad esempio, per rimuovere un proxy referenziato da un host, proxyid deve essere impostato su 0 ("proxyid": "0"), oppure, per filtrare gli host monitorati dal server, l'opzione proxyids deve essere impostata su 0 ("proxyids": "0").

Parametri comuni dei metodi "get"

I seguenti parametri sono supportati da tutti i metodi get:

Parametro Tipo Descrizione
countOutput boolean Restituisce il numero di record nel risultato invece dei dati effettivi.
editable boolean Se impostato su true, restituisce solo gli oggetti per i quali l'utente dispone dei permessi di scrittura.

Predefinito: false.
excludeSearch boolean Restituisce i risultati che non corrispondono ai criteri specificati nel parametro search.
filter object Restituisce solo i risultati che corrispondono esattamente al filtro specificato.

Accetta un oggetto, in cui le chiavi sono nomi di proprietà (ad esempio, proprietà dell'oggetto Host in host.get, proprietà dell'oggetto Item in item.get, ecc.) e i valori sono un singolo valore oppure un array di valori da confrontare.

Non supporta proprietà del tipo di dati text.

Si noti che alcuni metodi hanno funzionalità specifiche per questo parametro, descritte nella pagina del metodo (ad esempio, il parametro filter in host.get supporta anche le proprietà dell'interfaccia Host).
limit integer Limita il numero di record restituiti.
output query Proprietà dell'oggetto da restituire.

Si noti che l'ID dell'oggetto (ovvero hostid, itemid, ecc.) è sempre incluso nella risposta, anche se non è specificato nel parametro output.

Predefinito: extend.
preservekeys boolean Usa gli ID come chiavi nell'array risultante.
search object Restituisce i risultati che corrispondono al modello specificato (senza distinzione tra maiuscole e minuscole).

Accetta un oggetto, in cui le chiavi sono nomi di proprietà (ad esempio, proprietà dell'oggetto Host in host.get, proprietà dell'oggetto Item in item.get, ecc.) e i valori sono stringhe da cercare. Se non vengono fornite opzioni aggiuntive, verrà eseguita una ricerca LIKE "%…%".

Supporta solo proprietà del tipo di dati string e text.

Si noti che alcuni metodi hanno funzionalità specifiche per questo parametro, descritte nella pagina del metodo (ad esempio, il parametro search in host.get supporta anche le proprietà dell'interfaccia Host).
searchByAny boolean Se impostato su true, restituisce i risultati che corrispondono a uno qualsiasi dei criteri specificati nel parametro filter o search, invece che a tutti.

Predefinito: false.
searchWildcardsEnabled boolean Se impostato su true, abilita l'uso di "*" come carattere jolly nel parametro search.

Predefinito: false.
sortfield string/array Ordina il risultato in base alle proprietà specificate. Fare riferimento alla descrizione di uno specifico metodo API get per un elenco delle proprietà che possono essere usate per l'ordinamento. Le macro non vengono espanse prima dell'ordinamento.

Se non viene specificato alcun valore, i dati verranno restituiti senza ordinamento.
sortorder string/array Ordine di ordinamento. Se viene passato un array, ciascun valore verrà associato alla proprietà corrispondente specificata nel parametro sortfield.

Valori possibili:
ASC - (predefinito) crescente;
DESC - decrescente.
startSearch boolean Il parametro search confronterà l'inizio dei campi, ovvero eseguirà invece una ricerca LIKE "…%".

Ignorato se searchWildcardsEnabled è impostato su true.

Flag di origine dell'entità

I metodi get restituiscono una proprietà flags per le entità correlate al low-level discovery (regola LLD/prototipo di regola LLD, item/prototipo di item, ecc.). Questa proprietà è utile per indicare se l'entità è stata rilevata oppure no, poiché la modifica delle entità rilevate è limitata.

La proprietà flags restituisce un risultato basato su una combinazione (operazione "+") di questi valori:

Value Description
0 Entità di base (item, trigger, graph, host)
1 Regola di low-level discovery
2 Qualsiasi prototipo (prototipo di item, prototipo di trigger, prototipo di regola LLD, ecc.)
4 Entità rilevata (item, trigger, graph, host, regola LLD rilevati)

Il valore combinato restituito dalla proprietà flags può essere:

Value Combination of Description
0 0 Entità semplice (item, trigger, graph, host).
2 2 Prototipo di entità (prototipo di item, prototipo di trigger, ecc.).
6 2+4 item, trigger, graph, host rilevati (convertiti da prototipo).
1 1 Regola di low-level discovery.
3 1+2 Prototipo di regola di low-level discovery.
5 1+4 Regola di low-level discovery rilevata (convertita da prototipo).
7 1+2+4 Prototipo di regola di low-level discovery rilevato.

Esempi

Verifica dei permessi utente

L'utente ha il permesso di scrivere negli host i cui nomi iniziano con "MySQL" o "Linux" ?

Request:

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

Risposta:

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

Un risultato pari a zero significa che non ci sono host con permessi di lettura/scrittura.

Conteggio delle mancate corrispondenze

Conta il numero di host i cui nomi non contengono la sottostringa "ubuntu"

Richiesta:

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

Risposta:

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

Ricerca di host utilizzando caratteri jolly

Trova gli host il cui nome contiene la parola "server" e che hanno porte di interfaccia "10050" oppure "10071". Ordina il risultato per nome host in ordine decrescente e limitalo a 5 host.

Richiesta:

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

Risposta:

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

Ricerca di host utilizzando caratteri jolly con "preservekeys"

Se si aggiunge il parametro "preservekeys" alla richiesta precedente, il risultato viene restituito come array associativo, in cui le chiavi sono gli ID degli oggetti.

Richiesta:

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

Risposta:

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