[comment]: # ({7cef99ec-92f30379})
# 20 API

[comment]: # ({/7cef99ec-92f30379})

[comment]: # ({d9e959c3-13405b49})
### Panoramica

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](http://www.jsonrpc.org/specification) e la [homepage del formato JSON](http://json.org/).

Per ulteriori informazioni sull'integrazione delle funzionalità di Zabbix nelle applicazioni Python, vedere [libreria Python per Zabbix](/devel/python).

::: noteclassic
L'accesso degli utenti in Zabbix, inclusi sia i dati di configurazione sia quelli storici, dipende dal [tipo di utente](/manual/config/users_and_usergroups/permissions#user-types), dal [ruolo utente](/manual/config/users_and_usergroups/permissions#user-roles) assegnato e dai [gruppi di utenti](/manual/config/users_and_usergroups/usergroup).
:::

[comment]: # ({/d9e959c3-13405b49})

[comment]: # ({76e2a1dd-9cb56d09})
### 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".

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

[comment]: # ({/76e2a1dd-9cb56d09})

[comment]: # ({d3a7ab69-9cb2f5ca})
### 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
avere il seguente aspetto:

```bash
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` oppure
`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](https://www.jsonrpc.org/specification#notification)).

Se la richiesta è corretta, la risposta restituita dall'API dovrebbe avere il seguente aspetto:

```json
{
    "jsonrpc": "2.0",
    "result": "7.4.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.

[comment]: # ({/d3a7ab69-9cb2f5ca})

[comment]: # ({c36376e5-ec5a9f60})
### Flusso di lavoro di esempio

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

[comment]: # ({/c36376e5-ec5a9f60})

[comment]: # ({17ec6118-ef3f5841})
#### Autenticazione

Per accedere a qualsiasi dato in Zabbix, è necessario:

-   utilizzare un [token API](/manual/web_interface/frontend_sections/users/api_tokens) esistente (creato nel frontend di Zabbix o usando la [Token API](/manual/api/reference/token));
-   utilizzare un token di autenticazione ottenuto con il metodo [user.login](/manual/api/reference/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:

```bash
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:

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

[comment]: # ({/17ec6118-ef3f5841})

[comment]: # ({d920bab8-37011a71})
#### Metodi di autorizzazione

[comment]: # ({/d920bab8-37011a71})

[comment]: # ({78bcb6bc-130188f5})
##### 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:

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

::: noteimportant
Se riscontri problemi di autenticazione, consulta [inoltro dell'header Authorization](/manual/installation/known_issues#authorization-header-forwarding).
:::

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](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)).

[comment]: # ({/78bcb6bc-130188f5})

[comment]: # ({8a583b03-8950965e})
##### Tramite cookie di Zabbix

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

[comment]: # ({/8a583b03-8950965e})

[comment]: # ({7f924528-f572ecc2})
#### 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](/manual/api/reference/host/get) per recuperare gli ID, i nomi host e le interfacce di tutti gli [host](/manual/api/reference/host/object) configurati:

Richiesta:

```bash
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
```

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

data.json

```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:

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

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

[comment]: # ({/7f924528-f572ecc2})

[comment]: # ({c9fda4ae-ee2c324f})
#### Creazione di un nuovo item

Ora, crea un nuovo [item](/manual/api/reference/item/object) sull'host "Zabbix
server" utilizzando i dati ottenuti dalla precedente richiesta `host.get`.
Questo può essere fatto usando il metodo
[item.create](/manual/api/reference/item/create):

```bash
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:

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

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

[comment]: # ({/c9fda4ae-ee2c324f})

[comment]: # ({49a2cbe1-5ed44978})
#### Creazione di più trigger

Pertanto, se i *metodi create* accettano array, è possibile aggiungere più
[trigger](/manual/api/reference/trigger/object), ad esempio questi:


```bash
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:

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

[comment]: # ({/49a2cbe1-5ed44978})

[comment]: # ({07f914b6-aa174634})
#### Aggiornamento di un item

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

```bash
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:

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

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

[comment]: # ({/07f914b6-aa174634})

[comment]: # ({bfbd84bd-e217b4a2})
#### Aggiornamento di più trigger

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

```bash
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:

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

::: notetip
Questo è il metodo preferito per l'aggiornamento. Alcuni metodi API, come `host.massupdate`, consentono di scrivere un codice più semplice.
Tuttavia, non è consigliato usare questi metodi, poiché verranno rimossi nelle future release.
:::

[comment]: # ({/bfbd84bd-e217b4a2})

[comment]: # ({a9952ff9-7665e280})
#### 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](/manual/api/reference/host/create) ma omettendo il
parametro obbligatorio `groups`:

```bash
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:

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

[comment]: # ({/a9952ff9-7665e280})

[comment]: # ({0de672ce-c1074d48})
### 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](/manual/api/reference/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.

::: notetip
È possibile seguire tutte le modifiche apportate all'API nel
[registro delle modifiche dell'API](/manual/api/changes).
:::

[comment]: # ({/0de672ce-c1074d48})

[comment]: # ({77690bd2-dfd7315f})
### 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](/manual/api/reference).

[comment]: # ({/77690bd2-dfd7315f})