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

Creare nuove applicazioni che lavorano con Zabbix.
Integrare Zabbix in software di terze parti.
Automatizzare attività di routine.

La Zabbix API è una API basata su HTTP ed è distribuita come parte del frontend. Utilizza il protocollo JSON-RPC 2.0, il che significa due cose:

La API è composta da un insieme di metodi separati.
Le richieste e le risposte tra i client e la API sono codificate usando 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 vostre applicazioni Python, vedere Python library for Zabbix.

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

Struttura

L'API è composta da una serie di metodi raggruppati nominalmente in API separate. Ciascuno dei metodi esegue un'attività specifica. Ad esempio, il metodo host.create appartiene all'host API ed è usato per creare nuovi host. Storicamente, le API sono talvolta indicate come "classi".

La maggior parte delle API contiene almeno quattro metodi: get, create, update e delete per recuperare, creare, aggiornare ed eliminare i dati rispettivamente, ma alcune API possono fornire un insieme di metodi completamente diverso.

Esecuzione delle richieste

Una volta configurato il frontend, puoi usare richieste HTTP remote per chiamare l'API. Per farlo, devi inviare richieste HTTP POST al file api_jsonrpc.php situato nella directory del frontend.
Ad esempio, se il tuo frontend Zabbix è installato in https://example.com/zabbix, una richiesta HTTP per chiamare il metodo apiinfo.version potrebbe essere 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":"apiinfo.version","params":{},"id":1}'

La richiesta deve avere l'intestazione Content-Type impostata su uno di questi valori: application/json-rpc, application/json o application/jsonrequest.

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

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

Se la richiesta è corretta, la risposta restituita dall'API dovrebbe essere simile a questa:

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

Autenticazione

Per accedere a qualsiasi dato in Zabbix, è necessario:

Usare un token API esistente creato nel frontend di Zabbix, sezione Users > API tokens, oppure creato tramite la Token API.
Usare un token di autenticazione ottenuto con il metodo user.login.

Ad esempio, se si volesse ottenere un nuovo token di autenticazione effettuando l'accesso come utente standard Admin, una richiesta JSON avrebbe il seguente aspetto:

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

Flusso di lavoro di esempio

La sezione seguente illustra in modo più dettagliato diversi esempi di utilizzo.

Recupero degli host

Ora disponi di un token di autenticazione utente valido (rappresentato come variabile nei seguenti esempi) 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. In alternativa a 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 del nuovo item creato, che può essere usato per fare riferimento all'item nelle richieste successive:

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

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

Creazione di più trigger

Pertanto, se i metodi di creazione accettano array, puoi aggiungere più trigger, ad esempio questo:

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":"Processor load is too high on {HOST.NAME}","expression":"last(/Linux server/system.cpu.load[percpu,avg1])>5"},{"description":"Too many processes on {HOST.NAME}","expression":"avg(/Linux server/proc.num[],5m)>300"}],"id":4}'

La risposta corretta conterrà gli ID dei trigger appena creati:

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

Aggiornamento di un item

Abilita 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

Abilita 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 errata 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, al posto 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 quando si usano valori di input non corretti, si verifica un timeout della sessione oppure si tenta di accedere a oggetti inesistenti. La tua applicazione dovrebbe essere in grado di gestire in modo corretto questo tipo di errori.

Versioni API

Per semplificare il versioning dell'API, a partire da Zabbix 2.0.4, la versione dell'API corrisponde alla versione di Zabbix stesso. È possibile usare il metodo apiinfo.version per scoprire 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 compatibilità retroattiva delle funzionalità all'interno di una major version. Quando vengono introdotte modifiche non compatibili tra major release, Zabbix in genere lascia le vecchie funzionalità come deprecate nella release successiva e le rimuove solo nella release dopo quella. Occasionalmente, Zabbix può rimuovere funzionalità tra major release senza fornire alcuna compatibilità retroattiva. È importante non fare mai affidamento su funzionalità deprecate e migrare il prima possibile verso alternative più recenti.

È possibile seguire tutte le modifiche apportate all'API nel API changelog.

Ulteriori letture

Ora hai conoscenze sufficienti per iniziare a lavorare con le API di Zabbix, tuttavia non fermarti qui. Per ulteriori letture, ti consigliamo di dare un'occhiata all'elenco delle API disponibili.

What’s next?

Riferimento ai metodi

Docs

16 API

Panoramica