Dados de Telemetria

Aggregated APIs

As Aggregated APIs são usadas principalmente quando se deseja obter, para um determinado tipo de dados, um único valor de resposta, que permite resumir uma determinada tendência e/ou resultado, 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:

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

Uma chamada agregada sempre fornece um único valor como resposta, que é manipulado de acordo com a janela de tempo e o fuso horário indicados. Nesse contexto, o parâmetro {valuetype} é de grande importância, pois varia de acordo com a categoria de recursos, portanto de {dataType}, a ser obtido.

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 presentes na janela de tempo {startDate} e {endDate} definida, para o {dataType} solicitado;
• Minimum: retorna o valor mínimo encontrado entre todas as amostras presentes na janela de tempo {startDate} e {endDate} definida, para o {dataType} solicitado;
• Average: retorna o valor médio de todas as amostras presentes na janela de tempo {startDate} e {endDate} definida, para o {dataType} solicitado;

---

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 ):

Para um {dataType} pertencente à categoria {energy,kpis}, o {valueType} pode assumir dois valores diferentes:

• Cumulative:retorna o último valor cumulativo disponível na janela de tempo definida {startDate} e {endDate}, para o solicitado {dataType};
• Delta: retorna a diferença entre o último e o primeiro valor cumulativo disponível na 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 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 ):