19. API

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 e JSON formato home page.

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".

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:

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.

Esempio di flusso di lavoro

La sezione seguente ti guiderà attraverso alcuni esempi di utilizzo in più dettaglio.

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. Supponiamo che desideri accedere come utente amministratore standard. Quindi la tua richiesta JSON sarà simile a questo:

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

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

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 per recuperare gli ID, nomi host e interfacce di tutti configurati host:

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

{
           "jsonrpc": "2.0",
           "risultato": [
               {
                   "hostid": "10084",
                   "host": "server Zabbix",
                   "interfacce": [
                       {
                           "interfaccia": "1",
                           "ip": "127.0.0.1"
                       }
                   ]
               }
           ],
           "id": 2
       }

Creazione di un nuovo elemento

Creiamo un nuovo item su "Zabbix server" usando i dati che abbiamo ottenuto dal precedente host.get richiesta. Questo può essere fatto usando il Metodo item.create:

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

{
           "jsonrpc": "2.0",
           "risultato": {
               "itemi": [
                   "24759"
               ]
           },
           "id": 3
       }

Creazione di più trigger

Quindi, se i metodi di creazione accettano array, possiamo aggiungerne multipli trigger in questo modo:

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

{
           "jsonrpc": "2.0",
           "risultato": {
               "triggeridi": [
                   "17369",
                   "17370"
               ]
           },
           "id": 4
       }

Aggiornamento di un elemento

Abilita un elemento, ovvero imposta il suo stato su "0":

{
           "jsonrpc": "2.0",
           "metodo": "item.update",
           "parametri": {
               "itemid": "10092",
               "stato": 0
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 5
       }

Una risposta corretta conterrà l'ID dell'elemento aggiornato:

{
           "jsonrpc": "2.0",
           "risultato": {
               "itemi": [
                   "10092"
               ]
           },
           "id": 5
       }

Aggiornamento di più trigger

Abilita più trigger, ovvero imposta il loro stato su 0:

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

{
           "jsonrpc": "2.0",
           "risultato": {
               "triggeridi": [
                   "13938",
                   "13939"
               ]
           },
           "id": 6
       }

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 ma omettendo il parametro obbligatorio gruppi.

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

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

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 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.

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.