[comment]: # translation:outdated

[comment]: # aside:2

[comment]: # ({e4e166a4-ebcec779})
# Guide de démarrage rapide

Après avoir [installé](/devel/python/installation) zabbix\_utils, vous pouvez l’utiliser dans votre script.

Ce guide de démarrage rapide vous montre comment :

-   Récupérer le nom d’hôte depuis l’agent Zabbix.
-   Créer un hôte et un élément trapper à l’aide de l’API Zabbix.
-   Envoyer une valeur à l’élément.

Le guide présente le script étape par étape, en expliquant chaque partie au fur et à mesure de son introduction.
Le [script complet](#complete-script) est fourni à la fin de la page.

Le guide suppose également que votre serveur Zabbix, l’agent et l’API s’exécutent localement.

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

[comment]: # ({8ff8a246-7917ae33})
#### Récupérer le nom d'hôte depuis l'agent Zabbix

Commencez par récupérer le nom d'hôte du système sur lequel l'agent Zabbix est en cours d'exécution.
Vous aurez besoin de ce nom d'hôte pour créer un hôte à l'aide de l'API Zabbix.

1\. Importez la classe `Getter` depuis zabbix\_utils.
Cette classe fonctionne comme [Zabbix get](/manual/concepts/get) et vous permet de demander des données à l'agent Zabbix.

2\. Créez une instance de `Getter` qui se connecte à l'agent Zabbix local à l'adresse `127.0.0.1` sur le port `10050`.

3\. Appelez la méthode `get()` sur l'instance `Getter` pour demander le nom d'hôte à l'agent Zabbix.

-   La méthode `get()` prend une clé d'élément comme paramètre et envoie une requête à l'agent Zabbix pour cet élément.
-   La méthode `get()` renvoie un objet, et le nom d'hôte est stocké dans l'attribut `value` de cet objet.
-   [`system.hostname`](/manual/config/items/itemtypes/zabbix_agent#system.hostname) est une clé intégrée de l'agent Zabbix qui renvoie le nom de l'hôte.

```python
from zabbix_utils import Getter

agent = Getter(host='127.0.0.1', port=10050)
hostname = agent.get('system.hostname').value
```

[comment]: # ({/8ff8a246-7917ae33})

[comment]: # ({8f96b279-7bec0e05})
#### Se connecter et se connecter à l’API Zabbix

Ensuite, connectez-vous à l’API Zabbix.
Cela permet à votre script de gérer des objets Zabbix tels que les hôtes et les éléments.

1\. Importez la classe `ZabbixAPI` depuis zabbix\_utils.

2\. Créez une instance de `ZabbixAPI` et indiquez l’URL de votre interface web Zabbix.

3\. Appelez la méthode `login()` sur l’instance `ZabbixAPI` et fournissez votre nom d’utilisateur et votre mot de passe.
Le compte doit disposer de la [permission](/manual/web_interface/frontend_sections/users/user_roles#default-permissions) d’accéder à l’API Zabbix.

4\. Appelez la méthode `logout()` pour fermer la session après les opérations de l’API.

```python
from zabbix_utils import ZabbixAPI

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

# API operations go here

api.logout()
```

[comment]: # ({/8f96b279-7bec0e05})

[comment]: # ({8776420b-6f1a3be3})
#### Créer un hôte dans Zabbix

Maintenant que vous avez le nom d’hôte depuis l’agent Zabbix et que vous êtes connecté à l’API Zabbix, vous pouvez créer un nouvel hôte dans Zabbix.

1\. Appelez la méthode d’API [`host.create()`](/manual/api/reference/host/create) sur l’instance `ZabbixAPI` et fournissez les détails de l’hôte :

-   `host` - définissez-le sur la variable `hostname` contenant le nom d’hôte récupéré depuis l’agent Zabbix.
-   `interfaces` - contient les détails de connexion de l’agent Zabbix exécuté sur l’hôte.
-   `groups` - contient au moins un groupe d’hôtes auquel l’hôte doit appartenir.

2\. Puisque l’API Zabbix renvoie l’ID de l’hôte nouvellement créé, enregistrez cet ID dans la variable `host_id` pour une utilisation ultérieure.

3\. Affichez un message pour confirmer que l’hôte a été créé.

```python
api.host.create(
    host=hostname,
    interfaces=[{
        'type': 1,
        'main': 1,
        'useip': 1,
        'ip': '127.0.0.1',
        'dns': '',
        'port': '10050',
    }],
    groups=[{'groupid': '2'}]
)

host_id = host['hostids'][0]

print(f"Host '{hostname}' created with ID {host_id}")
```

[comment]: # ({/8776420b-6f1a3be3})

[comment]: # ({14e2596a-b8e7e66c})
#### Créer un nouvel élément dans Zabbix

Après avoir créé un hôte, vous pouvez lui ajouter un élément.

1\. Définissez une clé unique pour l’élément à créer.

2\. Appelez la méthode [`item.create()`](/manual/api/reference/item/create) sur l’instance `ZabbixAPI` et fournissez les détails de l’élément :

-   `hostid` - définissez-le sur la variable `host_id` contenant l’ID de l’hôte que vous venez de créer.
-   `name` - un nom pour l’élément.
-   `key_` - définissez-le sur la variable `item_key` que vous venez de définir.
-   `type` - définissez-le sur `2` ([élément trapper](/manual/config/items/itemtypes/trapper)), requis pour recevoir les valeurs envoyées par votre script dans les étapes suivantes.
-   `value_type` - définissez-le sur `3` (numérique non signé), le type de données que cet élément stocke.

3\. Comme l’API Zabbix renvoie l’ID de l’élément nouvellement créé, enregistrez cet ID dans la variable `item_id` pour une utilisation ultérieure.

4\. Affichez un message pour confirmer que l’élément a été créé.

```python
item_key = 'app.myservice.heartbeat'

item = api.item.create(
    hostid=host_id,
    name='App heartbeat',
    key_=item_key,
    type=2,
    value_type=3,
)

item_id = item['itemids'][0]

print(f"Item '{item_key}' created with ID {item_id}")
```

[comment]: # ({/14e2596a-b8e7e66c})

[comment]: # ({6d0ff9a9-10296181})
#### Envoyer une valeur à l'hôte

Maintenant que vous avez créé votre hôte et votre élément de données, vous pouvez lui envoyer des données.

1\. Importez la classe `time` et attendez quelques secondes avant d'envoyer les données.
Cela garantit que Zabbix a entièrement traité votre nouvel hôte et votre nouvel élément de données.

2\. Importez la classe `Sender` depuis zabbix\_utils.
Cette classe fonctionne comme [Zabbix sender](/manual/concepts/sender) et permet à votre script d'envoyer des données à Zabbix.

3\. Créez une instance de `Sender` qui se connecte au serveur Zabbix local à l'adresse `127.0.0.1` sur le port `10051`.

4\. Appelez la méthode `send_value()` sur l'instance `Sender` pour envoyer une valeur à l'élément de données de votre hôte et fournissez les détails suivants :

-   `hostname` - définissez-le sur la variable `hostname` contenant le nom d'hôte que vous avez récupéré depuis Zabbix agent.
-   `item_key` - définissez-le sur la variable `item_key` que vous venez de définir plus tôt dans votre script.
-   `1` - la valeur à envoyer.

4\. Affichez un message pour confirmer que la valeur a été envoyée.

```python
import time
time.sleep(10)

from zabbix_utils import Sender

sender = Sender(server='127.0.0.1', port=10051)

response = sender.send_value(hostname, item_key, 1)

print(f"Sender response: {response}")
```

Une fois ce code exécuté avec succès, vous devriez voir un message de réussite indiquant que Zabbix a reçu votre valeur :

```bash
Sender response: {"processed": 1, "failed": 0, "total": 1, "time": "0.000151", "chunk": 1}
```

Vous pouvez maintenant également vérifier votre interface web Zabbix (*Monitoring > [Latest data](/manual/web_interface/frontend_sections/monitoring/latest_data)*) pour voir la valeur.

[comment]: # ({/6d0ff9a9-10296181})

[comment]: # ({a620a163-3872741b})
#### Script complet

Ci-dessous se trouve le script complet qui combine toutes les étapes : récupération du nom d’hôte, création de l’hôte et de l’élément à l’aide de l’API Zabbix, puis envoi des données à Zabbix.

```python
import time
from zabbix_utils import Getter, ZabbixAPI, Sender

# Récupérer le nom d’hôte depuis l’agent Zabbix
agent = Getter(host='127.0.0.1', port=10050)
hostname = agent.get('system.hostname').value

# Se connecter et s’authentifier à l’API Zabbix
api = ZabbixAPI(url='127.0.0.1/zabbix')
api.login(user='Admin', password='zabbix')

# Créer l’hôte dans Zabbix
host = api.host.create(
    host=hostname,
    interfaces=[{
        'type': 1,
        'main': 1,
        'useip': 1,
        'ip': '127.0.0.1',
        'dns': '',
        'port': '10050',
    }],
    groups=[{'groupid': '2'}]
)

host_id = host['hostids'][0]

print(f"Hôte '{hostname}' créé avec l’ID {host_id}")

# Créer l’élément dans Zabbix
item_key = 'app.myservice.heartbeat'

item = api.item.create(
    hostid=host_id,
    name='App heartbeat',
    key_=item_key,
    type=2,
    value_type=3
)

item_id = item['itemids'][0]

print(f"Élément '{item_key}' créé avec l’ID {item_id}")

# Se déconnecter de l’API
api.logout()

# Attendre que Zabbix traite le nouvel hôte
time.sleep(10)

# Envoyer une valeur à l’hôte
sender = Sender(server='127.0.0.1', port=10051)
response = sender.send_value(hostname, item_key, 1)

print(f"Réponse de l’expéditeur : {response}")
```

[comment]: # ({/a620a163-3872741b})