Usar a API do Zabbix

zabbix_utils permite que você use a API do Zabbix para gerenciar objetos do Zabbix, incluindo a criação de hosts, atualização de items, recuperação de eventos e muito mais.

As requisições à API podem ser feitas em modo síncrono ou assíncrono:

• No modo síncrono, seu script Python envia uma requisição e aguarda uma resposta antes de continuar, o que é adequado para operações simples, sequenciais e previsíveis.
• No modo assíncrono, o script envia requisições sem esperar por cada resposta, permitindo que outras operações prossigam em paralelo; isso é mais eficiente para requisições lentas ou grandes lotes de dados.

Os exemplos nesta página focam no modo síncrono, embora o modo assíncrono siga padrões semelhantes. Exemplos adicionais estão disponíveis no repositório do GitHub zabbix_utils.

Importação

Para usar o zabbix_utils para trabalhar com a API do Zabbix, importe a classe ZabbixAPI em seu script:

from zabbix_utils import ZabbixAPI

Fazer login

Antes de fazer solicitações à API, você deve criar uma instância do ZabbixAPI e fazer login na API do Zabbix.

Escolha o método que melhor se adapta à forma como você gerencia as credenciais. Você pode usar seu nome de usuário e senha ou tokens de API.

Durante a inicialização

Ao criar uma instância de ZabbixAPI, você pode fornecer a URL da interface web do Zabbix e suas credenciais de uma só vez:

# Nome de usuário e senha:
api = ZabbixAPI(url="127.0.0.1/zabbix", user="Admin", password="zabbix")

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

Se preferir agrupar os parâmetros de conexão, você pode passá-los como um dicionário Python e desempacotá-los usando a sintaxe de argumentos nomeados do Python:

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

api = ZabbixAPI(**ZABBIX_AUTH)

Usando login()

Você pode primeiro criar uma instância ZabbixAPI apenas com a URL da interface web do Zabbix e, posteriormente, usar o método login() com suas credenciais:

# Nome de usuário e senha:
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

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

Usando variáveis de ambiente

Você pode primeiro armazenar suas credenciais como variáveis de ambiente, por exemplo, usando um terminal:

# Nome de usuário e senha:
export ZABBIX_USER="Admin"
export ZABBIX_PASSWORD="zabbix"

# Token:
export ZABBIX_TOKEN="your_api_token"

Em seguida, se você iniciar seu script a partir da mesma sessão do terminal, a instância ZabbixAPI no script requer apenas a URL da interface web do Zabbix:

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

Você também pode armazenar a URL em uma variável de ambiente:

# Nome de usuário e senha:
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 a URL e as credenciais estão todas definidas como variáveis de ambiente, a instância ZabbixAPI no script não requer nenhum argumento:

api = ZabbixAPI()

Sair

Se você fez login usando um nome de usuário e senha, chame o método logout() após concluir suas operações de API:

from zabbix_utils import ZabbixAPI

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

# As ações da API vão aqui

api.logout()

Requisições de API

Depois de fazer login, você pode fazer qualquer requisição de API chamando os métodos descritos na referência de métodos da API do Zabbix.

Os métodos da API são chamados usando o seguinte formato:

api_instance.zabbix_object.method(parameters)

Por exemplo, para ver uma lista de hosts com host.get:

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

# 2. Crie a instância do ZabbixAPI e faça login:
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

# 3. Recupere hosts que correspondam a um filtro:
hosts = api.host.get(
    filter={
        "host": [
            "Zabbix server",
            "Linux server"
        ]
    }
)

# 4. Itere sobre os hosts retornados e imprima os detalhes de cada host:
for host in hosts:
    print(host)

# 5. Faça logout da API para fechar a sessão:
api.logout()

Modo assíncrono

O modo assíncrono permite que seu script envie solicitações de API sem esperar que cada uma termine. Isso pode tornar seu script mais eficiente quando ele precisa executar muitas solicitações de API ou quando algumas solicitações demoram muito.

Ao usar o modo assíncrono, há diferenças importantes em relação ao modo síncrono:

• Importe o módulo asyncio do Python (você deve primeiro instalar as dependências necessárias).
• Importe AsyncZabbixAPI em vez de ZabbixAPI.
• Escreva seu código dentro de uma função async.
• Use await ao chamar métodos da API, incluindo login() e logout().

Por exemplo, para ver uma lista de hosts com host.get no modo assíncrono:

# 1. Importe asyncio para modo assíncrono e AsyncZabbixAPI de zabbix_utils:
import asyncio
from zabbix_utils import AsyncZabbixAPI

# 2. Defina a função principal async onde todas as operações da API serão executadas:
async def main():

    # 3. Crie uma instância de AsyncZabbixAPI e faça login (deve aguardar):
    api = AsyncZabbixAPI(url="127.0.0.1")
    await api.login(user="User", password="zabbix")

    # 4. Recupere hosts que correspondam a um filtro (deve aguardar):
    hosts = await api.host.get(
        filter={
            "host": [
                "Zabbix server",
                "Linux server"
            ]
        }
    )

    # 5. Itere sobre os hosts retornados e imprima os detalhes de cada host:
    for host in hosts:
        print(host)

    # 6. Faça logout da API para fechar a sessão (deve aguardar):
    await api.logout()

# 7. Execute a função async main() usando o event loop do asyncio:
asyncio.run(main())

Exemplos

Os exemplos a seguir mostram tarefas comuns da API do Zabbix usando a biblioteca zabbix_utils.

Exemplos adicionais estão disponíveis no diretório examples do repositório zabbix_utils no GitHub.