Utiliser l'API Zabbix

zabbix_utils vous permet d'utiliser l'API Zabbix pour gérer les objets Zabbix, notamment créer des hôtes, mettre à jour des éléments, récupérer des événements, et bien plus encore.

Les requêtes API peuvent être effectuées en mode synchrone ou asynchrone :

• En mode synchrone, votre script Python envoie une requête et attend une réponse avant de continuer, ce qui convient aux opérations simples, séquentielles et prévisibles.
• En mode asynchrone, le script envoie des requêtes sans attendre chaque réponse, ce qui permet à d'autres opérations de s'exécuter en parallèle ; cela est plus efficace pour les requêtes lentes ou les lots de données volumineux.

Les exemples de cette page se concentrent sur le mode synchrone, bien que le mode asynchrone suive des principes similaires. Des exemples supplémentaires sont disponibles dans le dépôt GitHub zabbix_utils.

Importation

Pour utiliser zabbix_utils afin de travailler avec l’API Zabbix, importez la classe ZabbixAPI dans votre script :

from zabbix_utils import ZabbixAPI

Se connecter

Avant d’effectuer des requêtes API, vous devez créer une instance ZabbixAPI et vous connecter à l’API Zabbix.

Choisissez la méthode qui correspond le mieux à votre façon de gérer les identifiants. Vous pouvez utiliser votre nom d’utilisateur et votre mot de passe ou des jetons d’API.

Lors de l'initialisation

Lors de la création d'une instance ZabbixAPI, vous pouvez fournir en une seule fois l'URL de l'interface web Zabbix ainsi que vos identifiants :

# Nom d'utilisateur et mot de passe :
api = ZabbixAPI(url="127.0.0.1/zabbix", user="Admin", password="zabbix")

# Jeton d'API :
api = ZabbixAPI(url="127.0.0.1/zabbix", token="your_api_token")

Si vous préférez regrouper les paramètres de connexion, vous pouvez les transmettre sous la forme d'un dictionnaire Python et le décompresser à l'aide de la syntaxe des arguments nommés de Python :

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

api = ZabbixAPI(**ZABBIX_AUTH)

Utilisation de login()

Vous pouvez d’abord créer une instance de ZabbixAPI avec uniquement l’URL de l’interface web Zabbix, puis utiliser la méthode login() avec vos identifiants :

# Nom d'utilisateur et mot de passe :
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

# Jeton d’API :
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(token="your_api_token")

Utilisation des variables d'environnement

Vous pouvez d'abord stocker vos identifiants comme variables d'environnement, par exemple en utilisant un terminal :

# Nom d'utilisateur et mot de passe :
export ZABBIX_USER="Admin"
export ZABBIX_PASSWORD="zabbix"

# Jeton :
export ZABBIX_TOKEN="your_api_token"

Ensuite, si vous démarrez votre script depuis la même session de terminal, l'instance ZabbixAPI dans le script ne nécessite que l'URL de l'interface web Zabbix :

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

Vous pouvez également stocker l'URL dans une variable d'environnement :

# Nom d'utilisateur et mot de passe :
export ZABBIX_USER="Admin"
export ZABBIX_PASSWORD="zabbix"
export ZABBIX_URL="https://127.0.0.1/zabbix"

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

Lorsque l'URL et les identifiants sont tous définis comme variables d'environnement, l'instance ZabbixAPI dans le script ne nécessite aucun argument :

api = ZabbixAPI()

Déconnexion

Si vous vous êtes connecté à l’aide d’un nom d’utilisateur et d’un mot de passe, appelez la méthode logout() après avoir terminé vos opérations API :

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

Requêtes API

Après vous être connecté, vous pouvez effectuer n'importe quelles requêtes API en appelant les méthodes décrites dans la référence des méthodes de l'API Zabbix.

Les méthodes de l'API sont appelées en utilisant le format suivant :

api_instance.zabbix_object.method(parameters)

Par exemple, pour afficher une liste d'hôtes avec host.get :

# 1. Importer ZabbixAPI depuis zabbix_utils :
from zabbix_utils import ZabbixAPI

# 2. Créer l'instance ZabbixAPI et se connecter :
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

# 3. Récupérer les hôtes correspondant à un filtre :
hosts = api.host.get(
    filter={
        "host": [
            "Zabbix server",
            "Linux server"
        ]
    }
)

# 4. Parcourir les hôtes renvoyés et afficher les détails de chaque hôte :
for host in hosts:
    print(host)

# 5. Se déconnecter de l'API pour fermer la session :
api.logout()

Mode asynchrone

Le mode asynchrone permet à votre script d'envoyer des requêtes API sans attendre que chacune d'elles se termine. Cela peut rendre votre script plus efficace lorsqu'il doit effectuer de nombreuses requêtes API ou lorsque certaines requêtes prennent beaucoup de temps.

Lors de l'utilisation du mode asynchrone, il existe des différences importantes par rapport au mode synchrone :

• Importez le module asyncio de Python (vous devez d'abord installer les dépendances requises).
• Importez AsyncZabbixAPI au lieu de ZabbixAPI.
• Écrivez votre code dans une fonction async.
• Utilisez await lors de l'appel des méthodes de l'API, y compris login() et logout().

Par exemple, pour afficher une liste d'hôtes avec host.get en mode asynchrone :

# 1. Importer asyncio pour le mode asynchrone, et AsyncZabbixAPI depuis zabbix_utils :
import asyncio
from zabbix_utils import AsyncZabbixAPI

# 2. Définir la fonction asynchrone principale où toutes les opérations API seront exécutées :
async def main():

    # 3. Créer une instance AsyncZabbixAPI et se connecter (await obligatoire) :
    api = AsyncZabbixAPI(url="127.0.0.1")
    await api.login(user="User", password="zabbix")

    # 4. Récupérer les hôtes correspondant à un filtre (await obligatoire) :
    hosts = await api.host.get(
        filter={
            "host": [
                "Zabbix server",
                "Linux server"
            ]
        }
    )

    # 5. Parcourir les hôtes renvoyés et afficher les détails de chaque hôte :
    for host in hosts:
        print(host)

    # 6. Se déconnecter de l'API pour fermer la session (await obligatoire) :
    await api.logout()

# 7. Exécuter la fonction asynchrone main() à l'aide de la boucle d'événements d'asyncio :
asyncio.run(main())

Exemples

Les exemples suivants montrent des tâches courantes de l’API Zabbix utilisant la bibliothèque zabbix_utils.

Des exemples supplémentaires sont disponibles dans le répertoire examples du dépôt GitHub zabbix_utils.