API Dispositivos - Monitoramento de Rede

Visão Geral

A API Dispositivos permite o gerenciamento e monitoramento de grupos, dispositivos e sensores no Ravi Monitor. A estrutura segue uma hierarquia de grupos → subgrupos → dispositivos → sensores.

Estrutura Hierárquica

Grupos (raiz)
├── Subgrupos
│   ├── Dispositivos
│   │   └── Sensores (com valor1, valor2, valor3, valor4)
│   └── Mais dispositivos...
└── Dispositivos (direto no grupo)
    └── Sensores

Parâmetros Base

Todas as operações de Dispositivos requerem:

action=dispositivo
operation: Operação específica
token: Token com permissão dispositivo

Status dos Sensores

Código	Status	Descrição
1	Offline	Dispositivo/sensor offline
2	Pausado	Monitoramento pausado
3	Alerta	Condição de alerta
4	Crítico	Condição crítica
5	Não testado	Ainda não foi testado
6	OK	Funcionando normalmente
7	Warning	Aviso
20	Falha SNMP	Falha na comunicação SNMP

Operações Disponíveis

1. topology - Topologia Completa

Retorna a estrutura completa do sistema com todos os grupos, subgrupos, dispositivos, sensores e estatísticas globais.

Parâmetros Opcionais

include_devices: "true" ou "false" (padrão: "true")
include_sensors: "true" ou "false" (padrão: "true")

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dispositivo" \
  -d "operation=topology"

Resposta

{
  "topology": {
    "groups": [
      {
        "id": 1,
        "name": "Datacenter Principal",
        "parent_id": 0,
        "subgroups": [
          {
            "id": 2,
            "name": "Servidores",
            "parent_id": 1,
            "subgroups": [],
            "devices": [...],
            "stats": {...}
          }
        ],
        "devices": [
          {
            "id": 1,
            "name": "Router Core",
            "ip": "192.168.1.1",
            "group_id": 1,
            "equipment": "Ubiquiti",
            "sensors": [...],
            "status": {
              "total_sensors": 5,
              "sensors_ok": 4,
              "sensors_alert": 1,
              "overall": "alert"
            }
          }
        ],
        "stats": {
          "total_devices": 10,
          "total_sensors": 50,
          "sensors_ok": 45,
          "sensors_alert": 3,
          "sensors_error": 2,
          "sensors_offline": 0,
          "sensors_paused": 0
        }
      }
    ],
    "root_devices": [...],
    "global_stats": {
      "total_groups": 15,
      "total_devices": 100,
      "total_sensors": 500,
      "sensors_ok": 450,
      "sensors_alert": 30,
      "sensors_error": 10,
      "sensors_offline": 5,
      "sensors_paused": 5
    }
  }
}

2. get_group - Obter Grupo Específico

Retorna um grupo específico com todos os seus subgrupos, dispositivos, sensores e estatísticas.

Parâmetros Obrigatórios

group_id: ID do grupo

Parâmetros Opcionais

include_devices: "true" ou "false" (padrão: "true")
include_sensors: "true" ou "false" (padrão: "true")

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dispositivo" \
  -d "operation=get_group" \
  -d "group_id=5"

Resposta

{
  "group": {
    "id": 5,
    "name": "Filial São Paulo",
    "parent_id": 1,
    "subgroups": [...],
    "devices": [
      {
        "id": 10,
        "name": "Switch Principal",
        "ip": "10.0.1.1",
        "group_id": 5,
        "equipment": "Mikrotik",
        "sensors": [
          {
            "id": 100,
            "name": "CPU Usage",
            "device_id": 10,
            "status": 6,
            "status_text": "OK",
            "value": "45%",
            "tag": "snmp_cpu",
            "unit": "%",
            "schedule": "1min"
          }
        ],
        "status": {
          "total_sensors": 8,
          "sensors_ok": 8,
          "overall": "ok"
        }
      }
    ],
    "stats": {
      "total_devices": 5,
      "total_sensors": 40,
      "sensors_ok": 38,
      "sensors_alert": 2
    }
  }
}

3. get_sensor - Obter Sensor Detalhado

Retorna dados detalhados de um sensor específico, incluindo todos os valores (valor1-4), médias (media1-4), informações do modelo e coletores.

Parâmetros Obrigatórios

