��Ĳ�

Table of Contents

19. API

19. API

Panoramica

L'API ��Ĳ� ti consente di recuperare e modificare a livello di codice il file di configurazione di ��Ĳ� e fornisce l'accesso ai dati storici. �� ampiamente utilizzato per:

Crea nuove applicazioni per lavorare con ��Ĳ�;
Integra ��Ĳ� con software di terze parti;
Automatizzare le attivit�� di routine.

L'API ��Ĳ� �� 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 e .

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

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.

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 ��Ĳ� �� 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 ��Ĳ� 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 ��Ĳ� 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 ��Ĳ�. 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 �����Ĳ�",
                   "interfacce": [
                       {
                           "interfaccia": "1",
                           "ip": "127.0.0.1"
                       }
                   ]
               }
           ],
           "id": 2
       }

Per motivi di prestazioni consigliamo di elencare sempre le propriet�� dell'oggetto che si desidera recuperare ed evitare di recuperare Tutto quanto.

Creazione di un nuovo elemento

Creiamo un nuovo item su "��Ĳ� 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
       }

Il metodo item.create e altri metodi di creazione pu�� anche accettare matrici di oggetti e creare pi�� elementi con un'unica API chiamata.

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
       }

Il metodo item.update e altri metodi di aggiornamento pu�� anche accettare matrici di oggetti e aggiornare pi�� elementi con un'unica chiamata API.

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
       }

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.

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 ��Ĳ� 2.0.4, la versione dell'API corrisponde alla versione di ��Ĳ� 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.

Puoi seguire tutte le modifiche apportate all'API nel file Registro modifiche API.

Ulteriori letture

Ora ne sai abbastanza per iniziare a lavorare con l'API ��Ĳ�, ma non fermarti qui. Per ulteriori letture ti suggeriamo di dare un'occhiata alla lista di API disponibili.

�����Ĳ�

Documentation