Dati di Telemetria

Timeseries APIs

Timeseries APIs vengono utilizzate principalmente quando si desidera ottenere, per un determinato tipo di dati, un andamento dettagliato, che consenta di eseguire analisi e rappresentazioni in tempo reale, per una finestra temporale personalizzata.

Questa tipologia di APIs è sempre strutturata come segue:

Il path, che permette di puntare alle risorse desiderate, richiede sempre i seguenti parametri:

  • {power,frequency,wind,temperature,voltage,current,energy,kpis}: }: il tipo di risorsa a cui puntare. Questo parametro non specifica i dati effettivi che si vuole ottenere, ma la categoria generale a cui appartengono i dati desiderati (per favore si noti che una chiamata API accetta solo una categoria alla volta, al momento non è possibile effettuare chiamate BULK);
  • {entityID}: può essere un EID di impianto o dispositivo. Nel primo caso, il valore ottenuto tiene conto dell’aggregazione di tutti i dispositivi, per i quali tale valore esiste, a livello di impianto; nel secondo caso, il valore ottenuto riferito al singolo dispositivo di interesse;
  • {dataType}: rappresenta i dati effettivi da ottenere. I dataTypes disponibili variano in base alle risorse indicate, una descrizione dettagliata è disponibile direttamente su OpenAPIs Swagger;
  • {valuetype}: rappresenta il tipo di criterio di aggregazione con cui vengono richiesti i dati da ottenere.

Le queries, che consentono di filtrare i dati di interesse, richiedono sempre i seguenti parametri:

  • {sampleSize}: definisce la frequenza di campionamento con cui ottenere i dati. Più lunga è la frequenza di campionamento, minore è la lunghezza dell’array di dati ottenuto in risposta (un sampleTime uguale a Min5 avrà più campioni nell’array di risposta rispetto ad un sampleTime uguale a Min15);
  • {startDate}: il limite inferiore che permette di definire l’inizio della finestra temporale di interesse. Il suo formato è sempre YYYYMMGG (eg: 20220321);
  • {endDate}: il limite superiore che permette di definire l’inizio della finestra temporale di interesse. Il suo formato è sempre YYYYMMGG (eg: 20220322) e deve essere temporalmente successivo alla {startDate};
  • {timezone}: permette di guidare la chiamata API ad un corretto recupero dei dati in base al fuso orario richiesto. Le scelta del fuso orario ha effetto sugli epochs forniti nell’array di risposta.

Una chiamata a serie temporali di solito fornisce un array di valori come risposta.
La lunghezza dell’array dipende direttamente dal valore di {sampleSize} e dalla finestra temporale definita dai parametri {startDate} ed {endDate}. Una volta definita una finestra temporale di riferimento, il valore {sampleSize} suddividerà quella finestra più o meno frequentemente modificando di conseguenza la lunghezza dell’array in risposta: maggiore è il valore di {sampleSize}, più la finestra temporale avrà minor numero sezioni, risultando quindi in meno elementi nell’array di risposta.
Vale la pena guardare un esempio diretto per spiegare meglio questi concetti.

Esempio

Supponiamo di voler rappresentare l’andamento in tempo reale della potenza prodotta da un inverter, durante la giornata odierna (supponiamo di essere nell’equinozio di primavera). La soluzione migliore è utilizzare una Timeseries API, che avrà la seguente struttura generale:

https://api.auroravision.net/api/rest/v1/stats/{power,frequency,wind,temperature,voltage,current,energy,kpis}/timeseries/12345678/{dataType}/{valueType}?{sampleSize}&{startDate}&{endDate}&{timeZone}

All’interno della struttura generica sopra, sappiamo che:

  1. La categoria di risorse a cui puntare è {power} e, all’interno di questa categoria, il {dataType} da chiamare è GenerationPower;
  2. Il {valueType} da chiamare è uno tra Maximum, Minimum ed Average (fare riferimento all’analisi dettagliata più in basso);
  3. La finestra temporale è il giorno dell’equinozio di primavera, quindi la {startDate} sarà 20220321 e la {endDate} sarà 20220322;

Questo porta la nostra chiamata ad assumere la seguente forma:

https://api.auroravision.net/api/rest/v1/stats/power/timeseries/12345678/GenerationPower/average?{sampleSize}&startDate=20220321&endDate=20220322&{timeZone}

Il parametro {sampleSize} può assumere i seguenti valori:

  • Min5: la finestra temporale viene affettata ogni 5 minuti, prelevando ogni singolo campione salvato su Aurora Vision (vedi Pagina 1);
  • Min15: la finestra temporale viene affettata ogni 15 minuti, includendo 3 campioni Aurora Vision per ogni fetta;
  • Min30: la finestra temporale viene affettata ogni 30 minuti, includendo 6 campioni Aurora Vision per ogni fetta;
  • Hour: la finestra temporale viene affettata ogni 60 minuti, includendo 12 campioni Aurora Vision per ogni fetta;
  • Day: la finestra temporale viene affettata giornalmente, includendo 288 campioni Aurora Vision per ogni fetta;
  • Month: la finestra temporale viene affettata mensilmente;
  • Year: la finestra temporale viene affettata annualmente.