sensor_id: ID do sensor

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dispositivo" \
  -d "operation=get_sensor" \
  -d "sensor_id=123"

Resposta

{
  "sensor": {
    "id": 123,
    "name": "Traffic In/Out",
    "device_id": 10,
    "device_name": "Router Core",
    "device_ip": "192.168.1.1",
    "status": 6,
    "status_text": "OK",
    "tag": "snmp_traffic",
    "unit": "Mbps",
    "schedule": "1min",
    "error_count": 0,
    "values": [
      {
        "name": "Traffic In",
        "raw_value": "125.5",
        "extension": "Mbps",
        "average": "98.3"
      },
      {
        "name": "Traffic Out",
        "raw_value": "89.2",
        "extension": "Mbps",
        "average": "72.1"
      }
    ],
    "raw_values": {
      "value1": "125.5",
      "value2": "89.2",
      "value3": null,
      "value4": null
    },
    "averages": {
      "avg1": "98.3",
      "avg2": "72.1",
      "avg3": null,
      "avg4": null
    },
    "model": {
      "id": 15,
      "name": "SNMP Traffic",
      "protocol": 1,
      "type": 2
    },
    "context": {
      "interface": "GigabitEthernet0/1",
      "description": "Uplink Provider"
    }
  }
}

4. alerts - Logs de Alertas

Retorna o histórico de alertas do sistema, incluindo alertas ativos e resolvidos, com informações detalhadas sobre notificações enviadas e duração dos problemas.

Parâmetros Opcionais

group_id: Filtrar por grupo específico
limit: Limite de resultados (padrão: 100)
only_active: "true" para retornar apenas alertas não resolvidos (padrão: "false")

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dispositivo" \
  -d "operation=alerts" \
  -d "only_active=true"

Resposta

{
  "alerts": [
    {
      "id": 456,
      "date": "2024-01-15 10:30:00",
      "device_id": 15,
      "device_name": "Server DB",
      "device_ip": "192.168.1.50",
      "sensor_id": 123,
      "sensor_name": "Disk Usage",
      "tag": "snmp_disk",
      "type": 4,
      "message": [
        {
          "descricao": "Uso de disco em 95% - acima do limite crítico de 90%"
        }
      ],
      "notifications": {
        "telegram": 1,
        "email": 1,
        "whatsapp": 0,
        "push": 1
      },
      "resolved": false,
      "resolved_date": null,
      "duration": {
        "days": 2,
        "hours": 5,
        "minutes": 30,
        "seconds": 45,
        "total_seconds": 192645,
        "formatted": "2 dias, 05:30:45"
      }
    },
    {
      "id": 789,
      "date": "2024-01-10 08:00:00",
      "device_id": 20,
      "device_name": "Server Web",
      "device_ip": "192.168.1.60",
      "sensor_id": 456,
      "sensor_name": "Memory Usage",
      "tag": "snmp_memory",
      "type": 3,
      "message": [
        {
          "descricao": "Uso de memória em 85% - acima do limite de 80%"
        }
      ],
      "notifications": {
        "telegram": 2,
        "email": 2,
        "whatsapp": 0,
        "push": 0
      },
      "resolved": true,
      "resolved_date": "2024-01-10 14:35:20",
      "duration": {
        "days": 0,
        "hours": 6,
        "minutes": 35,
        "seconds": 20,
        "total_seconds": 23720,
        "formatted": "06:35:20"
      }
    }
  ],
  "total": 2
}

Status de Notificações

Valor	Telegram/WhatsApp	Email
0	Não enviado	Não enviado
1	Enviado ao surgir problema	Enviado ao surgir problema
2	Enviado ao resolver problema	Enviado ao resolver problema
3	Falha no envio	Falha no envio

Tipos de Alerta

Tipo	Descrição
1-4	Níveis de severidade (1=baixo, 4=crítico)
5	Informativo
7	Warning
10	Crítico especial

5. search - Buscar Grupos/Dispositivos/Sensores

Busca por nome, IP ou tag em grupos, dispositivos e sensores.

Parâmetros Obrigatórios

query: Termo de busca (mínimo 2 caracteres)

Parâmetros Opcionais

type: "all", "groups", "devices" ou "sensors" (padrão: "all")

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dispositivo" \
  -d "operation=search" \
  -d "query=router"

