🔬 Synopsis Technique

Le script api_samsara.py (V37) est un orchestrateur ETL hybride (REST API / Pandas / SQLAlchemy / SQL Brut). Il interroge simultanément les API Samsara V1 (pour la haute précision odométrique des trips) et V2 (pour les safety-events et stats/history). Sa particularité réside dans sa capacité de traitement asynchrone (ThreadPoolExecutor) et son moteur d’injection de métadonnées JSON directement dans les agrégats relationnels.

📚 Dictionnaire de Lignage : Matrice CRUD Avancée

1. Référentiels d’Identité & Sécurité (Sources & Cibles)

  • Lecture Principale : assoamhd.jsmc_societe (Filtrage par geoloc='samsara' et conditionnel sur --idsoc).

  • Synchronisation assoamhd.groupe : Upsert des Tags Samsara (Mapping trgrpid <> id).

  • Synchronisation assoamhd.jsmc_machines : * Inputs API : make, model, vin, licensePlate (nettoyé via Regex de normalisation SIV ([A-Z]{2}[0-9]{3}[A-Z]{2})).

    • Updates : Mise à jour conditionnelle (on n’écrase pas une marque manuellement qualifiée, vérification via exist['marque'] not in [None, '', '-']).

  • Apprentissage Dynamique assoamhd.param_typologie_securite : Insertion IGNORE des nouveaux labels comportementaux natifs de l’API avec catégorisation par défaut A_CLASSER.

2. Flux Cinématiques et Comportementaux (La Fusion)

  • Flux Primaire assoamhd.agg_trajets_recap (INSERT / UPDATE) :

    • Clé d’unicité (id_trajet_samsara) : vid-start_ms.

    • Champs physiques : distance_km (tolérance < 0.1km rejetée), odo_debut_m, conso_obd_l.

  • Mécanique de Staging « Archéologue » (Safety) :

    • Étape 1 (Pandas) : Création de la table temporaire en mémoire via SQLAlchemy GasoilIndic.tmp_safety_merge (Typage strict : samsaraid VARCHAR(64), event_time DATETIME). Ajout systématique d’un Index SQL sur le couple (samsaraid, event_time) pour optimiser la jointure.

    • Étape 2 (Payload JSON) : Jointure SQL temporelle complexe. Mise à jour de agg_trajets_recap.events_json via JSON_ARRAYAGG encapsulant l’heure et le label pour tout événement où $S.event\_time \in [T.date\_debut, T.date\_fin]$.

3. Flux Thermo-Physiques

  • Table GasoilIndic.i_raw_obd (INSERT) : Utilisation de la technique du « Micro-Batching » (10 identifiants par requête) sur l’endpoint /stats/history pour extraire les courbes de carburant (j) et d’odométrie pure (o).

⚙️ Cœur Algorithmique : Ingénierie des Données

  1. Bouclier de Taux (Rate Limiting) : La fonction safe_api_call intercepte les codes HTTP 429. Au lieu de crasher, le Thread effectue un time.sleep(5) passif avant de relâcher le pool, protégeant l’IP du serveur contre un bannissement Samsara.

  2. Extraction des KPI Comportementaux (Moteur JSON_TABLE) :

    Une fois le JSON injecté dans le trajet, une requête SQL native (optimisée MySQL 8.0) déconstruit le payload via JSON_TABLE. Elle croise chaque événement avec le dictionnaire param_typologie_securite pour calculer les scores finaux : nb_accelerations_brusques, nb_freinages_brusques, nb_virages_dangereux.

  3. Propagation Subprocess (Mode Chirurgical) :

    Le paramètre --idsoc (Dôme de Fer) est hérité par l’exécution de l’appel système subprocess.run(valhalla_cmd). Cela garantit que la chaîne de valeur complète est respectée en cascade sans déborder sur l’espace mémoire d’autres sociétés.

📐 Équations & Normes IPMVP

Déduction du statut d’ignition (Micro-arrêts) :

Samsara V1 ne fournissant pas de statut « Contact coupé » direct sur les Trips, l’algorithme déduit l’état du moteur via une équation de ratio de ralenti ($Ratio_{idle}$).

Le moteur est considéré comme tournant et générant des pertes thermiques stationnaires si et seulement si :

$$Ratio_{idle} = \frac{IdleDuration_{ms}}{TotalDuration_{ms}} > 0.8$$

(Si le véhicule passe plus de 80% de son temps de trajet à l’arrêt, le statut type_coupure est forcé à MOTEUR_TOURNANT, isolant ainsi la surconsommation due au chauffage/climatisation cabine).

Retour en haut