Aller au contenu
FirstSIDocs

Exemples d'intégration

Des exemples prêts à adapter en PowerShell, Python et curl : outil de tickets, supervision, diagnostic à distance.

Dans les exemples, FIRSTSI_TOKEN contient le jeton et https://console.exemple.fr remplace l'adresse de votre console. Mettez vos propres valeurs.

PowerShell : les postes hors ligne

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

Python : lire une liste jusqu'au bout

Parcourir une liste paginée (read:flows)
import os, requests

BASE = "https://console.exemple.fr/api/v1"
ENTETES = {"Authorization": f"Bearer {os.environ['FIRSTSI_TOKEN']}"}

def tout_lire(route, **filtres):
    curseur = None
    while True:
        params = dict(filtres, **({"cursor": curseur} if curseur else {}))
        r = requests.get(f"{BASE}{route}", headers=ENTETES, params=params, timeout=60)
        r.raise_for_status()
        corps = r.json()
        yield from corps["data"]
        curseur = corps["meta"].get("next_cursor")
        if not curseur:
            break

for flux in tout_lire("/flows", machine="poste-009", period="24h", limit=500):
    print(flux)

Outil de tickets : afficher l'état réseau d'un poste

Quand un ticket cite un poste, votre outil peut aller chercher son résumé NetDiag (portée read:netdiag) :

Résumé NetDiag d'un poste sur 24 h
curl -s "https://console.exemple.fr/api/v1/netdiag/machines/poste-009/summary?period=24h" \
  -H "Authorization: Bearer $FIRSTSI_TOKEN"

La réponse donne la répartition des verdicts (OK, PC, LAN, INFRA, WAN, DNS, SERVICE), les causes principales et la dernière mesure. Souvent, cela suffit pour répondre « c'est le Wi-Fi » ou « c'est le serveur » sans ouvrir la console.

Supervision : les alertes ouvertes

Alertes ouvertes (read:alerts)
curl -s "https://console.exemple.fr/api/v1/alerts" -H "Authorization: Bearer $FIRSTSI_TOKEN"

Pour acquitter une alerte depuis votre outil (portée write:alerts), envoyez une note :

Acquitter une alerte (write:alerts)
curl -s -X POST "https://console.exemple.fr/api/v1/alerts/hm-128/ack" \
  -H "Authorization: Bearer $FIRSTSI_TOKEN" -H "Content-Type: application/json" \
  -d '{"note":"Pris en charge par l'\''astreinte, ticket #1234"}'

L'identifiant d'une alerte commence par son origine : hm-… pour la disponibilité, siem-… pour le SIEM. Les alertes NetDiag (nd-…) ne s'acquittent pas ; elles se ferment d'elles-mêmes quand le poste va mieux.

Lancer un diagnostic sur un poste

Avec la portée write:netdiag, vous pouvez demander un traceroute, un test de débit ou une capture réseau. Le résultat arrive quelques instants plus tard dans les événements du poste.

Traceroute depuis un poste (write:netdiag)
curl -s -X POST "https://console.exemple.fr/api/v1/netdiag/machines/poste-009/actions" \
  -H "Authorization: Bearer $FIRSTSI_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"trace","target":"srv-app-01.vireval.lan"}'
actionEffet
traceTraceroute vers target (nom d'hôte ou adresse ; sans target, vers la passerelle)
speedTest de débit vers le serveur FirstSI (20 Mo en réception, 8 Mo en émission)
captureCapture réseau de seconds secondes (5 à 120, 30 par défaut), consultable dans FirstSI

Chaque écriture est journalisée avec son corps dans l'écran API publique.

Source : · Docs FirstSI · mis à jour le 10/10/2026