Dato che siamo interessati a rappresentare l’andamento della potenza in tempo reale, il più frequentemente possibile, scegliamo di impostare il {sampleSize} a Min5 (non avrebbe senso inserire un valore maggiore di quello della finestra temporale scelta) ed impostare il parametro {timeZone} ad Europe/Rome:

https://api.auroravision.net/api/rest/v1/stats/power/timeseries/12345678/GenerationPower/average?sampleSize=Min5&startDate=20220321&endDate=20220322&timeZone=Europe/Rome

La risposta sarà un array di una certa lunghezza in cui ogni elemento sarà sempre composto dalla seguente struttura:

Come possiamo vedere, la risposta è composta da:

  • Start: rappresenta l’epoch, che è il valore del tempo in UTC; cambia in base alla timeZone (fusi orari diversi avranno epochs diversi per lo stesso valore di potenza) e segue le fette temporali definite da sampleSize;
  • Units: rappresenta l’unità di misura;
  • Value: rappresenta il valore.

Estrapoliamo un estratto più ampio dalla risposta:

Il parametro start aumenta di elemento in elemento, passando da un valore di 1647875700 ad un valore di 1647876000; se facciamo la differenza tra i due epochs, otteniamo esattamente 5 minuti o, in altre parole, il valore che abbiamo impostato per il parametro sampleSize.
Dall’epoch 1647876000 i parametri start e value non esistono più; questo perché, supponendo che la chiamata sia stata effettuata prima delle 16:20 (Europe/Rome), il campione a cui si fa riferimento con quell’epoch è futuro e, quindi, non ancora esistente. In quanto tale, Aurora Vision non fornisce il parametro all’interno dell’elemento; tuttavia, su una nuova chiamata effettuata dopo le 16:20, lo fornirà perché è stato popolato.

Il principio sulla presenza/assenza di determinati campi negli elementi di risposta di una timeseries API (espresso nelle ultime righe dell’esempio sopra) è di fondamentale importanza: non si applica solo nel caso di campioni futuri, ma anche e soprattutto nel caso di completa assenza di dati su Aurora Vision. Questo permette di dare coerenza alle risposte ottenute dalle APIs di telemetria, perché quando è presente il parametro value, significa che quel valore esiste effettivamente su Aurora Vision altrimenti non sarebbe presente.

Come avveniva per le chiamate aggregate, anche per le chiamate timeseries il parametro {valuetype} è di grande importanza perché varia in base alla categoria di risorse, quindi di {dataType}, da ottenere ed è anche influenzato dal {sampleSize}.

Per un {dataType} appartenente alla categoria {power,frequency,wind,temperature,voltage,current,kpis}, il {valueType} può assumere 3 differenti valori:

  • Maximum: restituisce il valore massimo trovato tra tutti i campioni presenti in ogni intervallo di tempo, determinato dal valore di {sampleSize}, per la finestra temporale definita da {startDate} ed {endDate}, per il {dataType} richiesto;
  • Minimum: restituisce il valore minimo trovato tra tutti i campioni presenti in ogni intervallo di tempo, determinato dal valore di {sampleSize}, per la finestra temporale definita da {startDate} ed {endDate}, per il {dataType} richiesto;
  • Average: restituisce il valore medio tra tutti i campioni presenti in ogni intervallo di tempo, determinato dal valore di {sampleSize}, per la finestra temporale definita da {startDate} ed {endDate}, per il {dataType} richiesto;

NOTA: per la categoria kpis , le considerazioni di cui sopra sono valide solo se vengono chiamati Power-Based KPIs. Per maggiori informazioni, fare riferimento ad OpenAPIs Swagger.

Diamo uno sguardo ad alcuni casi d’uso, in cui consideriamo un impianto ( entityID: 12345678 ) con un unico dispositivo inverter registrato ( entityID : 87654321 ):

Caso d’Uso 1

Voglio ottenere la potenza generata dall’inverter in tempo reale, ogni 5 minuti, nel giorno dell’equinozio di primavera. In questo modo posso tracciare il trend ed eseguire analisi specifiche su di esso.

Analisi del Problema

