Configuração Inicial para Interação com a API Zabbix

A automação de tarefas e o gerenciamento programático de alertas no Zabbix são funcionalidades poderosas que podem ser alcançadas através de sua API. Para garantir uma integração eficaz, algumas configurações prévias são necessárias.

Ajuste do Modelo de Mensagem de Alerta

Para permitir que sistemas externos interajam com incidentes específicos do Zabbix, é crucial que o ID do Evento ({EVENT.ID}) esteja presente nas mensagens de alerta. Este identificador exclusivo será usado para referenciar e manipular eventos através da API.

Considere a adição de um modelo de mensagem como o seguinte, ou a verificação de um template existente:

Host de Alerta: {HOST.NAME}
Endereço IP: {HOST.IP}
Item Monitorado: {ITEM.NAME}
Severidade do Alerta: {TRIGGER.SEVERITY}
Estado Atual: {TRIGGER.STATUS} Valor={ITEM.LASTVALUE}
Mensagem do Alerta: {TRIGGER.NAME}
Data/Hora do Evento: {EVENT.DATE} {EVENT.TIME}
ID do Evento: {EVENT.ID}

O campo {EVENT.ID} é indispensável para operações de consulta e atualização de problemas via API, garantindo que a ação seja aplicada ao incidente correto.

Obtenção de um Token de Autenticação da API

Para interagir com a API do Zabbix, é necessário um token de autenticação. Este token serve como credencial para as requisições. Ele pode ser gerado na interface web do Zabbix, geralmente na seção de gerenciamento de usuários, onde se pode criar um "API token" específico para a aplicação ou script que fará as chamadas.

Realizando Requisições à API do Zabbix

As interações com a API do Zabbix seguem o padrão JSON-RPC 2.0.

Endpoint da Requisição

O endereço padrão para as requisições à API JSON-RPC do Zabbix geralmente segue o formato:

http(s)://<IP_OU_FQDN_DO_SERVIDOR_ZABBIX>/api_jsonrpc.php

Por exemplo, se o servidor Zabbix estiver acessível em 192.168.140.5, o endpoint seria http://192.168.140.5/api_jsonrpc.php.

Método HTTP e Cabeçalhos

Todas as requisições para a API Zabbix devem ser enviadas utilizando o método HTTP POST. É mandatório incluir o cabeçalho Content-Type com o valor application/json-rpc.

Exemplos de Operações com a API

Consulta de Problemas

Para recuperar detalhes de um ou mais problemas ativos ou históricos, o método problem.get é utilizado. É possível filtrar por diversos critérios, incluindo eventids para problemas específicos.

Exemplo de corpo da requisição:

{
    "jsonrpc": "2.0",
    "method": "problem.get",
    "params": {
        "output": "extend",
        "selectAcknowledges": "extend",
        "selectTags": "extend",
        "selectSuppressionData": "extend",
        "eventids": ["2474", "2475"],
        "recent": true,
        "sortfield": ["eventid"],
        "sortorder": "DESC"
    },
    "auth": "SEU_TOKEN_DA_API_AQUI",
    "id": 1
}

Neste exemplo, eventids espera um array de strings. O valor de auth deve ser substituído pelo token de API gerado na interface do Zabbix. O parâmetro recent: true filtra por problemas recentes que não foram fechados.

Exemplo de resposta bem-sucedida:

{
    "jsonrpc": "2.0",
    "result": [
        {
            "eventid": "2474",
            "source": "0",
            "object": "0",
            "objectid": "23653",
            "clock": "1685496566",
            "ns": "183983534",
            "r_eventid": "0",
            "r_clock": "0",
            "r_ns": "0",
            "correlationid": "0",
            "userid": "0",
            "name": "Falha na conexão do Banco de Dados",
            "acknowledged": "0",
            "severity": "4",
            "opdata": "",
            "acknowledges": [],
            "suppression_data": [],
            "suppressed": "0",
            "urls": [],
            "tags": [
                {
                    "tag": "servico",
                    "value": "database"
                },
                {
                    "tag": "equipe",
                    "value": "dba"
                }
            ]
        }
    ],
    "id": 1
}

A resposta retorna uma lista de objetos de problema, cada um com os detalhes estendidos conforme solicitado pelos parâmetros select*.

Fechamento ou Reconhecimento de Problemas

Para interagir com o estado de um problema (reconhecer, fechar ou ambos), utiliza-se o método event.acknowledge.

Exemplo de corpo da requisição:

{
    "jsonrpc": "2.0",
    "method": "event.acknowledge",
    "params": {
        "eventids": ["2480"],
        "action": 3,
        "message": "Problema resolvido após reinício do serviço."
    },
    "auth": "SEU_TOKEN_DA_API_AQUI",
    "id": 1
}

O campo action nos parâmetros é fundamental e determina a operação a ser executada:

• 1: Fechar o problema sem reconhecê-lo.
• 2: Reconhecer o problema sem fechá-lo.
• 3: Reconhecer e fechar o problema.

O parâmetro message é opcional e permite adicionar uma nota detalhada sobre o reconhecimento ou a resolução do problema.

Exemplo de resposta de sucesso:

{
    "jsonrpc": "2.0",
    "result": {
        "eventids": [
            "2480"
        ]
    },
    "id": 1
}

A resposta indica os IDs dos eventos que foram processados com sucesso pela API.