Dati di Telemetria

Aggregated APIs

Aggregated APIs vengono utilizzate principalmente quando si desidera ottenere, per un determinato tipo di dati, un unico valore in risposta, che consenta di sintetizzare un determinato trend e/o risultato, 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:

• {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.

Una chiamata aggregata fornisce sempre un unico valore come risposta, che viene manipolato in base alla finestra temporale ed al fuso orario indicati. In questo contesto il parametro {valuetype} è di grande importanza perché varia a seconda della categoria di risorse, quindi di {dataType}, che si vuole ottenere.

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 nella finestra temporale definita da {startDate} ed {endDate}, per il {dataType} richiesto;
• Minimum: restituisce il valore minimo trovato tra tutti i campioni presenti nella finestra temporale definita da {startDate} ed {endDate}, per il {dataType} richiesto;
• Average: restituisce il valore medio di tutti i campioni presenti nella 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 ):

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

• Cumulative: restituisce l’ultimo valore cumulativo disponibile nella finestra temporale definita da {startDate} ed {endDate}, per il {dataType} richiesto;
• Delta: restituisce la differenza tra l’ultimo e il primo valore cumulativo disponibile nella 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 ):