Vai al contenuto
FirstSIDocs

Esempi di integrazione

Esempi pronti da adattare in PowerShell, Python e curl: ticketing, supervisione, diagnostica a distanza.

Negli esempi FIRSTSI_TOKEN contiene il token e https://console.esempio.it sostituisce l'indirizzo della vostra console. Mettete i vostri valori.

PowerShell: le postazioni offline

Postazioni offline (read:machines)
$intestazioni = @{ Authorization = "Bearer $env:FIRSTSI_TOKEN" }
$url = "https://console.esempio.it/api/v1/machines?status=offline&limit=500"
$r = Invoke-RestMethod -Uri $url -Headers $intestazioni
$r.data | Select-Object hostname, ip, agent_version, last_seen_at | Format-Table

Python: leggere un elenco fino in fondo

Scorrere un elenco paginato (read:flows)
import os, requests

BASE = "https://console.esempio.it/api/v1"
INTESTAZIONI = {"Authorization": f"Bearer {os.environ['FIRSTSI_TOKEN']}"}

def leggi_tutto(rotta, **filtri):
    cursore = None
    while True:
        params = dict(filtri, **({"cursor": cursore} if cursore else {}))
        r = requests.get(f"{BASE}{rotta}", headers=INTESTAZIONI, params=params, timeout=60)
        r.raise_for_status()
        corpo = r.json()
        yield from corpo["data"]
        cursore = corpo["meta"].get("next_cursor")
        if not cursore:
            break

for flusso in leggi_tutto("/flows", machine="postazione-009", period="24h", limit=500):
    print(flusso)

Ticketing: mostrare lo stato di rete di una postazione

Quando un ticket cita una postazione, il vostro strumento può recuperarne il riepilogo NetDiag (ambito read:netdiag):

Riepilogo NetDiag di una postazione sulle 24 h
curl -s "https://console.esempio.it/api/v1/netdiag/machines/postazione-009/summary?period=24h" \
  -H "Authorization: Bearer $FIRSTSI_TOKEN"

La risposta riporta la ripartizione dei verdetti (OK, PC, LAN, INFRA, WAN, DNS, SERVICE), le cause principali e l'ultima misura. Spesso basta per rispondere «è il Wi-Fi» o «è il server» senza aprire la console.

Supervisione: gli avvisi aperti

Avvisi aperti (read:alerts)
curl -s "https://console.esempio.it/api/v1/alerts" -H "Authorization: Bearer $FIRSTSI_TOKEN"

Per riconoscere un avviso dal vostro strumento (ambito write:alerts), inviate una nota:

Riconoscere un avviso (write:alerts)
curl -s -X POST "https://console.esempio.it/api/v1/alerts/hm-128/ack" \
  -H "Authorization: Bearer $FIRSTSI_TOKEN" -H "Content-Type: application/json" \
  -d '{"note":"Preso in carico dalla reperibilità, ticket #1234"}'

L'identificativo di un avviso inizia con la sua origine: hm-… per la disponibilità, siem-… per il SIEM. Gli avvisi NetDiag (nd-…) non si riconoscono: si chiudono da soli quando la postazione torna a stare bene.

Lanciare una diagnostica su una postazione

Con l'ambito write:netdiag potete chiedere un traceroute, un test di banda o una cattura di rete. Il risultato arriva pochi istanti dopo negli eventi della postazione.

Traceroute da una postazione (write:netdiag)
curl -s -X POST "https://console.esempio.it/api/v1/netdiag/machines/postazione-009/actions" \
  -H "Authorization: Bearer $FIRSTSI_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"trace","target":"srv-app-01.esempio.lan"}'
actionEffetto
traceTraceroute verso target (nome host o indirizzo; senza target, verso il gateway)
speedTest di banda verso il server FirstSI (20 MB in ricezione, 8 MB in invio)
captureCattura di rete di seconds secondi (da 5 a 120, 30 per impostazione predefinita), consultabile in FirstSI

Ogni scrittura viene registrata con il suo corpo nella schermata API pubblica.

Fonte: · Docs FirstSI · aggiornato il 10/10/2026