Resposta

{
  "results": {
    "groups": [
      {
        "id": 3,
        "name": "Routers",
        "parent_id": 1
      }
    ],
    "devices": [
      {
        "id": 1,
        "name": "Router Core",
        "ip": "192.168.1.1",
        "group_id": 3,
        "equipment": "Cisco"
      },
      {
        "id": 2,
        "name": "Router Backup",
        "ip": "192.168.1.2",
        "group_id": 3,
        "equipment": "Cisco"
      }
    ],
    "sensors": [
      {
        "id": 50,
        "name": "Router CPU",
        "device_id": 1,
        "device_name": "Router Core",
        "status": 6,
        "status_text": "OK",
        "tag": "snmp_cpu"
      }
    ]
  }
}

6. list_groups - Listar Grupos

Lista grupos filhos de um grupo pai específico.

Parâmetros Opcionais

parent_id: ID do grupo pai (padrão: 0 para grupos raiz)

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dispositivo" \
  -d "operation=list_groups" \
  -d "parent_id=0"

Resposta

{
  "groups": [
    {
      "id": 1,
      "name": "Datacenter Principal",
      "parent_id": 0
    },
    {
      "id": 2,
      "name": "Filiais",
      "parent_id": 0
    }
  ]
}

7. list_devices - Listar Dispositivos

Lista dispositivos de um grupo específico.

Parâmetros Obrigatórios

group_id: ID do grupo

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dispositivo" \
  -d "operation=list_devices" \
  -d "group_id=1"

Resposta

{
  "devices": [
    {
      "id": 1,
      "name": "Router Core",
      "ip": "192.168.1.1",
      "equipment": "Ubiquiti"
    },
    {
      "id": 2,
      "name": "Switch Principal",
      "ip": "192.168.1.2",
      "equipment": "Mikrotik"
    }
  ]
}

8. get_device - Obter Dispositivo

Retorna dados de um dispositivo específico com seus sensores.

Parâmetros Obrigatórios

device_id: ID do dispositivo

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dispositivo" \
  -d "operation=get_device" \
  -d "device_id=1"

Resposta

{
  "device": {
    "id": 1,
    "name": "Router Core",
    "ip": "192.168.1.1",
    "group_id": 1,
    "equipment": "Ubiquiti",
    "sensors": [
      {
        "id": 10,
        "name": "CPU Usage",
        "status": 6,
        "status_text": "OK",
        "value": "35%",
        "tag": "snmp_cpu"
      },
      {
        "id": 11,
        "name": "Memory Usage",
        "status": 6,
        "status_text": "OK",
        "value": "60%",
        "tag": "snmp_memory"
      }
    ]
  }
}

9. list_sensors - Listar Sensores

Lista sensores de um dispositivo específico.

Parâmetros Obrigatórios

device_id: ID do dispositivo

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dispositivo" \
  -d "operation=list_sensors" \
  -d "device_id=1"

Resposta

{
  "sensors": [
    {
      "id": 10,
      "name": "CPU Usage",
      "status": 6,
      "status_text": "OK",
      "value": "35%",
      "tag": "snmp_cpu",
      "unit": "%"
    }
  ]
}

10. get_sensor_history - Dados Históricos de Sensor

Retorna dados históricos de um sensor específico para análise e geração de relatórios.

Parâmetros Obrigatórios

sensor_id: ID do sensor

Parâmetros Opcionais

start_date: Data início no formato YYYY-MM-DD (padrão: hoje)
end_date: Data fim no formato YYYY-MM-DD (padrão: hoje)
include_stats: "true" ou "false" para incluir estatísticas (padrão: "true")
limit: Limitar número de registros retornados (padrão: 0 = sem limite)

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dispositivo" \
  -d "operation=get_sensor_history" \
  -d "sensor_id=123" \
  -d "start_date=2024-01-01" \
  -d "end_date=2024-01-07" \
  -d "limit=100"

Resposta