Considerando che il rapporto tra impianto e dispositivi registrati è 1:1, posso inserire indifferentemente l’ entityID di uno dei due. Voglio la potenza prodotta, quindi punterò le risorse della categoria power e richiederò GenerationPower. Il parametro sampleSize sarà uguale a Min5 , perché voglio ottenere ogni singolo campione. Il parametro valueType può essere, solo in questo caso, impostato indifferentemente come Maximum, Minimum oppure Average perché la finestra temporale è affettata in modo tale da avere un unico campione per ogni fetta e, quindi, nessuna operazione sarà differente se c’è un solo campione come riferimento.

Request

GET   https://api.auroravision.net/api/rest/v1/stats/power/timeseries/12345678/GenerationPower/average?sampleSize=Min5&startDate=20220321&endDate=20220322&timeZone=Europe/Rome

Charted Response

Caso d’Uso 2

Voglio ottenere la potenza media generata dall’inverter ogni 15 minuti, nel giorno dell’equinozio di primavera. In questo modo posso tracciare il trend ed eseguire analisi specifiche su di esso.

Analisi del Problema

Considerando che il rapporto tra impianto e dispositivi registrati è 1:1, posso inserire indifferentemente l’ entityID di uno dei due. Voglio la potenza prodotta, quindi punterò le risorse della categoria power e richiederò la GenerationPower. In questo caso il parametro sampleSize sarà uguale a Min15. Il parametro valueType deve essere Average perché la finestra temporale è affettata in modo tale da avere 3 campioni per ogni fetta e, quindi, la media viene eseguita sui 3 campioni appartenenti a ciascuna fetta.

Request

GET   https://api.auroravision.net/api/rest/v1/stats/power/timeseries/12345678/GenerationPower/average?sampleSize=Min15&startDate=20220321&endDate=20220322&timeZone=Europe/Rome

Charted Response

Per un {dataType} appartenente alla categorie {energy,kpis}, il {valueType} può assumere due differenti valori:

  • Cumulative: restituisce l’ultimo valore cumulativo disponibile all’interno di ogni intervallo di tempo, determinato dal valore di {sampleSize}, per la finestra temporale definita da {startDate} ed {endDate}, per il {dataType} richiesto;
  • Delta: restituisce il differenza tra l’ultimo ed il primo valore cumulativo disponibile all’interno di ogni intervallo di tempo, determinato dal valore di {sampleSize}, per la finestra temporale definita da {startDate} ed {endDate}, per il {dataType}richiesto;

NOTA: per la categoria kpis , le considerazioni di cui sopra sono valide solo se vengono chiamati Energy-Based KPIs. Per maggiori informazioni, fare riferimento ad OpenAPIs Swagger.

Diamo uno sguardo ad alcuni casi d’uso, in cui consideriamo un impianto ( entityID: 12345678 ) con un unico dispositivo inverter registrato ( entityID : 87654321 ):

Caso d’Uso 1

Voglio ottenere l’energia generata dall’inverter in tempo reale, ogni 5 minuti, nel giorno dell’equinozio di primavera; per tracciare l’andamento energetico.

Analisi del Problema

Considerando che il rapporto tra impianto e dispositivi registrati è 1:1, posso inserire indifferentemente l’ entityID di uno dei due. Voglio l’energia prodotta, quindi punterò le risorse della categoria energy e richiederò GenerationEnergy. Il parametro sampleSize sarà uguale a Min5 , perché voglio ottenere ogni singolo campione. Il parametro valueType sarà uguale a delta perché la finestra temporale è affettata in modo tale da avere un unico campione per ogni fetta e, quindi, la differenza tra i campioni fornirà l’energia effettivamente prodotta nei 5 minuti.

Request

GET   https://api.auroravision.net/api/rest/v1/stats/energy/timeseries/12345678/GenerationEnergy/delta?sampleSize=Min5&startDate=20220321&endDate=20220322&timeZone=Europe/Rome

Response

Caso d’Uso 2

Voglio ottenere l’energia generata dall’inverter per ogni giorno della settimana dell’equinozio di primavera, in modo da tracciare l’andamento energetico settimanale.

Analisi del Problema

Considerando che il rapporto tra impianto e dispositivi registrati è 1:1, posso inserire indifferentemente l’ entityID di uno dei due. Voglio l’energia generata ogni singolo giorno della settimana dell’equinozio di primavera, quindi punterò le risorse della categoria energy category e richiederò GenerationEnergy. Il parametro sampleSize sarà uguale a Day, perché voglio dividere la finestra temporale ogni singolo giorno della settimana. Il parametro valueType sarà uguale a delta perché la finestra temporale è suddivisa in modo da avere la differenza tra il primo e l’ultimo campione di ogni giorno della settimana (finestra temporale).

Request

GET   https://api.auroravision.net/api/rest/v1/stats/energy/timeseries/87654321/GenerationEnergy/delta?sampleSize=Day?startDate=20220321&endDate=20220327&timeZone=Europe/Rome

Response

Pages: 1 2 3 4