Datos de Telemetrías

Timeseries APIs

Las Timeseries APIs se utilizan principalmente cuando desea obtener, para un determinado tipo de datos, una tendencia detallada, que le permite realizar análisis y representaciones en tiempo real, 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}: {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:

  • {sampleSize}: define la frecuencia de muestreo con la que se obtienen los datos. Cuanto mayor sea la frecuencia de muestreo, menor será la longitud de la matriz de datos obtenida en respuesta (a sampleTime igual a Min5 tendrá más muestras en la matriz de respuesta que un sampleTime igual a Min15);
  • {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}: {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. La elección de la zona horaria afecta las épocas devueltas dentro de l’array de respuesta.

Una llamada de serie temporal generalmente proporciona un array de valores como respuesta.
La longitud de l’array depende directamente del valor {sampleSize} y de la ventana de tiempo definida por el parámetros {startDate} y {endDate} parameters. Una vez que se ha definido una ventana de tiempo de referencia, el valor {sampleSize} dividirá esa ventana con más o menos frecuencia, modificando así la longitud de l’array en respuesta: cuanto mayor sea {sampleSize} valor, la ventana de tiempo se dividirá escasamente, lo que dará como resultado menos elementos en la matriz de respuesta.
Vale la pena mirar un ejemplo directo para explicar mejor estos conceptos.

Ejemplo

Supongamos que queremos representar la tendencia en tiempo real de la energía producida por un inversor, durante el día actual (supongamos que estamos en el equinoccio de primavera). La mejor solución es utilizar una API de Timeseries, que tendrá la siguiente estructura general:

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

Dentro de la estructura genérica anterior sabemos que:

  1. La categoría de recursos a la que apuntar es {power} y, dentro de esta categoría, el {dataType} a llamar es GenerationPower;
  2. El {valueType} para llamar es uno de Maximum, Minimum y Average (consulte el análisis detallado más adelante);
  3. La ventana de tiempo es el día del equinoccio de primavera, por lo tanto {startDate} será 20220321 y {endDate} será 20220322;

Esto lleva a que nuestro llamado tome la siguiente forma:

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

El parámetro {sampleSize} puede tener los siguientes valores:

  • Min5: la ventana de tiempo se divide cada 5 minutos, tomando cada muestra guardada en Aurora Vision (ver Página 1);
  • Min15: la ventana de tiempo se divide cada 15 minutos, se incluyen 3 muestras de Aurora Vision para cada segmento;
  • Min30: la ventana de tiempo se divide cada 30 minutos, se incluyen 6 muestras de Aurora Vision para cada segmento;
  • Hour: la ventana de tiempo se divide cada 60 minutos, se incluyen 12 muestras de Aurora Vision para cada segmento;
  • Day: la ventana de tiempo se corta todos los días, se incluyen 288 muestras de Aurora Vision para cada segmento;
  • Month: la ventana de tiempo se divide cada mes;
  • Year: la ventana de tiempo se divide cada año.

Dado que estamos interesados ​​en representar la tendencia de energía en tiempo real, con la mayor frecuencia posible, elegimos establecer el {sampleSize} en Min5 (no tendría sentido introducir un valor superior al de la ventana de tiempo elegida) y establecer el parámetro {timeZone} en 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 respuesta será un array de cierta longitud en el que cada elemento estará siempre compuesto por la siguiente estructura:

Como podemos ver, la respuesta se compone de:

  • Start: representa la época, que es el valor de tiempo en UTC; cambia de acuerdo con timeZone (diferentes zonas horarias tendrán diferentes épocas para el mismo valor de potencia) y sigue los segmentos temporales definidos por sampleSize;
  • Units: representa la unidad de medida;
  • Value: representa el valor.

Extrapolemos un extracto más grande de la respuesta:

El parámetro start aumenta de elemento a elemento, pasando de un valor de 1647875700 a un valor de 1647876000; si hacemos la diferencia entre las dos épocas, lo que obtenemos son exactamente 5 minutos o, dicho de otro modo, el valor que hemos establecido para el parámetro sampleSize.
From epoch 1647876000 los campos start y value ya no existen; esto se debe a que, suponiendo que la llamada se haya realizado antes de las 16:20 (Europe/Rome), la muestra a la que se hace referencia con esa época es futura y, por tanto, aún no existente. Como tal, Aurora Vision no proporciona el campo dentro del elemento; sin embargo, en una nueva llamada realizada después de las 16:20, lo proporcionará porque se ha rellenado.

El principio sobre la presencia/ausencia de ciertos campos en los elementos de respuesta de una timeseries API (expresado en las últimas líneas del ejemplo anterior) es de fundamental importancia: no se aplica solo en el caso de futuras muestras, pero también y sobre todo en el caso de ausencia total de datos sobre Aurora Vision. Esto permite dar coherencia a las respuestas obtenidas de las API de telemetría, ya que cuando el value rchivado está presente, significa que ese valor realmente existe en Aurora Vision, de lo contrario no estaría presente.

Como fue el caso de las llamadas agregadas, también para las llamadas de series temporales el parámees de gran importancia porque varía según la categoría de recursos, por lo tanto de {dataType}, que se obtendrá y también se ve afectado por el {sampleSize}.

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 dentro de cada intervalo de tiempo, determinado por el valor {sampleSize}, en el definido {startDate} y {endDate} ventana de tiempo, para el {dataType};
  • Minimum: devuelve el valor mínimo encontrado entre todas las muestras dentro de cada intervalo de tiempo, determinado por el valor {sampleSize}, en el definido {startDate} y {endDate} ventana de tiempo, para el {dataType};
  • Average: devuelve el valor promedio de todas las muestras dentro de cada intervalo de tiempo, determinado por el valor {sampleSize}, en el definido {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 ):

Caso de Uso 1

Quiero obtener la energía generada por el inversor en tiempo real, cada 5 minutos, el día del equinoccio de primavera. De esta forma puedo trazar la tendencia y realizar análisis específicos sobre ella.

Análisis de Problemas

Teniendo en cuenta que la relación entre planta y dispositivos registrados es de 1:1, puedo ingresar indistintamente el entityID de uno de los dos. Quiero que se produzca la energía, así que señalaré los recursos de la categoría power y solicitaré GenerationPower. El parámetro sampleSize será igual a Min5, porque quiero obtener todas las muestras. El parámetro valueType puede ser, sólo en este caso, configurado indistintamente como Maximum, Minimum ou Average porque el tiempo la ventana está dividida de tal manera que tiene una sola muestra para cada porción y, por lo tanto, ninguna operación real hace la diferencia si hay una sola muestra como referencia.

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 de Uso 2

Quiero obtener la potencia promedio generada por el inversor cada 15 minutos, en el día del equinoccio de primavera. De esta forma puedo trazar la tendencia y realizar análisis específicos sobre ella.

Análisis de Problemas

Teniendo en cuenta que la relación entre planta y dispositivos registrados es de 1:1, puedo ingresar indistintamente el entityID de uno de los dos.Quiero que se produzca la energía, así que señalaré los recursos de la categoría power y solicitaré GenerationPower. En este caso, el parámetro sampleSize será igual a Min15. El parámetro valueType debe ser Average porque la ventana de tiempo se divide de tal manera que tiene 3 muestras para cada segmento y, por lo tanto, el promedio se realiza en las 3 muestras pertenecientes a cada sector.

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

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

  • Cumulative: devuelve el último valor acumulativo disponible dentro de cada segmento de tiempo, determinado por el valor {sampleSize}, en el definido {startDate} y {endDate} ventana de tiempo, para el {dataType};
  • Delta: devuelve el diferencia entre el último y el primer valor acumulativo disponible dentro de cada segmento de tiempo, determinado por el valor {sampleSize}, en el definido {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 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 ):

Caso de Uso 1

Quiero obtener la energía generada por el inversor en tiempo real, cada 5 minutos, el día del equinoccio de primavera; para trazar la tendencia energética.

Análisis de Problemas

Teniendo en cuenta que la relación entre planta y dispositivos registrados es de 1:1, puedo ingresar indistintamente el entityID de uno de los dos. Quiero la energía producida, así que apuntaré los recursos de la categoría energy y solicitaré la GenerationEnergy. El parámetro sampleSize será igual a Min5 , porque quiero obtener todas las muestras. El parámetro valueType será igual a delta porque la ventana de tiempo se rebana de tal manera que tiene una sola muestra para cada rebanada y, por lo tanto, la diferencia entre las muestras proporcionará la energía realmente producida en los 5 minutos.

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 de Uso 2

Quiero obtener la energía generada por el inversor para cada día de la semana del equinoccio de primavera, para trazar la tendencia energética semanal.

Análisis de Problemas

Teniendo en cuenta que la relación entre planta y dispositivos registrados es de 1:1, puedo ingresar indistintamente el entityID de uno de los dos. Quiero que la energía se genere todos los días de la semana del equinoccio de primavera, así que señalaré los recursos de la categoría energy y solicitaré la GenerationEnergy. El parámetro sampleSize será igual a Day, porque quiero dividir la ventana de tiempo todos los días de la semana. El parámetro valueType será igual a delta porque la ventana de tiempo se divide de tal manera que tiene la diferencia entre la primera y la última muestra de cada día de la semana (ventana de tiempo).

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