{
  "sensor_id": 123,
  "sensor_name": "Traffic In/Out",
  "sensor_tag": "snmp_traffic",
  "start_date": "2024-01-01",
  "end_date": "2024-01-07",
  "data": [
    {
      "timestamp": "2024-01-01 00:00:00",
      "status": 6,
      "status_text": "OK",
      "values": [
        {
          "name": "Traffic In",
          "value": "125.50",
          "unit": "Mbps"
        },
        {
          "name": "Traffic Out",
          "value": "89.20",
          "unit": "Mbps"
        }
      ]
    }
  ],
  "total_records": 10080,
  "returned_records": 100,
  "statistics": {
    "total_records": 10080,
    "status_summary": {
      "1": 0,
      "2": 0,
      "3": 15,
      "4": 2,
      "5": 0,
      "6": 10063,
      "7": 0,
      "20": 0
    },
    "values_stats": {
      "Traffic In": {
        "min": "45.20",
        "max": "892.50",
        "count": 10080,
        "min_date": "2024-01-03 04:15:00",
        "max_date": "2024-01-05 18:30:00",
        "average": "425.67",
        "unit": "Mbps"
      },
      "Traffic Out": {
        "min": "23.10",
        "max": "654.80",
        "count": 10080,
        "min_date": "2024-01-02 03:20:00",
        "max_date": "2024-01-06 19:45:00",
        "average": "312.45",
        "unit": "Mbps"
      }
    }
  }
}

Observações

Estatísticas incluem min/max/média com timestamps de quando os valores foram registrados
Resumo de status mostra quantas leituras tiveram cada status durante o período
Valores são automaticamente formatados para exibição (ex: "125.50 Mbps" ao invés de valores brutos)

11. status_summary - Resumo de Status

Retorna estatísticas gerais de status dos sensores.

Parâmetros Opcionais

group_id: Filtrar por grupo específico

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dispositivo" \
  -d "operation=status_summary"

Resposta

{
  "total_devices": 100,
  "total_sensors": 500,
  "status_counts": {
    "offline": 5,
    "paused": 10,
    "alert": 15,
    "critical": 3,
    "untested": 2,
    "ok": 460,
    "snmp_failure": 5
  }
}

Exemplos Práticos

Script Shell

#!/bin/bash

TOKEN="seu_token_aqui"
API_URL="https://seu-servidor-ravi/api.php"

# Função para obter topologia completa
get_topology() {
    curl -s -X POST "$API_URL" \
        -d "token=$TOKEN" \
        -d "action=dispositivo" \
        -d "operation=topology"
}

# Função para obter grupo específico
get_group() {
    local group_id="$1"

    curl -s -X POST "$API_URL" \
        -d "token=$TOKEN" \
        -d "action=dispositivo" \
        -d "operation=get_group" \
        -d "group_id=$group_id"
}

# Função para obter sensor detalhado
get_sensor() {
    local sensor_id="$1"

    curl -s -X POST "$API_URL" \
        -d "token=$TOKEN" \
        -d "action=dispositivo" \
        -d "operation=get_sensor" \
        -d "sensor_id=$sensor_id"
}

# Função para obter alertas
get_alerts() {
    curl -s -X POST "$API_URL" \
        -d "token=$TOKEN" \
        -d "action=dispositivo" \
        -d "operation=alerts"
}

# Função para buscar
search() {
    local query="$1"

    curl -s -X POST "$API_URL" \
        -d "token=$TOKEN" \
        -d "action=dispositivo" \
        -d "operation=search" \
        -d "query=$query"
}

# Exemplos de uso
get_topology
get_group "5"
get_sensor "123"
get_alerts
search "router"

Script PHP

<?php

/**
 * Obtém a topologia completa do sistema
 *
 * @param bool $includeDevices Incluir dispositivos
 * @param bool $includeSensors Incluir sensores
 * @return array Resposta da API
 */
