L'API di Zabbix consente di recuperare e modificare programmaticamente la configurazione di Zabbix e fornisce accesso ai dati storici. È ampiamente utilizzata per:

creare nuove applicazioni che funzionino con Zabbix;
integrare Zabbix in software di terze parti;
automatizzare attività di routine.

L'API di Zabbix è un'API basata su HTTP ed è distribuita come parte del frontend web. Utilizza il protocollo JSON-RPC 2.0, il 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.

Per ulteriori informazioni sul protocollo e su JSON, vedere la specifica JSON-RPC 2.0 e la homepage del formato JSON.

Per ulteriori informazioni sull'integrazione delle funzionalità di Zabbix nelle applicazioni Python, vedere libreria Python per Zabbix.

L'accesso degli utenti in Zabbix, inclusi sia i dati di configurazione sia quelli storici, dipende dal tipo di utente, dal ruolo utente assegnato e dai gruppi di utenti.

Struttura

L'API è composta da una serie di metodi che sono nominalmente raggruppati in API separate. Ciascuno di questi metodi esegue un'attività specifica. Ad esempio, il metodo host.create appartiene all'API host e viene utilizzato per creare nuovi host. Storicamente, le API sono talvolta chiamate "classi".

La maggior parte delle API contiene almeno quattro metodi: get, create, update e delete, rispettivamente per il recupero, la creazione, l'aggiornamento e l'eliminazione dei dati, ma alcune API possono fornire un insieme di metodi completamente diverso.

Esecuzione delle richieste

Una volta configurato il frontend, è possibile utilizzare richieste HTTP remote per chiamare l'API. Per farlo, è necessario inviare richieste HTTP POST al file api_jsonrpc.php situato nella directory del frontend. Ad esempio, se il frontend di Zabbix è installato in https://example.com/zabbix, una richiesta HTTP per chiamare il metodo apiinfo.version può apparire così:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'

La richiesta deve avere l'header Content-Type impostato su uno di questi valori: application/json-rpc, application/json oppure application/jsonrequest.

L'oggetto della richiesta deve contenere le seguenti proprietà:

jsonrpc - la versione del protocollo JSON-RPC utilizzata dall'API (l'API di Zabbix implementa JSON-RPC versione 2.0);
method - il metodo API che viene chiamato;
params - i parametri che verranno passati al metodo API;
id - un identificatore arbitrario della richiesta (se omesso, l'API tratta la richiesta come una notifica).

Se la richiesta è corretta, la risposta restituita dall'API dovrebbe apparire così:

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

L'oggetto della risposta, a sua volta, contiene le seguenti proprietà:

jsonrpc - la versione del protocollo JSON-RPC;
result - i dati restituiti dal metodo;
id - un identificatore della richiesta corrispondente.

Flusso di lavoro di esempio

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

Autenticazione

Per accedere a qualsiasi dato in Zabbix, è necessario:

utilizzare un token API esistente (creato nel frontend di Zabbix o usando la Token API);
utilizzare un token di autenticazione ottenuto con il metodo user.login.

Ad esempio, se si desidera ottenere un nuovo token di autenticazione effettuando l'accesso come utente Admin standard, una richiesta JSON sarà simile a questa:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"user.login","params":{"username":"Admin","password":"zabbix"},"id":1}'

Se le credenziali sono state fornite correttamente, la risposta restituita dall'API dovrebbe contenere il token di autenticazione dell'utente:

{
    "jsonrpc": "2.0",
    "result": "0424bd59b807674191e7d77572075f33",
    "id": 1
}

Metodi di autorizzazione

Tramite l'header "Authorization"

Tutte le richieste API richiedono un'autenticazione o un token API. Puoi fornire le credenziali utilizzando l'header Authorization nella richiesta:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33'

Se riscontri problemi di autenticazione, consulta inoltro dell'header Authorization.

Zabbix API accetta gli header in modo case-insensitive (ad esempio, authorization, Authorization e AUTHORIZATION vengono trattati allo stesso modo).

L'header Authorization è supportato nelle richieste cross-origin (CORS).

Un cookie "zbx_session" viene utilizzato per autorizzare una richiesta API dall'interfaccia utente di Zabbix eseguita tramite JavaScript (da un componente o da un widget personalizzato).

Recupero degli host

Ora disponi di un token di autenticazione utente valido (rappresentato come variabile negli esempi seguenti) che può essere utilizzato per accedere ai dati in Zabbix. Ad esempio, puoi usare il metodo host.get per recuperare gli ID, i nomi host e le interfacce di tutti gli host configurati:

Richiesta:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data @data.json

data.json è un file che contiene una query JSON. Invece di un file, puoi passare la query nell'argomento --data.

data.json

{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "output": [
            "hostid",
            "host"
        ],
        "selectInterfaces": [
            "interfaceid",
            "ip"
        ]
    },
    "id": 2
}

L'oggetto di risposta conterrà i dati richiesti sugli host:

{
    "jsonrpc": "2.0",
    "result": [
        {
            "hostid": "10084",
            "host": "Zabbix server",
            "interfaces": [
                {
                    "interfaceid": "1",
                    "ip": "127.0.0.1"
                }
            ]
        }
    ],
    "id": 2
}

