Usar la API de Zabbix

zabbix_utils le permite utilizar la API de Zabbix para gestionar objetos de Zabbix, incluyendo la creación de hosts, actualización de items, recuperación de eventos y más.

Las solicitudes a la API pueden realizarse en modo síncrono o asíncrono:

• En modo síncrono, su script de Python envía una solicitud y espera una respuesta antes de continuar, lo que es adecuado para operaciones simples, secuenciales y predecibles.
• En modo asíncrono, el script envía solicitudes sin esperar cada respuesta, permitiendo que otras operaciones se realicen en paralelo; esto es más eficiente para solicitudes lentas o grandes lotes de datos.

Los ejemplos de esta página se centran en el modo síncrono, aunque el modo asíncrono sigue patrones similares. Hay ejemplos adicionales disponibles en el repositorio de GitHub de zabbix_utils.

Importar

Para utilizar zabbix_utils para trabajar con la API de Zabbix, importe la clase ZabbixAPI en su script:

from zabbix_utils import ZabbixAPI

Iniciar sesión

Antes de realizar solicitudes a la API, debe crear una instancia de ZabbixAPI e iniciar sesión en la API de Zabbix.

Elija el método que mejor se adapte a la forma en que gestiona las credenciales. Puede utilizar su nombre de usuario y contraseña o tokens de API.

Durante la inicialización

Al crear una instancia de ZabbixAPI, puede proporcionar la URL de la interfaz web de Zabbix y sus credenciales de una sola vez:

# Nombre de usuario y contraseña:
api = ZabbixAPI(url="127.0.0.1/zabbix", user="Admin", password="zabbix")

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

Si prefiere agrupar los parámetros de conexión, puede pasarlos como un diccionario de Python y desempaquetarlos usando la sintaxis de argumentos de palabras clave de Python:

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

api = ZabbixAPI(**ZABBIX_AUTH)

Usando login()

Primero puede crear una instancia de ZabbixAPI solo con la URL de la interfaz web de Zabbix y luego usar el método login() con sus credenciales:

# Nombre de usuario y contraseña:
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

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

Uso de variables de entorno

Primero puede almacenar sus credenciales como variables de entorno, por ejemplo, usando una terminal:

# Nombre de usuario y contraseña:
export ZABBIX_USER="Admin"
export ZABBIX_PASSWORD="zabbix"

# Token:
export ZABBIX_TOKEN="your_api_token"

Luego, si inicia su script desde la misma sesión de terminal, la instancia de ZabbixAPI en el script solo requiere la URL de la interfaz web de Zabbix:

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

También puede almacenar la URL en una variable de entorno:

# Nombre de usuario y contraseña:
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"

Cuando la URL y las credenciales están configuradas como variables de entorno, la instancia de ZabbixAPI en el script no requiere ningún argumento en absoluto:

api = ZabbixAPI()

Cerrar sesión

Si ha iniciado sesión utilizando un nombre de usuario y contraseña, llame al método logout() después de completar sus operaciones de API:

from zabbix_utils import ZabbixAPI

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

# Las acciones de la API van aquí

api.logout()

Solicitudes de API

Después de iniciar sesión, puede realizar cualquier solicitud de API llamando a los métodos descritos en la referencia de métodos de la API de Zabbix.

Los métodos de la API se llaman utilizando el siguiente formato:

api_instance.zabbix_object.method(parameters)

Por ejemplo, para ver una lista de hosts con host.get:

# 1. Importe ZabbixAPI desde zabbix_utils:
from zabbix_utils import ZabbixAPI

# 2. Cree la instancia de ZabbixAPI e inicie sesión:
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

# 3. Recupere los hosts que coincidan con un filtro:
hosts = api.host.get(
    filter={
        "host": [
            "Zabbix server",
            "Linux server"
        ]
    }
)

# 4. Itere sobre los hosts devueltos e imprima los detalles de cada host:
for host in hosts:
    print(host)

# 5. Cierre la sesión de la API para cerrar la sesión:
api.logout()

Modo asíncrono

El modo asíncrono permite que tu script envíe solicitudes a la API sin esperar a que cada una termine. Esto puede hacer que tu script sea más eficiente cuando necesita realizar muchas solicitudes a la API o cuando algunas solicitudes tardan mucho tiempo.

Al utilizar el modo asíncrono, existen diferencias importantes en comparación con el modo síncrono:

• Importa el módulo asyncio de Python (primero debes instalar las dependencias requeridas).
• Importa AsyncZabbixAPI en lugar de ZabbixAPI.
• Escribe tu código dentro de una función async.
• Utiliza await al llamar a los métodos de la API, incluyendo login() y logout().

Por ejemplo, para ver una lista de hosts con host.get en modo asíncrono:

# 1. Importa asyncio para el modo asíncrono y AsyncZabbixAPI desde zabbix_utils:
import asyncio
from zabbix_utils import AsyncZabbixAPI

# 2. Define la función principal async donde se ejecutarán todas las operaciones de la API:
async def main():

    # 3. Crea una instancia de AsyncZabbixAPI e inicia sesión (debes usar await):
    api = AsyncZabbixAPI(url="127.0.0.1")
    await api.login(user="User", password="zabbix")

    # 4. Recupera los hosts que coincidan con un filtro (debes usar await):
    hosts = await api.host.get(
        filter={
            "host": [
                "Zabbix server",
                "Linux server"
            ]
        }
    )

    # 5. Itera sobre los hosts devueltos e imprime los detalles de cada host:
    for host in hosts:
        print(host)

    # 6. Cierra la sesión en la API para cerrar la sesión (debes usar await):
    await api.logout()

# 7. Ejecuta la función async main() usando el bucle de eventos de asyncio:
asyncio.run(main())

Ejemplos

Los siguientes ejemplos muestran tareas comunes de la API de Zabbix utilizando la biblioteca zabbix_utils.

Hay ejemplos adicionales disponibles en el directorio examples del repositorio de GitHub zabbix_utils.