function obterTopologia($includeDevices = true, $includeSensors = true) {
    $token = 'seu_token_aqui';
    $apiUrl = 'https://seu-servidor-ravi/api.php';

    $data = [
        'token' => $token,
        'action' => 'dispositivo',
        'operation' => 'topology',
        'include_devices' => $includeDevices ? 'true' : 'false',
        'include_sensors' => $includeSensors ? 'true' : 'false'
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 60);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

/**
 * Obtém um grupo específico com todo conteúdo
 *
 * @param int $groupId ID do grupo
 * @param bool $includeDevices Incluir dispositivos
 * @param bool $includeSensors Incluir sensores
 * @return array Resposta da API
 */
function obterGrupo($groupId, $includeDevices = true, $includeSensors = true) {
    $token = 'seu_token_aqui';
    $apiUrl = 'https://seu-servidor-ravi/api.php';

    $data = [
        'token' => $token,
        'action' => 'dispositivo',
        'operation' => 'get_group',
        'group_id' => $groupId,
        'include_devices' => $includeDevices ? 'true' : 'false',
        'include_sensors' => $includeSensors ? 'true' : 'false'
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

/**
 * Obtém dados detalhados de um sensor
 *
 * @param int $sensorId ID do sensor
 * @return array Resposta da API
 */
function obterSensor($sensorId) {
    $token = 'seu_token_aqui';
    $apiUrl = 'https://seu-servidor-ravi/api.php';

    $data = [
        'token' => $token,
        'action' => 'dispositivo',
        'operation' => 'get_sensor',
        'sensor_id' => $sensorId
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

/**
 * Obtém sensores em alerta
 *
 * @param int|null $groupId Filtrar por grupo (opcional)
 * @param int $limit Limite de resultados
 * @return array Resposta da API
 */
function obterAlertas($groupId = null, $limit = 100) {
    $token = 'seu_token_aqui';
    $apiUrl = 'https://seu-servidor-ravi/api.php';

    $data = [
        'token' => $token,
        'action' => 'dispositivo',
        'operation' => 'alerts',
        'limit' => $limit
    ];

    if ($groupId) {
        $data['group_id'] = $groupId;
    }

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

/**
 * Busca grupos, dispositivos e sensores
 *
 * @param string $query Termo de busca
 * @param string $type Tipo de busca (all, groups, devices, sensors)
 * @return array Resposta da API
 */
function buscar($query, $type = 'all') {
    $token = 'seu_token_aqui';
    $apiUrl = 'https://seu-servidor-ravi/api.php';

    $data = [
        'token' => $token,
        'action' => 'dispositivo',
        'operation' => 'search',
        'query' => $query,
        'type' => $type
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

/*
Exemplos de uso:

// Obter topologia completa
$topologia = obterTopologia();

// Obter topologia sem sensores (mais rápido)
$topologiaSimples = obterTopologia(true, false);

// Obter grupo específico
$grupo = obterGrupo(5);

// Obter sensor detalhado
$sensor = obterSensor(123);

// Obter todos os alertas
$alertas = obterAlertas();

// Obter alertas de um grupo específico
$alertasGrupo = obterAlertas(5);

// Buscar por termo
$resultados = buscar('router');

// Buscar apenas dispositivos
$dispositivos = buscar('192.168', 'devices');

// Verificar se há alertas críticos
$alertas = obterAlertas();
foreach ($alertas['alerts'] as $alerta) {
    if ($alerta['status'] == 4) {
        echo "CRÍTICO: " . $alerta['name'] . " em " . $alerta['device_name'] . "\n";
    }
}
*/

?>

Códigos de Retorno

Código	Descrição
`"Group ID is required"`	ID do grupo é obrigatório
`"Device ID is required"`	ID do dispositivo é obrigatório
`"Sensor ID is required"`	ID do sensor é obrigatório
`"Group not found"`	Grupo não encontrado
`"Device not found"`	Dispositivo não encontrado
`"Sensor not found"`	Sensor não encontrado
`"Search query must be at least 2 characters"`	Busca deve ter no mínimo 2 caracteres
`"Invalid device operation"`	Operação inválida
`"Database error"`	Erro no banco de dados

Casos de Uso

Dashboard de Monitoramento

Use topology para construir uma visão geral completa do sistema, ou status_summary para um resumo rápido.

Detalhamento de Problemas

Use alerts para listar todos os problemas ativos, depois get_sensor para investigar cada sensor em alerta.

Navegação Hierárquica

Use list_groups e list_devices para construir uma navegação em árvore interativa.

Busca Rápida

Use search para encontrar rapidamente qualquer grupo, dispositivo ou sensor por nome ou IP.

Limitações

Topologia completa pode ser lenta em sistemas muito grandes (use parâmetros include_devices e include_sensors para otimizar)
Busca limitada a 50 resultados por tipo
Alertas limitados a 100 resultados por padrão

Nota: As estatísticas são calculadas recursivamente, incluindo todos os subgrupos. Para melhor performance em sistemas grandes, considere usar include_sensors=false quando não precisar dos dados dos sensores.