[comment]: # translation:outdated [comment]: # ({92f30379-92f30379}) # 19. API [comment]: # ({/92f30379-92f30379}) [comment]: # ({83612426-13405b49}) ### Panoramica L'API Zabbix ti consente di recuperare e modificare a livello di codice il file di configurazione di Zabbix e fornisce l'accesso ai dati storici. è ampiamente utilizzato per: - Crea nuove applicazioni per lavorare con Zabbix; - Integra Zabbix con software di terze parti; - Automatizzare le attività di routine. L'API Zabbix è un'API basata sul Web e viene fornita come parte del Web frontend. Utilizza il protocollo JSON-RPC 2.0 che significa due cose: - L'API consiste in un insieme di metodi separati; - Le richieste e le risposte tra i client e l'API sono codificate utilizzando il formato JSON. Maggiori informazioni sul protocollo e su JSON sono disponibili in [JSON-RPC 2.0 specifica](http://www.jsonrpc.org/specification) e [JSON formato home page](http://json.org/). [comment]: # ({/83612426-13405b49}) [comment]: # ({9cb56d09-9cb56d09}) ### Struttura L'API è costituita da una serie di metodi raggruppati nominalmente in API separate. Ciascuno dei metodi esegue un compito specifico. Per esempio, il metodo `host.create` appartiene all'API *host* e viene utilizzato per creare nuovi host. Storicamente, le API sono talvolta denominate "classi". ::: suggerimento La maggior parte delle API contiene almeno quattro metodi: `get`, `create`, `update` e `delete` per recuperare, creare, aggiornare e eliminando i dati rispettivamente, ma alcune delle API possono fornire un insieme di metodi totalmente differenti. ::: [comment]: # ({/9cb56d09-9cb56d09}) [comment]: # ({e4e06a45-9cb2f5ca}) ### Richieste in esecuzione Dopo aver configurato il frontend, puoi utilizzare le richieste remote HTTP come chiamata API. Per fare ciò è necessario inviare richieste HTTP POST a File `api_jsonrpc.php` che si trova nella directory frontend. Per esempio, se il tuo frontend Zabbix è installato in *http://company.com/zabbix*, la richiesta HTTP per chiamare il metodo `apiinfo.version` potrebbe assomigliare questo: ``` {.http} POST http://company.com/zabbix/api_jsonrpc.php HTTP/1.1 Tipo di contenuto: application/json-rpc {"jsonrpc":"2.0","method":"apiinfo.version","id":1,"auth":null,"params":{}} ``` La richiesta deve avere l'intestazione `Content-Type` impostata su uno di questi valori: `application/json-rpc`, `application/json` o `applicazione/richiesta json`. [comment]: # ({/e4e06a45-9cb2f5ca}) [comment]: # ({ec5a9f60-ec5a9f60}) ### Esempio di flusso di lavoro La sezione seguente ti guiderà attraverso alcuni esempi di utilizzo in più dettaglio. [comment]: # ({/ec5a9f60-ec5a9f60}) [comment]: # ({43b7bad6-ef3f5841}) #### Autenticazione Prima di poter accedere a qualsiasi dato all'interno di Zabbix dovrai effettuare il login e ottenere un token di autenticazione. Questo può essere fatto usando il Metodo [user.login](/manual/api/reference/user/login). Supponiamo che desideri accedere come utente amministratore standard. Quindi la tua richiesta JSON sarà simile a questo: ```json { "jsonrpc": "2.0", "metodo": "user.login", "parametri": { "utente": "Amministratore", "password": "zabbix" }, "id": 1, "auth": nullo } ``` Diamo un'occhiata più da vicino all'oggetto della richiesta. Ha quanto segue proprietà: - `jsonrpc` - la versione del protocollo JSON-RPC utilizzato dall'API; l'API Zabbix implementa JSON-RPC versione 2.0; - `method` - il metodo API chiamato; - `params` - parametri che verranno passati al metodo API; - `id` - un identificatore arbitrario della richiesta; - `auth` - un token di autenticazione utente; visto che non ne abbiamo ancora uno, è impostato su `null`. Se hai fornito le credenziali correttamente, la risposta restituita dalla API conterrà il token di autenticazione dell'utente: ```json { "jsonrpc": "2.0", "risultato": "0424bd59b807674191e7d77572075f33", "id": 1 } ``` L'oggetto risposta a sua volta contiene le seguenti proprietà: - `jsonrpc` - ancora, la versione del protocollo JSON-RPC; - `risultato` - i dati restituiti dal metodo; - `id` - identificatore della richiesta corrispondente. [comment]: # ({/43b7bad6-ef3f5841}) [comment]: # ({61809060-f572ecc2}) #### Recupero degli host Ora abbiamo un token di autenticazione utente valido che può essere utilizzato per accedere ai dati in Zabbix. Ad esempio, usiamo il [host.get](/manual/api/reference/host/get) per recuperare gli ID, nomi host e interfacce di tutti configurati [host](/manual/api/riferimento/host/oggetto): ```json { "jsonrpc": "2.0", "metodo": "host.get", "parametri": { "produzione": [ "ostile", "ospite" ], "selectInterfaces": [ "interfaccia", "ip" ] }, "id": 2, "auth": "0424bd59b807674191e7d77572075f33" } ``` ::: nota importante Si noti che la proprietà `auth` è ora impostata su token di autenticazione che abbiamo ottenuto chiamando `user.login`. ::: L'oggetto risposta conterrà i dati richiesti sugli host: ```json { "jsonrpc": "2.0", "risultato": [ { "hostid": "10084", "host": "server Zabbix", "interfacce": [ { "interfaccia": "1", "ip": "127.0.0.1" } ] } ], "id": 2 } ``` ::: suggerimento Per motivi di prestazioni consigliamo di elencare sempre le proprietà dell'oggetto che si desidera recuperare ed evitare di recuperare Tutto quanto. ::: [comment]: # ({/61809060-f572ecc2}) [comment]: # ({e4c060f4-ee2c324f}) #### Creazione di un nuovo elemento Creiamo un nuovo [item](/manual/api/reference/item/object) su "Zabbix server" usando i dati che abbiamo ottenuto dal precedente `host.get` richiesta. Questo può essere fatto usando il Metodo [item.create](/manual/api/reference/item/create): ```json { "jsonrpc": "2.0", "metodo": "item.create", "parametri": { "name": "Spazio libero su disco su /home/joe/", "key_": "vfs.fs.size[/home/joe/,free]", "hostid": "10084", "tipo": 0, "tipo_valore": 3, "interfaccia": "1", "ritardo": 30 }, "auth": "0424bd59b807674191e7d77572075f33", "id": 3 } ``` Una risposta positiva conterrà l'ID dell'elemento appena creato, che può essere utilizzato per fare riferimento all'articolo nelle seguenti richieste: ```json { "jsonrpc": "2.0", "risultato": { "itemi": [ "24759" ] }, "id": 3 } ``` ::: suggerimento Il metodo `item.create` e altri metodi di creazione può anche accettare matrici di oggetti e creare più elementi con un'unica API chiamata. ::: [comment]: # ({/e4c060f4-ee2c324f}) [comment]: # ({e511a956-5ed44978}) #### Creazione di più trigger Quindi, se i metodi di creazione accettano array, possiamo aggiungerne multipli [trigger](/manual/api/reference/trigger/object) in questo modo: ```json { "jsonrpc": "2.0", "metodo": "trigger.create", "parametri": [ { "description": "Il carico del processore è troppo alto su {HOST.NAME}", "expression": "last(/server Linux/system.cpu.load[percpu,avg1])>5", }, { "description": "Troppi processi su {HOST.NAME}", "expression": "avg(/server Linux/proc.num[],5m)>300", } ], "auth": "0424bd59b807674191e7d77572075f33", "id": 4 } ``` Una risposta positiva conterrà gli ID del nuovo creato trigger: ```json { "jsonrpc": "2.0", "risultato": { "triggeridi": [ "17369", "17370" ] }, "id": 4 } ``` [comment]: # ({/e511a956-5ed44978}) [comment]: # ({2a515812-aa174634}) #### Aggiornamento di un elemento Abilita un elemento, ovvero imposta il suo stato su "0": ```json { "jsonrpc": "2.0", "metodo": "item.update", "parametri": { "itemid": "10092", "stato": 0 }, "auth": "0424bd59b807674191e7d77572075f33", "id": 5 } ``` Una risposta corretta conterrà l'ID dell'elemento aggiornato: ```json { "jsonrpc": "2.0", "risultato": { "itemi": [ "10092" ] }, "id": 5 } ``` ::: suggerimento Il metodo `item.update` e altri metodi di aggiornamento può anche accettare matrici di oggetti e aggiornare più elementi con un'unica chiamata API. ::: [comment]: # ({/2a515812-aa174634}) [comment]: # ({3772c85a-e217b4a2}) #### Aggiornamento di più trigger Abilita più trigger, ovvero imposta il loro stato su 0: ```json { "jsonrpc": "2.0", "metodo": "trigger.update", "parametri": [ { "triggeride": "13938", "stato": 0 }, { "triggeride": "13939", "stato": 0 } ], "auth": "0424bd59b807674191e7d77572075f33", "id": 6 } ``` Una risposta corretta conterrà gli ID dei trigger aggiornati: ```json { "jsonrpc": "2.0", "risultato": { "triggeridi": [ "13938", "13939" ] }, "id": 6 } ``` ::: suggerimento Questo è il metodo preferito di aggiornamento. Alcun metodi API come `host.massupdate` consentono di scrivere codice più semplice, ma lo è non è consigliabile utilizzare questi metodi, poiché verranno rimossi nel versioni future. ::: [comment]: # ({/3772c85a-e217b4a2}) [comment]: # ({0ba3cefc-7665e280}) #### Gestione degli errori Fino a quel momento tutto ciò che abbiamo provato ha funzionato bene. Ma cosa succede se proviamo a fare una chiamata errata all'API? Proviamo a creare un altro host chiamando [host.create](/manual/api/reference/host/create) ma omettendo il parametro obbligatorio `gruppi`. ```json { "jsonrpc": "2.0", "metodo": "host.create", "parametri": { "host": "server Linux", "interfacce": [ { "tipo 1, "principale": 1, "uso": 1, "ip": "192.168.3.1", "dn": "", "porta": "10050" } ] }, "id": 7, "auth": "0424bd59b807674191e7d77572075f33" } ``` La risposta conterrà quindi un messaggio di errore: ```json { "jsonrpc": "2.0", "errore": { "codice": -32602, "messaggio": "Parametri non validi.", "data": "Nessun gruppo per l'host \"server Linux\"." }, "id": 7 } ``` Se si è verificato un errore, invece della proprietà `result`, la risposta oggetto conterrà una proprietà `error` con i seguenti dati: - `codice` - un codice di errore; - `messaggio` - un breve riepilogo degli errori; - `data` - un messaggio di errore più dettagliato. Gli errori possono verificarsi in diversi casi, ad esempio utilizzando un input errato valori, un timeout di sessione o il tentativo di accedere a oggetti inesistenti. Tuo l'applicazione dovrebbe essere in grado di gestire con garbo questo tipo di errori. [comment]: # ({/0ba3cefc-7665e280}) [comment]: # ({db15f318-c1074d48}) ### versioni dell'API Per semplificare il versionamento dell'API, da Zabbix 2.0.4, la versione dell'API corrisponde alla versione di Zabbix stessa. Puoi usare il metodo [apiinfo.version](/manual/api/reference/apiinfo/version) da trovare la versione dell'API con cui stai lavorando. Questo può essere utile per modificare l'applicazione per utilizzare le funzionalità specifiche della versione. Garantiamo la compatibilità con le versioni precedenti delle funzionalità all'interno di una versione principale. Quando apportiamo modifiche incompatibili con le versioni precedenti tra le versioni principali, noi di solito lasciamo le vecchie funzionalità come deprecate nella prossima versione e rimuoverli solamente nella versione ancora successiva. Occasionalmente, potremmo rimuovere funzionalità tra le versioni principali senza fornire alcuna versione precedente Compatibilità. È importante non fare mai affidamento su nessuna funzionalità deprecata e migrare a nuove alternative il prima possibile. ::: suggerimento Puoi seguire tutte le modifiche apportate all'API nel file [Registro modifiche API](/manual/api/changes_5.4_-_6.0). ::: [comment]: # ({/db15f318-c1074d48}) [comment]: # ({dfd7315f-dfd7315f}) ### Ulteriori letture Ora ne sai abbastanza per iniziare a lavorare con l'API Zabbix, ma non fermarti qui. Per ulteriori letture ti suggeriamo di dare un'occhiata alla [lista di API disponibili](/manual/api/reference). [comment]: # ({/dfd7315f-dfd7315f})