Datos de Telemetrías

Aggregated APIs

Las Aggregated APIs se utilizan principalmente cuando se desea obtener, para un determinado tipo de datos, un único valor de respuesta, que permite resumir una determinada tendencia y/o resultado, para una ventana de tiempo personalizada.

Este tipo de APIs siempre se estructuran de la siguiente manera:

El path, que le permite apuntar a los recursos deseados, siempre requiere los siguientes parámetros:

• {power,frequency,wind,temperature,voltage,current,energy,kpis}: el tipo de recurso al que apuntar. Este parámetro no especifica los datos reales que desea obtener, sino la categoría general a la que pertenecen los datos deseados (tenga en cuenta que una llamada API solo acepta una categoría a la vez, actualmente no es posible realizar llamadas BULK);
• {entityID}: puede ser un EID de planta o de dispositivo. En el primer caso, el valor obtenido tiene en cuenta la agregación de todos los dispositivos, para los que existe ese valor, a nivel de planta; en el segundo caso, el valor obtenido se refiere al único dispositivo de interés;
• {dataType}: representa los datos reales que se obtendrán. Los dataTypes disponibles varían según los recursos señalados, una descripción detallada está disponible directamente en OpenAPIs Swagger;
• {valuetype}: representa el tipo de criterio de agregación con el que se solicitan los datos a obtener.

Las queries, que permiten filtrar los datos solicitados, requieren siempre los siguientes parámetros:

• {startDate}: el límite inferior que permite definir el comienzo de la ventana de tiempo de interés. Su formato siempre es YYYYMMGG (eg: 20220321);
• {endDate}: el límite superior que permite definir el final de la ventana de tiempo de interés. Su formato es siempre YYYYMMGG (eg: 20220322) y debe ser temporalmente posterior a {startDate};
• {timezone}: permite guiar la llamada API a una correcta recuperación de datos según la zona horaria solicitada.

Una llamada agregada siempre proporciona un único valor como respuesta, que se manipula de acuerdo con la ventana de tiempo y la zona horaria indicada. En este contexto, el parámetro {valuetype} es de gran importancia porque varía según la categoría de recursos, por lo tanto de {dataType}, a obtener.

Para un {dataType} perteneciente a la categoría {power,frequency,wind,temperature,voltage,current,kpis}, el {valueType} puede asumir tres valores diferentes:

• Maximum: devuelve el valor máximo encontrado entre todas las muestras presentes en el definido {startDate} y {endDate} ventana de tiempo, para el {dataType};
• Minimum: devuelve el valor mínimo encontrado entre todas las muestras presentes en el definido {startDate} y {endDate} ventana de tiempo, para el {dataType};
• Average: devuelve el valor promedio de todas las muestras presentes en el {startDate} y {endDate}, ventana de tiempo, para el {dataType};

---

NOTA: para la categoría kpis , las consideraciones anteriores son válidas solo si se denominan Power-Based KPIs. Para obtener más detalles, consulte OpenAPIs Swagger.

---

Echemos un vistazo a algunos casos de uso, donde consideramos una planta ( entityID: 12345678 ) con un solo dispositivo inversor registrado ( entityID : 87654321 ):

Para un {dataType} perteneciente a la categoría {energy,kpis}, el {valueType} puede asumir dos valores diferentes:

• Cumulative: devuelve el último valor acumulativo disponible en la ventana de tiempo definida {startDate} y {endDate} para el {dataType};
• Delta: devuelve la diferencia entre el último y el primer valor acumulativo disponible en el {startDate} y {endDate} para el {dataType};

---

NOTA: para la categoría kpis , las consideraciones anteriores son válidas solo si se denominan Energy-Based KPIs. Para obtener más detalles, consulte OpenAPIs Swagger.

---

Echemos un vistazo a algunos casos de uso, donde consideramos una planta ( entityID: 12345678 ) con un solo dispositivo inversor registrado ( entityID : 87654321 ):