[comment]: # translation:outdated

[comment]: # aside:3

[comment]: # ({d1748010-ebcec779})
# Utilizzo della API di Zabbix

[zabbix\_utils](https://github.com/zabbix/python-zabbix-utils/blob/main/README.md) consente di utilizzare la [API di Zabbix](/manual/api) per gestire gli oggetti di Zabbix, inclusa la creazione di host, l'aggiornamento di item, il recupero di eventi e altro ancora.

Le richieste API possono essere effettuate in modalità sincrona o asincrona:

-   In modalità sincrona, lo script Python invia una richiesta e attende una risposta prima di continuare, il che è adatto per operazioni semplici, sequenziali e prevedibili.
-   In modalità asincrona, lo script invia richieste senza attendere ogni risposta, consentendo ad altre operazioni di procedere in parallelo; questo è più efficiente per richieste lente o grandi quantità di dati.

Gli esempi in questa pagina si concentrano sulla modalità sincrona, sebbene la [modalità asincrona](#asynchronous-mode) segua schemi simili.
Ulteriori esempi sono disponibili nel repository GitHub [zabbix_utils](https://github.com/zabbix/python-zabbix-utils/tree/main/examples).

[comment]: # ({/d1748010-ebcec779})

[comment]: # ({3d27f26b-8304e91c})
#### Importazione

Per utilizzare zabbix\_utils per lavorare con l'API di Zabbix, importa la classe `ZabbixAPI` nel tuo script:

```python
from zabbix_utils import ZabbixAPI
```

::: noteclassic
Se utilizzi già una [libreria Python della community](https://www.zabbix.com/integrations/python), di solito puoi sostituire quell'importazione con `ZabbixAPI` da zabbix\_utils.
:::

[comment]: # ({/3d27f26b-8304e91c})

[comment]: # ({55f43c13-2fe24fc5})
#### Accesso

Prima di effettuare richieste API, è necessario creare un'istanza di `ZabbixAPI` ed effettuare l'accesso alla API di Zabbix.

Scegli il metodo più adatto al modo in cui gestisci le credenziali.
Puoi utilizzare il tuo nome utente e la tua password oppure i [token API](/manual/web_interface/frontend_sections/users/api_tokens).

[comment]: # ({/55f43c13-2fe24fc5})

[comment]: # ({eecbd507-f5ed9f85})
##### Durante l'inizializzazione

Quando si crea un'istanza di `ZabbixAPI`, è possibile fornire in un'unica volta l'URL dell'interfaccia web di Zabbix e le proprie credenziali:

```python
# Nome utente e password:
api = ZabbixAPI(url="127.0.0.1/zabbix", user="Admin", password="zabbix")

# Token API:
api = ZabbixAPI(url="127.0.0.1/zabbix", token="your_api_token")
```

Se si preferisce raggruppare i parametri di connessione, è possibile passarli come dizionario Python e decomprimerlo utilizzando la sintassi degli argomenti con nome di Python:

```python
ZABBIX_AUTH = {
    "url": "127.0.0.1/zabbix",
    "user": "Admin",
    "password": "zabbix"
}

api = ZabbixAPI(**ZABBIX_AUTH)
```

[comment]: # ({/eecbd507-f5ed9f85})

[comment]: # ({5cb46e5e-3bf35a85})
##### Utilizzo di `login()`

Per prima cosa puoi creare un'istanza di `ZabbixAPI` usando solo l'URL dell'interfaccia web di Zabbix e successivamente utilizzare il metodo `login()` con le tue credenziali:

```python
# Nome utente e password:
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

# Token API:
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(token="your_api_token")
```

[comment]: # ({/5cb46e5e-3bf35a85})

[comment]: # ({ff280370-a8fe2b33})
##### Utilizzo delle variabili d'ambiente

Puoi innanzitutto memorizzare le tue credenziali come variabili d'ambiente, ad esempio utilizzando un terminale:

```bash
# Nome utente e password:
export ZABBIX_USER="Admin"
export ZABBIX_PASSWORD="zabbix"

# Token:
export ZABBIX_TOKEN="your_api_token"
```

Quindi, se avvii il tuo script dalla stessa sessione del terminale, l'istanza `ZabbixAPI` nello script richiede solo l'URL dell'interfaccia web di Zabbix:

```python
api = ZabbixAPI(url="127.0.0.1/zabbix")
```

Puoi anche memorizzare l'URL in una variabile d'ambiente:

```bash
# Nome utente e password:
export ZABBIX_USER="Admin"
export ZABBIX_PASSWORD="zabbix"
export ZABBIX_URL="https://127.0.0.1/zabbix"

# Token:
export ZABBIX_TOKEN="your_api_token"
export ZABBIX_URL="https://127.0.0.1/zabbix"
```

Quando l'URL e le credenziali sono tutti impostati come variabili d'ambiente, l'istanza `ZabbixAPI` nello script non richiede alcun argomento:

```python
api = ZabbixAPI()
```

[comment]: # ({/ff280370-a8fe2b33})

[comment]: # ({b539ed93-326ac077})
#### Disconnessione

Se hai effettuato l'accesso utilizzando un nome utente e una password, richiama il metodo `logout()` dopo aver completato le operazioni API:

```python
from zabbix_utils import ZabbixAPI

api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

# API actions go here

api.logout()
```

::: noteclassic
La chiamata al metodo `logout()` non è necessaria quando si utilizzano token API.
:::

[comment]: # ({/b539ed93-326ac077})

[comment]: # ({a94d5334-e970d222})
#### Richieste API

Dopo aver effettuato l'accesso, puoi eseguire qualsiasi richiesta API chiamando i metodi descritti nel [riferimento dei metodi](/manual/api/reference) delle API di Zabbix.

I metodi API vengono chiamati utilizzando il seguente formato:

```python
api_instance.zabbix_object.method(parameters)
```

::: noteclassic
Alcuni nomi di metodi o oggetti dell'API di Zabbix utilizzano parole che in Python sono parole chiave riservate (ad esempio, `import`).
Per evitare errori in Python, aggiungi un trattino basso al nome del metodo o dell'oggetto quando lo utilizzi in Python (ad esempio, `api.configuration.import_`).
:::

Ad esempio, per visualizzare un elenco di host con [`host.get`](/manual/api/reference/host/get):

```python
# 1. Importa ZabbixAPI da zabbix_utils:
from zabbix_utils import ZabbixAPI

# 2. Crea l'istanza ZabbixAPI ed effettua l'accesso:
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

# 3. Recupera gli host che corrispondono a un filtro:
hosts = api.host.get(
    filter={
        "host": [
            "Zabbix server",
            "Linux server"
        ]
    }
)

# 4. Scorri gli host restituiti e stampa i dettagli di ciascun host:
for host in hosts:
    print(host)

# 5. Disconnettiti dall'API per chiudere la sessione:
api.logout()
```

[comment]: # ({/a94d5334-e970d222})

[comment]: # ({7b3e3f97-0e327592})
##### Modalità asincrona

La modalità asincrona consente al tuo script di inviare richieste API senza attendere che ciascuna venga completata.
Questo può rendere il tuo script più efficiente quando deve eseguire molte richieste API o quando alcune richieste richiedono molto tempo.

Quando si utilizza la modalità asincrona, ci sono differenze importanti rispetto alla modalità sincrona:

-   Importa il modulo `asyncio` di Python (devi prima [installare](/devel/python/install) le dipendenze richieste).
-   Importa `AsyncZabbixAPI` invece di `ZabbixAPI`.
-   Scrivi il tuo codice all'interno di una funzione `async`.
-   Usa `await` quando chiami i metodi API, inclusi `login()` e `logout()`.

::: noteimportant
Quando crei un'istanza di `AsyncZabbixAPI`, non puoi effettuare l'accesso [durante l'inizializzazione](#during-initialization).
:::

Ad esempio, per visualizzare un elenco di host con [`host.get`](/manual/api/reference/host/get) in modalità asincrona:

```python
# 1. Importa asyncio per la modalità asincrona e AsyncZabbixAPI da zabbix_utils:
import asyncio
from zabbix_utils import AsyncZabbixAPI

# 2. Definisci la funzione async principale in cui verranno eseguite tutte le operazioni API:
async def main():

    # 3. Crea un'istanza di AsyncZabbixAPI ed effettua l'accesso (è necessario await):
    api = AsyncZabbixAPI(url="127.0.0.1")
    await api.login(user="User", password="zabbix")

    # 4. Recupera gli host che corrispondono a un filtro (è necessario await):
    hosts = await api.host.get(
        filter={
            "host": [
                "Zabbix server",
                "Linux server"
            ]
        }
    )

    # 5. Scorri gli host restituiti e stampa i dettagli di ciascun host:
    for host in hosts:
        print(host)

    # 6. Disconnettiti dall'API per chiudere la sessione (è necessario await):
    await api.logout()

# 7. Esegui la funzione async main() usando l'event loop di asyncio:
asyncio.run(main())
```

[comment]: # ({/7b3e3f97-0e327592})

[comment]: # ({57854c72-5dc3bb95})
#### Esempi

I seguenti esempi mostrano attività comuni dell'API di Zabbix utilizzando la libreria zabbix\_utils.

Ulteriori esempi sono disponibili nella directory `examples` del repository GitHub [zabbix_utils](https://github.com/zabbix/python-zabbix-utils).

[comment]: # ({/57854c72-5dc3bb95})