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}. Una variante JSON e una esportazione time-series raw separata coprono i grafici in-app e le curve di potenza ad alta risoluzione; tutte e tre sono descritte 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 dati aggregati da più parchi o portfolio in una sola richiesta
Formati di esportazione multipli: CSV con separatori configurabili per la compatibilità internazionale, più una variante JSON per i grafici in-app
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	Output	Ideale per
CSV da template	`GET /v1/export/metrics/template/{template_uid}`	Download CSV	Report, fogli di calcolo, fatturazione — colonne predefinite, aggregate e consapevoli delle formule su uno o più parchi
JSON da template	`POST /v1/export/metrics/query`	JSON	Grafici e anteprime all'interno della tua applicazione — stesso motore di aggregazione, restituisce righe di valori datati
Time series raw	`POST /v1/export/raw/query`	JSON	Curve di potenza ad alta risoluzione al passo scelto (5m, 15m, 1h, 1d) — query raw arbitrarie, non aggregate

Il percorso CSV da template è l'esportazione metriche canonica e il focus di questa guida. Per un accesso programmatico e basato su formule ai tuoi dati, vedi Linguaggio di query MiroxQL — il modo supportato per interrogare e modellare i dati raw in metriche personalizzate.

Multi-parco in una sola chiamata

Le esportazioni CSV e JSON da template 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.

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)

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_week estende 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