Per motivi di prestazioni, è sempre consigliato elencare le proprietà dell'oggetto che desideri recuperare. In questo modo, eviterai di recuperare tutto.

Creazione di un nuovo item

Ora, crea un nuovo item sull'host "Zabbix server" utilizzando i dati ottenuti dalla precedente richiesta host.get. Questo può essere fatto usando il metodo item.create:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"item.create","params":{"name":"Free disk space on /home/joe/","key_":"vfs.fs.size[/home/joe/,free]","hostid":"10084","type":0,"value_type":3,"interfaceid":"1","delay":30},"id":3}'

Una risposta riuscita conterrà l'ID dell'item appena creato, che può essere utilizzato per fare riferimento all'item nelle richieste successive:

{
    "jsonrpc": "2.0",
    "result": {
        "itemids": [
            "24759"
        ]
    },
    "id": 3
}

Il metodo item.create, così come altri metodi create, può anche accettare array di oggetti e creare più item con una sola chiamata API.

Creazione di più trigger

Pertanto, se i metodi create accettano array, è possibile aggiungere più trigger, ad esempio questi:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"trigger.create","params":[{"description":"Il carico del processore è troppo elevato su {HOST.NAME}","expression":"last(/Linux server/system.cpu.load[percpu,avg1])>5"},{"description":"Troppi processi su {HOST.NAME}","expression":"avg(/Linux server/proc.num[],5m)>300"}],"id":4}'

La risposta restituita in caso di esito positivo conterrà gli ID dei trigger appena creati:

{
    "jsonrpc": "2.0",
    "result": {
        "triggerids": [
            "17369",
            "17370"
        ]
    },
    "id": 4
}

Aggiornamento di un item

Abilitare un item impostando il suo stato su "0":

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"item.update","params":{"itemid":"10092","status":0},"id":5}'

La risposta corretta conterrà l'ID dell'item aggiornato:

{
    "jsonrpc": "2.0",
    "result": {
        "itemids": [
            "10092"
        ]
    },
    "id": 5
}

Il metodo item.update, così come altri metodi di aggiornamento, può anche accettare array di oggetti e aggiornare più item con una sola chiamata API.

Aggiornamento di più trigger

Abilitare più trigger impostando il loro stato su "0":

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"trigger.update","params":[{"triggerid":"13938","status":0},{"triggerid":"13939","status":0}],"id":6}'

La risposta corretta conterrà gli ID dei trigger aggiornati:

{
    "jsonrpc": "2.0",
    "result": {
        "triggerids": [
            "13938",
            "13939"
        ]
    },
    "id": 6
}

Gestione degli errori

Fino a questo momento, tutto ciò che hai provato ha funzionato correttamente. Ma cosa succederebbe se provassi a effettuare una chiamata non corretta all'API? Prova a creare un altro host chiamando host.create ma omettendo il parametro obbligatorio groups:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"host.create","params":{"host":"Linux server","interfaces":[{"type":1,"main":1,"useip":1,"ip":"192.168.3.1","dns":"","port":"10050"}]},"id":7}'

La risposta conterrà quindi un messaggio di errore:

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Invalid params.",
        "data": "No groups for host \"Linux server\"."
    },
    "id": 7
}

Se si è verificato un errore, invece della proprietà result, l'oggetto di risposta conterrà la proprietà error con i seguenti dati:

code - un codice di errore;
message - un breve riepilogo dell'errore;
data - un messaggio di errore più dettagliato.

Gli errori possono verificarsi in vari casi, ad esempio in presenza di valori di input non corretti, di una sessione scaduta o nel tentativo di accedere a oggetti inesistenti. La tua applicazione dovrebbe essere in grado di gestire correttamente questi tipi di errori.

Versioni dell'API

Per semplificare il versionamento dell'API, a partire da Zabbix 2.0.4, la versione dell'API corrisponde alla versione di Zabbix stessa. È possibile utilizzare il metodo apiinfo.version per conoscere la versione dell'API con cui si sta lavorando. Questo può essere utile per adattare la propria applicazione all'uso di funzionalità specifiche della versione.

Zabbix garantisce la retrocompatibilità delle funzionalità all'interno di una versione principale. Quando apporta modifiche non retrocompatibili tra release principali, Zabbix di solito mantiene le vecchie funzionalità come deprecate nella release successiva, e le rimuove solo nella release seguente. Occasionalmente, Zabbix può rimuovere funzionalità tra release principali senza fornire alcuna retrocompatibilità. È importante non fare mai affidamento su funzionalità deprecate e migrare alle alternative più recenti il prima possibile.

È possibile seguire tutte le modifiche apportate all'API nel registro delle modifiche dell'API.

Approfondimenti

Ora hai conoscenze sufficienti per iniziare a lavorare con la API di Zabbix, tuttavia non fermarti qui. Per ulteriori approfondimenti, ti consigliamo di consultare l'elenco delle API disponibili.

What’s next?

Appendice 1. Commento di riferimento

Docs

18 API

Panoramica