Network Worker API — Netzwerk-Überwachung & Discovery

Der Network Worker ist ein Python-basierter Agent, der SNMP-Polling, SSH-Konfigurationsbackups, Netzwerk-Discovery, Ping-Monitoring und SIP-Monitoring durchführt.

1. Authentifizierung

Alle Endpunkte (außer /download) erfordern einen Bearer Token im Header:

Authorization: Bearer <api_token>

Das Token wird bei der Worker-Einrichtung generiert und in der network_workers-Tabelle gespeichert. Der Worker muss aktiviert sein (is_enabled = true).

Basis-URL: /api/network-worker

2. POST /heartbeat

Worker-Heartbeat — aktualisiert Status und Version.

Antwort (200)

{ "success": true, "poll_interval": 30 }

3. GET /tasks

Holt bis zu 10 ausstehende Tasks. Jeder zurückgegebene Task wird als „gesendet" markiert.

Antwort (200)

{
  "success": true,
  "tasks": [
    {
      "id": 123,
      "type": "snmp_poll_full",
      "parameters": {},
      "device": {
        "id": 1, "ip_address": "192.168.1.1",
        "hostname": "switch-01", "type": "switch",
        "manufacturer": "HP", "model": "2530-48G"
      },
      "snmp": { "version": "v2c", "community": "public", "timeout_ms": 5000, "retries": 2 },
      "ssh": { "username": "admin", "password": "***", "port": 22 }
    }
  ],
  "poll_interval": 30
}

Credentials (snmp, ssh) werden nur mitgeliefert, wenn der Task-Typ sie benötigt und für das Gerät hinterlegt sind.

GET /scheduled-tasks

Holt alle aktiven wiederkehrenden Tasks für autonome Ausführung. Enthält zusätzlich schedule_cron und interval_seconds.

4. POST /results

Übermittelt Ergebnisse für einen bestimmten Task.

Bei wiederkehrenden Tasks wird der Task nach Abschluss automatisch mit neuem next_execution_at zurückgesetzt. Fehlgeschlagene Tasks werden bei verfügbaren Retries erneut gequeued.

5. Daten-Einreichung

POST /data

Übermittelt Daten unabhängig von einem Task (Offline-Betrieb).

POST /data/batch

Batch-Einreichung mehrerer Datensätze auf einmal.

{
  "data_type": "snmp_poll_full",
  "items": [
    { "device_id": 1, "data": { ... } },
    { "device_id": 2, "data": { ... } }
  ]
}

6. Konfiguration & Netzwerke

GET /config

Ruft die Worker-Konfiguration ab.

{
  "success": true,
  "config": {
    "poll_interval": 30,
    "sync_interval": 30,
    "autonomous_check_interval": 60,
    "max_retries": 3,
    "offline_cache_days": 7
  },
  "worker": { "id": 1, "name": "Worker 1", "customer_id": 42 }
}

GET /networks

Verfügbare Netzwerke für Discovery-Scans.

{
  "success": true,
  "networks": [
    { "id": 1, "name": "Office LAN", "cidr": "192.168.1.0/24", "gateway": "192.168.1.1", "vlan_id": 10 }
  ]
}

GET /devices/{'{id}'}/credentials

SNMP- und SSH-Zugangsdaten für ein bestimmtes Gerät (Gerät muss zum Worker-Kunden gehören).

7. Ping-Monitoring

GET /ping-monitors

Aktive Ping-Überwachungsziele für diesen Worker. Zwei Typen:

• Geräte-basiert (mit device_id) — aus den Monitoring-Checks des Geräts
• Standalone (mit target_id) — eigene Ping-Ziele

POST /ping-event

Meldet Ausfall-Start (outage_start) oder -Ende (outage_end). Erstellt/löst automatisch Monitoring-Alerts.

POST /ping-summary

Periodische Latenz-Statistiken (packets_sent, packets_lost, avg/min/max_latency_ms).

8. SIP-Monitoring

GET /sip-monitors

Aktive SIP-Überwachungsziele. Enthält: host, port, transport (udp/tcp), monitor_type (options), uri, interval, timeout, threshold.

POST /sip-event

Status-Änderung melden (event_type: "status_change"). Felder: target_id, previous_status, new_status, response_code, response_time_ms.

POST /sip-summary

Periodische SIP-Statistiken: checks_total, checks_failed, avg/min/max_response_time_ms.

9. Log-Streaming

POST /logs

Überträgt bis zu 100 Log-Einträge pro Request.

{
  "entries": [
    {
      "level": "info",
      "message": "SNMP poll completed for 192.168.1.1",
      "source": "snmp_poller",
      "context": { "device_id": 1, "duration_ms": 450 },
      "timestamp": "2026-03-03T10:00:00Z"
    }
  ]
}

Erlaubte Level: debug, info, warning, error, critical

10. Auto-Update

GET /check-update

GET /api/network-worker/check-update?version=a1b2c3d4e5f6g7h8

{
  "success": true,
  "latest_version": "x9y8z7w6v5u4t3s2",
  "update_available": true,
  "download_url": "https://it-dashboard.de/api/network-worker/download"
}

GET /download (öffentlich)

Worker-Paket als ZIP herunterladen. Keine Authentifizierung erforderlich.

11. Unterstützte Task-Typen