Dados de Telemetria

Timeseries APIs

As Timeseries APIs são usadas principalmente quando você deseja obter, para um determinado tipo de dados, uma tendência detalhada, que permite realizar análises e representações em tempo real, para uma janela de tempo personalizada.

Esse tipo de APIs é sempre estruturado da seguinte forma:

As path, que permite apontar para os recursos desejados, sempre requer os seguintes parâmetros:

  • {power,frequency,wind,temperature,voltage,current,energy,kpis}: o tipo de recurso para apontar. Este parâmetro não especifica os dados reais que você deseja obter, mas a categoria geral à qual os dados desejados pertencem (observe que uma chamada de API só aceita uma categoria por vez, atualmente não é possível fazer chamadas BULK);
  • {entityID}: pode ser uma planta ou um dispositivo EID. No primeiro caso, o valor obtido leva em consideração a agregação de todos os dispositivos, para os quais esse valor existe, em nível de planta; no segundo caso, o valor obtido refere-se ao único dispositivo de interesse;
  • {dataType}: representa os dados reais a serem obtidos. Os dataTypes disponíveis variam de acordo com os recursos apontados, uma descrição detalhada está disponível diretamente no OpenAPIs Swagger;
  • {valuetype}: representa o tipo de critério de agregação com o qual os dados solicitados são a ser obtido.

As queries, que permitem filtrar os dados solicitados, sempre requerem os seguintes parâmetros:

  • {sampleSize}: define a taxa de amostragem com a qual obter dados. Quanto maior a taxa de amostragem, menor o comprimento do array de dados obtido em resposta (a sampleTime igual a Min5 terá mais amostras na matriz de resposta do que um sampleTime igual a Min15);
  • {startDate}: o limite inferior que permite definir o início da janela de tempo de interesse. Seu formato é sempre YYYYMMGG (eg: 20220321);
  • {endDate}: o limite superior que permite definir o fim da janela de tempo de interesse. Seu formato é sempre YYYYMMGG (eg: 20220322) e deve ser temporalmente posterior ao {startDate};
  • {timezone}: permite orientar a chamada da API para uma correta recuperação dos dados de acordo com o fuso horário solicitado. A escolha do fuso horário afeta as épocas retornadas no array de resposta.

Uma chamada de série temporal geralmente fornece um array de valores como resposta.
O comprimento da array depende diretamente do valor de {sampleSize} e da janela de tempo definida pelo {startDate} e {endDate}. Depois que uma janela de tempo de referência for definida, o valor {sampleSize} cortará essa janela com mais ou menos frequência, consequentemente, modificando o comprimento da matriz em resposta: quanto maior for {sampleSize}, quanto mais esparsa a janela de tempo for dividida, resultando em menos elementos na matriz de resposta.
Vale a pena ver um exemplo direto para explicar melhor esses conceitos.

Exemplo

Vamos supor que queremos representar a tendência em tempo real da potência produzida por um inversor, durante o dia atual (suponha que estamos no equinócio da primavera). A melhor solução é usar uma Timeseries API, que terá a seguinte estrutura geraleneral structure:

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 da estrutura genérica acima, sabemos que:

  1. A categoria de recursos a ser visada é {power} e, dentro dessa categoria, o {dataType} a ser chamado é o GenerationPower;
  2. O {valueType} a ser chamado é um de Maximum, Minimum e Average (consulte a análise detalhada mais abaixo);
  3. A janela de tempo é o dia do equinócio da primavera, portanto {startDate} será 20220321 e {endDate} será 20220322;

Isso leva nossa chamada a assumir o seguinte formato:

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

