[comment]: # translation:outdated [comment]: # ({6d056871-6d056871}) # Appendice 1. Commento di riferimento [comment]: # ({/6d056871-6d056871}) [comment]: # ({6594bdc4-6594bdc4}) ### Notazione [comment]: # ({/6594bdc4-6594bdc4}) [comment]: # ({8c926b1a-2df08058}) #### 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.| ::: noteimportant L'API di Zabbix restituisce sempre valori solo come stringhe o array. ::: [comment]: # ({/8c926b1a-2df08058}) [comment]: # ({8f68b338-a2c16a18}) #### 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). ::: noteclassic 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. [comment]: # ({/8f68b338-a2c16a18}) [comment]: # ({f960f4be-f255da9d}) #### 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. [comment]: # ({/f960f4be-f255da9d}) [comment]: # ({cf59def4-5e99748d}) ### 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"`). [comment]: # ({/cf59def4-5e99748d}) [comment]: # ({da9957c2-b4e0f5ab}) ### Parametri comuni dei metodi "get" I seguenti parametri sono supportati da tutti i metodi `get`: |Parametro|[Tipo](#data-types)|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](#data-types) `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](/manual/api/reference/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](#data-types) `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](/manual/api/reference/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`.| [comment]: # ({/da9957c2-b4e0f5ab}) [comment]: # ({1f52febe-4a0aeab6}) ### 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.| [comment]: # ({/1f52febe-4a0aeab6}) [comment]: # ({b41637d2-b41637d2}) ### Esempi [comment]: # ({/b41637d2-b41637d2}) [comment]: # ({7f8a25ac-7a121fac}) #### Verifica dei permessi utente L'utente ha il permesso di scrivere negli host i cui nomi iniziano con "MySQL" o "Linux" ? [Request](/manual/api#performing-requests): ```json { "jsonrpc": "2.0", "method": "host.get", "params": { "countOutput": true, "search": { "host": ["MySQL", "Linux"] }, "editable": true, "startSearch": true, "searchByAny": true }, "id": 1 } ``` Risposta: ```json { "jsonrpc": "2.0", "result": "0", "id": 1 } ``` ::: noteclassic Un risultato pari a zero significa che non ci sono host con permessi di lettura/scrittura. ::: [comment]: # ({/7f8a25ac-7a121fac}) [comment]: # ({b814e950-ea3cccd8}) #### Conteggio delle mancate corrispondenze Conta il numero di host i cui nomi non contengono la sottostringa "ubuntu" [Richiesta](/manual/api#performing-requests): ```json { "jsonrpc": "2.0", "method": "host.get", "params": { "countOutput": true, "search": { "host": "ubuntu" }, "excludeSearch": true }, "id": 1 } ``` Risposta: ```json { "jsonrpc": "2.0", "result": "44", "id": 1 } ``` [comment]: # ({/b814e950-ea3cccd8}) [comment]: # ({a325f949-e911c08b}) #### 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](/manual/api#performing-requests): ```json { "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: ```json { "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 } ``` [comment]: # ({/a325f949-e911c08b}) [comment]: # ({8c8fa5f6-8ce6f554}) #### 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](/manual/api#performing-requests): ```json { "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: ```json { "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 } ``` [comment]: # ({/8c8fa5f6-8ce6f554})