API di esportazione metriche
Estrai dati time-series elaborati e pronti per i report dai tuoi impianti in una singola chiamata — su un parco, molti parchi o interi portfolio. Il sistema di esportazione è costruito attorno a template che definiscono quali metriche esportare e in quale ordine, così gli stessi numeri che vedi in un report generato sono i numeri che ottieni tramite l'API.
Il download CSV canonico è GET /v1/export/metrics/template/{template_uid}. Accanto a esso, un'esportazione per id di metrica e un'esportazione di serie temporali raw offrono lo stesso download CSV per selezioni estemporanee; i tre percorsi sono messi a confronto di seguito.
Apri in Mirox
Costruisci ed esegui un'esportazione in modo interattivo su Esportazione dati ▸ Builder, oppure gestisci i tuoi template su Esportazione dati ▸ Template. Gli stessi template e metriche descritti qui alimentano sia il builder in-app che l'API.
Comprendere i tipi di metriche
La piattaforma Mirox lavora con due tipi distinti di metriche che servono a scopi diversi:
Raccolta di metriche raw
Le metriche raw sono il fondamento dell'infrastruttura dati della piattaforma. Queste metriche sono:
- Raccolte direttamente dall'hardware: estratte da inverter, sensori e data logger
- Memorizzate così come sono nel database time-series: preservano la granularità e la struttura originali
- Ottimizzate per il monitoraggio in tempo reale: abilitano dashboard live e query istantanee
- Multidimensionali: usano label per suddividere i dati per componente, posizione o tipo
- Contatori cumulativi: spesso memorizzano valori di energia totale che crescono nel tempo
- Alta frequenza: possono essere raccolte ogni pochi secondi o minuti
Le metriche raw sono essenziali per il funzionamento del sistema ma non sono ottimizzate per un'esportazione dati intuitiva. Richiedono trasformazione, aggregazione e interpretazione per diventare metriche di business significative.
Per informazioni dettagliate sulla raccolta di metriche raw, vedi Architettura della raccolta metriche.
Metriche di esportazione
Le metriche di esportazione sono metriche elaborate e intuitive progettate specificamente per l'esportazione di dati e la reportistica:
- Pre-aggregate: calcolate su base giornaliera per impostazione predefinita
- Pulite e validate: con controlli di qualità dei dati applicati
- Denominazione intuitiva: identificatori chiari e descrittivi
- Unità coerenti: standardizzate su tutte le metriche
- Pronte per l'analisi: nessuna trasformazione aggiuntiva richiesta
- Orientate al business: focalizzate su KPI ed esigenze di reportistica
Le metriche di esportazione sono identificate da stringhe metric_id (es. energy_grid_daily, availability_technical) e costituiscono il fondamento del sistema di esportazione.
Suggerimento
Quando usi l'API di esportazione metriche, lavori sempre con metriche di esportazione. La raccolta di metriche raw viene automaticamente trasformata in questi formati pronti per l'esportazione dalla piattaforma.
Funzionalità principali
- Esportazioni basate su template: definisci configurazioni di metriche riutilizzabili
- Supporto multi-parco: esporta più parchi o portfolio in una sola richiesta — uniti in una colonna per metrica, oppure divisi in una colonna per parco
- CSV portabile: separatori, simboli decimali e formati data configurabili per la compatibilità internazionale
- Intervalli temporali flessibili: esporta per anno, trimestre, mese, settimana o un singolo giorno
- Opzioni di aggregazione: aggregazione giornaliera, settimanale, mensile, trimestrale o annuale
- Supporto internazionale: formati di data e separatori decimali personalizzabili
- Metriche personalizzate: definisci le tue metriche usando formule MiroxQL
Scegliere l'esportazione giusta
La piattaforma offre tre percorsi di esportazione distinti. Scegli quello che corrisponde al tuo obiettivo:
| Esportazione | Endpoint (GET) | Output | Ideale per |
|---|---|---|---|
| Template | /v1/export/metrics/template/… | Download CSV | Report standard, fogli di calcolo, fatturazione — un quadro di colonne salvato e predefinito su uno o più parchi. Il minimo sforzo e la massima riproducibilità, ma il quadro è statico. |
| Metriche | /v1/export/metrics/query | Download CSV | Scegliere singole metriche — una o più — con la stessa aggregazione per periodo dei template, e creare metriche personalizzate a partire dalle formule. |
| Time series raw | /v1/export/raw/query | Download CSV | Qualsiasi intervallo temporale a qualsiasi passo (5m, 15m, 1h, 1d), senza vincolo di giornate intere. Nessuna formula — in compenso differenze per intervallo, normalizzazione a zero e unione o divisione di più parchi. |
Template e Metriche condividono lo stesso motore di aggregazione: i valori sono aggregati per periodo (giorno, settimana, mese, trimestre, anno), azzerati a ogni periodo così da impilarsi e confrontarsi in modo pulito, e possono essere combinati in metriche personalizzate con le formule MiroxQL. L'esportazione raw scambia il supporto alle formule con un intervallo temporale libero e trasformazioni delle serie. Tutte e tre le esportazioni accettano gli stessi nomi di parametro: una sola selezione alimenta sia l'anteprima nell'app sia il suo link CSV condivisibile. Il percorso CSV da template è l'esportazione metriche canonica e il focus di questa guida.
Le metriche si selezionano per id, non tramite query
Ogni esportazione seleziona le metriche tramite id — gli id salvati di un template, oppure metrics per le esportazioni metriche e raw. Il server risolve ogni id nella propria query limitata al tenant a partire da un registro verificato; il PromQL fornito dal chiamante non viene mai eseguito e un id sconosciuto viene rifiutato con 400. Il catalogo raw è disponibile su GET /v1/metrics/raw.
Multi-parco in una sola chiamata
Tutte le esportazioni accettano parametri di query park e portfolio separati da virgola, così puoi ottenere un'aggregazione a livello di portfolio in una singola richiesta. Quando entrambi sono forniti, i parchi di ciascun portfolio vengono uniti ai parchi elencati esplicitamente.
Più parchi: unire o dividere
multi_park_agg decide come vengono rappresentati più parchi. Il parametro è disponibile su tutte e tre le esportazioni.
| Valore | Risultato |
|---|---|
merge (predefinito) | Una colonna per metrica. I parchi vengono combinati con l'operatore che la metrica dichiara: energia e potenza vengono sommate, tensioni, temperature e rapporti mediati. |
split | Una colonna per parco e per metrica, chiamata <nome parco> - <nome metrica>. Le colonne sono raggruppate per parco: tutte le metriche di un parco insieme, con i parchi ordinati per nome. |
Un'esportazione divisa viene eseguita una volta per parco, così ogni metrica, formula e valore di report è calcolato su quel solo parco. Con un unico parco le due opzioni sono identiche e il parametro viene ignorato.
Dividere moltiplica le colonne
Dieci metriche su otto parchi fanno ottanta colonne. Usa merge per i totali di portfolio e split quando vuoi davvero confrontare i parchi affiancati.
Esportazione per id di metrica
GET /v1/export/metrics/query esporta un qualsiasi insieme di id di metrica senza salvare prima un template: stesso motore di aggregazione, stessi selettori temporali e stesso formato CSV del percorso da template.
| Parametro | Scopo |
|---|---|
metrics | Id di metrica separati da virgola (1-20), ad es. energy_grid_daily,energy_ac_daily |
park / portfolio | UID separati da virgola che delimitano l'esportazione |
year + quarter / month / week / day | L'intervallo di calendario (day richiede month) |
resolution | daily, weekly, monthly, quarterly oppure yearly |
full_week | Solo con risoluzione settimanale: estendere l'intervallo a settimane ISO intere |
multi_park_agg | merge (predefinito) oppure split |
separator_csv / separator_decimal / datetime_format / language | Formattazione CSV e nomi di colonna localizzati |
Un solo vocabolario
Le esportazioni da template, per id di metrica e raw condividono i nomi dei parametri: una stessa selezione vale per tutte e tre, dall'anteprima nell'app al link CSV condivisibile. Il percorso CSV da template è il riferimento; gli altri vi sono stati allineati.
Esportazione time series raw
GET /v1/export/raw/query restituisce il CSV — gli stessi valori mostrati dalla scheda Dati raw. GET /v1/metrics/raw elenca ogni id raw con nome, unità, categoria e l'operatore che applica tra le serie (sum, avg, min o max). Seleziona le serie con metrics, poi modellale:
| Parametro | Scopo |
|---|---|
metrics | Id di metriche raw separati da virgola, ad es. raw_grid_energy_total,raw_power_ac |
start / end / step | Qualsiasi intervallo ISO 8601 a qualsiasi passo (5m, 15m, 1h, 1d) — senza vincolo di giornate intere |
value | plain (come registrato), start_at_zero (il primo valore diventa 0) oppure use_delta (variazione per intervallo invece del totale cumulativo). Una scelta esclusiva. |
multi_park_agg | Con più di un parco: merge (una serie per metrica) oppure split (una serie per parco e per metrica, chiamata <nome parco> - <nome metrica>) |
park / portfolio | UID separati da virgola che delimitano l'esportazione |
separator_csv / separator_decimal / language | Formattazione CSV e nomi di colonna localizzati |
Sistema di template
Cosa sono i template di esportazione?
I template di esportazione sono configurazioni predefinite o personalizzate che specificano:
- Quali metriche includere nell'esportazione
- L'ordine delle metriche nell'output
- I metadati di ciascuna metrica (nome, unità, categoria, descrizione)
I template consentono esportazioni coerenti e ripetibili e possono essere condivisi all'interno di un'organizzazione. Per creare, modificare o condividere template senza scrivere codice, apri Esportazione dati ▸ Template in Mirox.
Template di sistema predefinito
Il sistema fornisce un template predefinito completo che include tutte le metriche essenziali per il monitoraggio e la reportistica dei parchi solari.
Template Report Technical v1 (UID: ABCD12340001):
Questo template completo viene utilizzato sia per la generazione di report PDF che per le esportazioni CSV. Include:
Metriche time-series:
- Produzione di energia (kWh) -
energy_grid_daily - Energia da irraggiamento totale (kWh) -
energy_radiation_daily - Sensore GTI (kWh/m²) -
gti_sensor_daily - GTI meteo (kWh/m²) -
gti_weather_daily - Ore di sole (h) -
sunhours_daily - Disponibilità inverter (%) -
availability_inverter - Disponibilità energia (%) -
availability_energy - Disponibilità dati (%) -
availability_data - Disponibilità sensore (%) -
availability_sensor - Energia persa per spegnimento da rete (kWh) -
energy_shutdown_grid_daily - Energia persa per spegnimento esterno (kWh) -
energy_shutdown_external_daily
Metriche di configurazione report:
- Energia report (kWh) -
energy_report - GTI report incidente (kWh/m²) -
gti_report - GTI report effettivo (kWh/m²) -
gti_report_eff - PR report target (%) -
pr_report
Metriche calcolate (usando MiroxQL):
- Analisi dell'irraggiamento (effettivo, utilizzo meteo, differenza sensore-meteo)
- Target di produzione (basati su meteo, basati su sensore, effettivi, corretti)
- Performance ratio (meteo, sensore, effettivo, corretto)
- Resa specifica (Wh/W)
- Analisi delle perdite (perdite non compensabili)
Dati coerenti tra report ed esportazioni
Questo template viene utilizzato sia per la Generazione di report PDF che per le esportazioni API, garantendo che i report generati internamente e i dati esportati dall'utente contengano esattamente le stesse metriche e gli stessi calcoli. Questa coerenza è una funzionalità centrale della piattaforma e consente una validazione e un confronto dei dati affidabili.
Per informazioni sulle metriche calcolate personalizzate, vedi Linguaggio di query MiroxQL.
Metriche di esportazione disponibili
Tutte le metriche sono calcolate su base giornaliera e possono essere aggregate a intervalli settimanali, mensili, trimestrali o annuali. Ogni metrica include una formula semplificata che mostra come il valore viene derivato dalle metriche raw.
Metriche di produzione di energia
| Metric ID | Nome | Unità | Descrizione | Formula |
|---|---|---|---|---|
energy_grid_daily | Produzione di energia | kWh | Energia giornaliera immessa nella rete | sum(delta(grid_energy_total)) per componente |
energy_ac_daily | Produzione AC | kWh | Produzione giornaliera di energia AC | sum(delta(ac_energy_total)) per componente |
energy_inverter_daily | Produzione inverter | kWh | Produzione giornaliera di energia dagli inverter | sum(delta(inverter_ac_energy_total)) per inverter |
energy_radiation_daily | Energia da irraggiamento totale | kWh | Energia da irraggiamento totale giornaliera | sum(delta(radiation_energy_total)) per componente |
Metriche di spegnimento/perdita
| Metric ID | Nome | Unità | Descrizione | Formula |
|---|---|---|---|---|
energy_shutdown_grid_daily | Energia persa per spegnimento da rete | kWh | Perdita giornaliera di energia dovuta a vincoli di rete | sum(delta(energy_loss_total)) dove type='grid', per componente |
energy_shutdown_external_daily | Energia persa per spegnimento esterno | kWh | Perdita giornaliera di energia dovuta a controllo esterno | sum(delta(energy_loss_total)) dove type='external', per componente |
Metriche di irraggiamento
Le metriche di irraggiamento globale sul piano inclinato (GTI) sono comparabili e misurano la radiazione solare sul piano inclinato dei moduli solari.
| Metric ID | Nome | Unità | Descrizione | Formula |
|---|---|---|---|---|
gti_sensor_daily | Sensore GTI | kWh/m² | Irraggiamento globale sul piano inclinato giornaliero dai sensori | avg(delta(irradiation_total)) dove position='module-level' o fallback |
gti_weather_daily | GTI meteo | kWh/m² | Irraggiamento globale sul piano inclinato giornaliero dalle previsioni meteo | sum(weather_gti) / 4, campionamento: intervalli di 15min |
gti_report | GTI report | kWh/m² | Target GTI dalla configurazione del parco | valore dalla configurazione del parco |
Metriche meteo
| Metric ID | Nome | Unità | Descrizione | Formula |
|---|---|---|---|---|
solar_radiation_daily | Radiazione solare | Wh | Radiazione solare media giornaliera | avg(solar_radiation) su 24h |
sunhours_daily | Ore di sole | h | Ore di sole giornaliere | count(weather_gti > 0) / 4, campionamento: 15min |
Metriche ambientali
| Metric ID | Nome | Unità | Descrizione | Formula |
|---|---|---|---|---|
temperature_ambient_avg | Temperatura ambiente | °C | Temperatura ambiente media giornaliera | avg(ambient_temperature) su 24h |
temperature_module_avg | Temperatura modulo | °C | Temperatura del modulo media giornaliera | avg(module_temperature) su 24h |
wind_speed_avg | Velocità del vento | m/s | Velocità del vento media giornaliera | avg(wind_speed) su 24h |
humidity_avg | Umidità | % | Umidità media giornaliera | avg(humidity) su 24h |
Metriche di disponibilità
| Metric ID | Nome | Unità | Descrizione | Formula |
|---|---|---|---|---|
availability_inverter | Disponibilità inverter | % | Disponibilità inverter basata sulla potenza in uscita e sulle condizioni GTI | avg(1 - count(inverter_power ≤ 0 AND weather_gti > 100)), campionamento: 15min |
availability_technical | Disponibilità tecnica | % | Disponibilità tecnica del sistema | avg(sum(scraper_health == 1) / count(scraper_health)) per sorgente, campionamento: 15min |
availability_data | Disponibilità dati | % | Disponibilità dei dati dall'impianto | 1 - avg(count(grid_energy_total)) dove assente, campionamento: 15min |
availability_sensor | Disponibilità sensore | % | Disponibilità del sensore | 1 - avg(count(solar_radiation)) dove assente, campionamento: 15min |
availability_energy | Disponibilità energia | % | Approssimazione della disponibilità basata sull'energia | 1 - (sum(energy_loss_total) / (sum(grid_energy_total) + sum(energy_loss_total))) |
La disponibilità tecnica cambia nel tempo
L'ambito della metrica availability_technical si espande man mano che vengono aggiunte nuove funzionalità alla piattaforma. Questo può far diminuire il valore quando vengono distribuite nuove funzionalità, anche se i sistemi esistenti funzionano normalmente. Per confronti storici stabili, usa metriche specifiche come availability_inverter, availability_data o availability_sensor.
Metriche delle batterie
Le aggregazioni delle batterie operano a livello di box della gerarchia BESS — la vista canonica "intero BESS" definita dall'enum BATTERY. Vedi la pagina Raccolta metriche per la gerarchia completa dei componenti (ambiente / box / storage / modulo / cella).
| Metric ID | Nome | Unità | Descrizione | Formula |
|---|---|---|---|---|
battery_energy_in_daily | Energia caricata nella batteria | kWh | Energia DC giornaliera caricata nella batteria | sum(delta(battery_box_energy_dc_in_total)) per box |
battery_energy_out_daily | Energia scaricata dalla batteria | kWh | Energia DC giornaliera scaricata dalla batteria | sum(delta(battery_box_energy_dc_out_total)) per box |
battery_soc_avg | Stato di carica della batteria | % | Stato di carica medio giornaliero a livello di box | avg(battery_box_soc) su 24h |
battery_soh_avg | Stato di salute della batteria | % | Stato di salute medio giornaliero a livello di box | avg(battery_box_soh) su 24h |
battery_energy_charged_avg | Energia immagazzinata nella batteria | kWh | Energia media giornaliera attualmente immagazzinata | avg(sum(battery_box_energy_charged)) su 24h |
temperature_battery_avg | Temperatura della batteria | °C | Temperatura media giornaliera della batteria a livello di box | avg(battery_box_temperature) su 24h |
Metriche di report
| Metric ID | Nome | Unità | Descrizione | Formula |
|---|---|---|---|---|
energy_report | Energia report | kWh | Target di energia dalla configurazione del parco | valore dalla configurazione del parco |
Intervallo temporale e aggregazione
Selezionare l'intervallo temporale
Scegli quale porzione di cronologia esportare con questi selettori:
- Anno: un intero anno solare
- Trimestre: un trimestre di un dato anno
- Mese: un singolo mese solare
- Settimana: una singola settimana solare
- Giorno: un singolo giorno (richiede che sia impostato un mese)
Si impostano con il parametro year più uno tra quarter, month, week o day. Mirox non conserva dati precedenti al 2025, quindi year deve essere 2025 o successivo.
Risoluzione di aggregazione
All'interno dell'intervallo selezionato, i valori giornalieri vengono raggruppati alla risoluzione scelta. Le metriche basate su energia e ore vengono sommate; tutte le altre metriche vengono mediate.
Aggregazione giornaliera
- Valori giornalieri raw dall'archivio time-series della piattaforma
- Massima granularità disponibile
- Ideale per analisi dettagliate e risoluzione dei problemi
- Dimensione del file: grande
Aggregazione settimanale
- Dati aggregati per settimana ISO (da lunedì a domenica)
- Include il numero della settimana e le colonne della settimana di calendario
- Un'opzione
full_weekestende le prime e ultime settimane parziali a settimane ISO complete - Adatta all'analisi dei trend
- Dimensione del file: media
Aggregazione mensile
- Dati aggregati per mese solare
- Include la colonna "Giorni nel mese" per la normalizzazione
- Ideale per reportistica e trend a lungo termine
- Dimensione del file: piccola
Aggregazione trimestrale e annuale
- Dati raggruppati per trimestri solari o interi anni
- Ideale per riepiloghi esecutivi e confronti anno su anno
- Dimensione del file: minima
Supporto ai formati internazionali
Separatori CSV
L'API supporta più separatori CSV per la compatibilità regionale:
- Virgola (
,): standard in USA/Regno Unito - Punto e virgola (
;): standard in Germania e in molti paesi europei - Tabulazione (
\t): universale, ottima per l'importazione in Excel - Pipe (
|): alternativa per casi speciali
Separatori decimali
- Punto (
.): standard in USA/Regno Unito (es. 1234.56) - Virgola (
,): standard in Germania e in molti paesi europei (es. 1234,56)
Attenzione
Il separatore CSV e il separatore decimale devono essere diversi per evitare problemi di parsing.
Formati di data
I formati datetime personalizzati possono essere specificati usando la sintassi strftime di Python:
Formati comuni:
%Y-%m-%d: formato ISO (2025-03-15)%d/%m/%Y: formato europeo (15/03/2025)%m/%d/%Y: formato statunitense (03/15/2025)%d.%m.%Y: formato tedesco (15.03.2025)%Y-%m: solo mese (2025-03)%Y-W%W: formato settimana ISO (2025-W11)
Formato di output CSV
I file CSV esportati includono intestazioni con nomi e unità delle metriche. La struttura varia in base all'intervallo di aggregazione:
Esportazione mensile
Include una colonna "Giorni nel mese" per la normalizzazione.
Esportazione settimanale
Include sia la colonna "Data" (formato settimana ISO) che la colonna "Settimana di calendario" (numero della settimana).
Esportazione giornaliera
Una riga per giorno con la data nel formato specificato.
Casi d'uso
Reportistica personalizzata
Crea template di esportazione specializzati per:
- Report di performance mensili
- Aggiornamenti trimestrali per gli stakeholder
- Reportistica di conformità annuale
- Tracciamento di KPI personalizzati
Integrazione con terze parti
Esporta dati per l'integrazione con:
- Sistemi di gestione dell'energia
- Piattaforme di business intelligence
- Software di contabilità del carbonio
- Strumenti di gestione del portfolio
Analisi dei dati
Alimenta i dati esportati nelle tue analisi:
- Benchmarking delle performance
- Analisi dei trend stagionali
- Alimentazione di pipeline di business intelligence e reportistica
Autenticazione e permessi
Tutti gli endpoint di esportazione richiedono una sessione autenticata. Puoi utilizzarli da una sessione del browser o con un token API che porta il gruppo di permessi reporting.
Cosa ti serve:
- Gestione dei template: diritti per leggere, creare, modificare o eliminare template di esportazione all'interno della tua organizzazione. I template di sistema sono in sola lettura per tutti.
- Esportazione metriche: accesso in lettura per esportare i report.
- Accesso ai parchi: ricevi sempre e solo dati per i parchi e i portfolio che hai il permesso di vedere. I parchi richiesti a cui non puoi accedere vengono filtrati silenziosamente — e se non ne rimane nessuno accessibile, la richiesta viene rifiutata.
Best practice
- Scegli i template appropriati: usa i template predefiniti quando possibile, creane di personalizzati per esigenze specifiche
- Seleziona l'aggregazione corretta: usa quella mensile per i report, quella giornaliera per analisi dettagliate
- Imposta i separatori corretti: abbina le impostazioni Excel/CSV locali
- Esportazioni multi-parco: sfrutta le capacità multi-parco per analisi a livello di portfolio
- Riutilizzabilità dei template: crea template a livello di organizzazione per una reportistica coerente
- Usa MiroxQL: definisci metriche calcolate personalizzate per analisi avanzate
Esempio pratico
Per un esempio completo di implementazione della generazione di report personalizzati usando l'API di esportazione metriche, vedi l'Esempio di generatore di report. Questo esempio dimostra come recuperare dati dall'API, elaborarli e generare report personalizzati con visualizzazioni.
Gestione degli errori
Risposte di errore comuni:
- 404 Not Found: il template, il parco o il portfolio non esiste
- 403 Forbidden: permessi insufficienti o nessun parco accessibile
- 422 Validation Error: parametri non validi (es. ID di metrica non validi)
- 400 Bad Request: combinazioni di parametri non valide (es. separatore CSV e separatore decimale uguali)
- 409 Conflict: il nome del template esiste già nell'organizzazione
Funzionalità correlate
- Linguaggio di query MiroxQL — definisci metriche calcolate personalizzate per i tuoi template
- Generazione di report esterni — automatizza le esportazioni CSV da template nel tuo flusso di lavoro di reportistica
- Esempio di generatore di report — un esempio Python eseguibile end-to-end
- Report — generazione automatica di report PDF usando gli stessi template
- Guida ai token API — configura un token API per autenticare le esportazioni