O parâmetro {sampleSize} pode ter os seguintes valores:

  • Min5: a janela de tempo é dividida a cada 5 minutos, tomando todas as amostras salvas no Aurora Vision (consulte a Página 1);
  • Min15: a janela de tempo é fatiada a cada 15 minutos, 3 amostras do Aurora Vision são incluídas para cada fatia;
  • Min30: a janela de tempo é fatiada a cada 30 minutos, 6 amostras do Aurora Vision são incluídas para cada fatia;
  • Hour: a janela de tempo é fatiada a cada 60 minutos, 12 amostras do Aurora Vision são incluídas para cada fatia;
  • Day: a janela de tempo é fatiada todos os dias, 288 amostras do Aurora Vision são incluídas para cada fatia;
  • Month: a janela de tempo é dividida a cada mês;
  • Year: a janela de tempo é dividida a cada ano.

Como estamos interessados ​​em representar a tendência de energia em tempo real, com a maior frequência possível, optamos por definir {sampleSize} como Min5 (não faria sentido inserir um valor maior que o da janela de tempo escolhida) e definir o parâmetro {timeZone} para Europe/Rome:

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

A resposta será um array de um determinado tamanho em que cada elemento será sempre composto pela seguinte estrutura:

Como podemos ver, a resposta é composta por:

  • Start: representa a época, que é o valor da hora em UTC; muda de acordo com o timeZone (diferentes fusos horários terão diferentes épocas para o mesmo valor de potência) e segue as fatias temporais definidas pelo sampleSize;
  • Units: representa a unidade de medida;
  • Value: representa o valor.

Vamos extrapolar um extrato maior da resposta:

O campostart aumenta de elemento para elemento, passando de um valor de 1647875700 para um valor de 1647876000; se fizermos a diferença entre as duas épocas, obteremos exatamente 5 minutos ou, em outras palavras, o valor que definimos para o parâmetro sampleSize.
De epoch 1647876000 os parâmetro start e value não existem mais; isso porque, supondo que a chamada tenha sido feita antes das 16:20 (Europe/Rome), a amostra referida com aquela época está no futuro e, portanto, ainda não existe. Como tal, o Aurora Vision não fornece o campo dentro do elemento; no entanto, em uma nova chamada feita após as 16:20, ele a fornecerá porque foi preenchida.

O princípio da presença/ausência de determinados campos nos elementos de resposta de uma API de série temporal (expresso nas últimas linhas do exemplo acima) é de fundamental importância: não se aplica apenas em no caso de amostras futuras, mas também e sobretudo no caso de completa ausência de dados sobre Aurora Vision. Isso permite dar coerência às respostas obtidas das APIs de telemetrias, pois quando o value arquivado está presente, significa que esse valor realmente existe no Aurora Vision, caso contrário não estaria presente.

Assim como para chamadas agregadas, também para chamadas de série temporal o parâmetro {valuetype} é de grande importância, pois varia de acordo com a categoria dos recursos, portanto de {dataType}, a ser obtido e também é afetado pelo {sampleSize}.

Para um {dataType} pertencente à categoria {power,frequency,wind,temperature,voltage,current,kpis}, o {valueType} pode assumir três valores diferentes:

  • Maximum: retorna o valor máximo encontrado entre todas as amostras dentro de cada fatia de tempo, determinado pelo valor {sampleSize}, na janela de tempo definida {startDate} e {endDate}, para o solicitado {dataType};
  • Minimum: retorna o valor mínimo encontrado entre todas as amostras dentro de cada fatia de tempo, determinado pelo valor {sampleSize}, no janela de tempo definida {startDate} e {endDate}, para o solicitado {dataType};
  • Average: retorna o valor médio de todas as amostras dentro de cada fatia de tempo, determinado pelo valor {sampleSize}, no janela de tempo definida {startDate} e {endDate}, para o solicitado {dataType};

OBSERVAÇÃO: para a categoria kpis , as considerações acima são válidas somente se Power-Based KPIs são chamados. Para obter mais detalhes, consulte OpenAPIs Swagger.

Vamos dar uma olhada em alguns casos de uso, onde consideramcom um único dispositivo inversor registrado ( entityID : 87654321 ):

Caso de Uso 1

Quero obter a energia gerada pelo inversor em tempo real, a cada 5 minutos, no dia do equinócio da primavera. Dessa forma, posso traçar a tendência e realizar análises específicas sobre ela.

Análise de Problemas

Considerando que a relação entre a planta e os dispositivos registrados é 1:1, posso inserir indiferentemente o entityID de um dos dois. Eu quero a energia produzida, então vou apontar os recursos da categoria power e solicitar o GenerationPower. O parâmetro sampleSize será igual a Min5 , porque eu quero obter todas as amostras. O parâmetro valueType pode ser, somente neste caso, definido indiferentemente como Maximum, Minimum ou Average porque o tempo janela é cortada de forma a ter uma única amostra para cada fatia e, portanto, nenhuma operação real faz a diferença se houver uma única amostra como referência.

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

Quero obter a potência média gerada pelo inversor a cada 15 minutos, no dia do equinócio da primavera. Dessa forma, posso traçar a tendência e realizar análises específicas sobre ela.

Análise de Problemas

Considerando que a relação entre a planta e os dispositivos registrados é 1:1, posso inserir indiferentemente o entityID de um dos dois. Eu quero a energia produzida, então vou apontar os recursos da categoria power e solicitar o GenerationPower. Neste caso, o parâmetro sampleSize será igual a Min15. O parâmetro valueType deve ser Average porque a janela de tempo é fatiada de forma a ter 3 amostras para cada fatia e, portanto, a média é realizada nas 3 amostras pertencente a cada fatia.

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 um {dataType} pertencente à categoria {energy,kpis}, o {valueType} pode assumir dois valores diferentes:

  • Cumulative: retorna o último valor cumulativo disponível dentro de cada fatia de tempo, determinado pelo valor {sampleSize}, no definido {startDate} e {endDate} janela de tempo, para o {dataType};
  • Delta: retorna o diferença entre o último e o primeiro valor cumulativo disponível dentro de cada fatia de tempo, determinado pelo valor {sampleSize}, no definido {startDate} e {endDate} janela de tempo, para o {dataType};

OBSERVAÇÃO: para a categoria kpis , as considerações acima são válidas somente se Energy-Based KPIs são chamados. Para obter mais detalhes, consulte OpenAPIs Swagger.

Vamos dar uma olhada em alguns casos de uso, onde consideramcom um único dispositivo inversor registrado ( entityID : 87654321 ):

Caso de Uso 1

Quero obter a energia gerada pelo inversor em tempo real, a cada 5 minutos, no dia do equinócio de primavera; para traçar a tendência de energia.

Análise de Problemas

Considerando que a relação entre a planta e os dispositivos registrados é 1:1, posso inserir indiferentemente o entityID de um dos dois. Eu quero a energia produzida, então vou apontar os recursos da categoria energy e solicitar a GenerationEnergy. O parâmetro sampleSize será igual a Min5 , porque eu quero obter todas as amostras. O parâmetro valueType será igual a delta porque a janela de tempo é fatiada de forma a ter uma única amostra para cada fatia e, portanto, a diferença entre as amostras fornecerá a energia realmente produzida nos 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

Quero obter a energia gerada pelo inversor para todos os dias da semana do equinócio da primavera, a fim de traçar a tendência de energia semanal.

Análise de Problemas

Considerando que a relação entre a planta e os dispositivos registrados é 1:1, posso inserir indiferentemente o entityID de um dos dois. Eu quero a energia gerada todos os dias da semana do equinócio da primavera, então vou apontar os recursos da categoria energy e solicitar a GenerationEnergy. O parâmetro sampleSize será igual a Day, porque quero dividir a janela de tempo todos os dias da semana. O parâmetro valueType será igual a delta porque a janela de tempo é fatiada de forma a ter a diferença entre a primeira e a última amostra de cada dia da semana (janela de tempo).

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