Telemetriedaten

Aggregated APIs

Aggregated APIs werden hauptsächlich verwendet, wenn sie für einen bestimmten datentyp einen einzelnen wert als antwort erhalten möchten, der es ermöglicht, einen bestimmten trend und/oder ein bestimmtes ergebnis für ein benutzerdefiniertes zeitfenster zusammenzufassen.

Diese Art von APIs sind immer wie folgt strukturiert:

Der path, mit dem sie auf die gewünschten ressourcen zeigen können, erfordert immer die folgenden parameter:

• {power,frequency,wind,temperature,voltage,current,energy,kpis}: der ressourcentyp, auf den verwiesen werden soll. Dieser parameter gibt nicht die eigentlichen daten an, die sie erhalten möchten, sondern die allgemeine kategorie, zu der die gewünschten daten gehören (bitte beachten sie, dass ein API-Aufruf jeweils nur eine kategorie akzeptiert, es ist derzeit nicht möglich, BULK-Aufrufe durchzuführen);
• {entityID}: es kann sich um eine anlagen-oder Geräte-EID handeln. Im ersten fall berücksichtigt der erhaltene wert die aggregation aller geräte, für die dieser wert existiert, auf anlagenebene; im zweiten fall bezieht sich der erhaltene wert auf das einzelne interessierende gerät;
• {dataType}: stellt die tatsächlich zu erhaltenden daten dar. Die verfügbaren dataTypes variieren je nach ressource, auf die verwiesen wird, eine detaillierte beschreibung ist direkt in der OpenAPIs Swagger;
• {valuetype}: stellt die art des aggregationskriteriums dar, mit dem die angeforderten daten vorliegen zu erhalten.

Die queries, mit denen sie die angeforderten daten filtern können, erfordern immer die folgenden parameter:

• {startDate}: die untere grenze, die es ermöglicht, den beginn des interessierenden zeitfensters zu definieren. Sein Format ist immer YYYYMMGG (eg: 20220321);
• {endDate}: die obergrenze, die es erlaubt definieren sie das ende des interessierenden zeitfensters. Sein format ist immer YYYYMMGG (eg: 20220322) und muss zeitlich nach dem {startDate} liegen;
• {timezone}: ermöglicht es, den API-Aufruf zu einer korrekten datenwiederherstellung gemäß der angeforderten zeitzone zu leiten.

Ein aggregataufruf liefert als antwort immer einen einzelwert, der entsprechend dem angegebenen zeitfenster und der angegebenen zeitzone manipuliert wird. In diesem zusammenhang ist der parameter {valuetype} von großer bedeutung, da er je nach kategorie der zu erhaltenden ressourcen, also {dataType} variiert.

Für einen {dataType} der zur kategorie {power,frequency,wind,temperature,voltage,current,kpis} gehört, wird der{valueType} kann drei verschiedene werte annehmen:

• Maximum: gibt den maximalen wert zurück, der unter allen in der def vorhandenen proben gefunden wurde {startDate} und {endDate} zeitfenster, für den angeforderten {dataType};
• Minimum: returns the minimum value found among all the samples present in the defined {startDate} und {endDate} zeitfenster, für den angeforderten {dataType};
• Average: gibt den durchschnittswert aller stichproben zurück, die im definierten {startDate} und {endDate} tzeitfenster, für den angeforderten {dataType};

---

HINWEIS: für die kategorie kpis, gelten die obigen Überlegungen nur, wenn Power-Based KPIs genannt werden. Weitere einzelheiten finden sie unter OpenAPIs Swagger.

---

Werfen wir einen blick auf einige anwendungsfälle, in denen wir eine anlage ( entityID: 12345678 ) mit einem einzelnen registrierten wechselrichtergerät ( entityID : 87654321 ):

Für einen {dataType} der zur kategorie {energy,kpis}, gehört, kann der {valueType} zwei unterschiedliche werte annehmen:

• Cumulative: gibt den letzten kumulativen wert zurück, der im definierten zeitfenster {startDate} und {endDate}, für die verfügbar ist angeforderter {dataType};
• Delta: gibt die differenz zwischen dem letzten und dem ersten kumulativen wert zurück, der im definierten {startDate} und {endDate} zeitfenster, für den angeforderten {dataType};

---

HINWEIS: für die kategorie kpis, gelten die obigen Überlegungen nur, wenn Energy-Based KPIs genannt werden. Weitere einzelheiten finden sie unter OpenAPIs Swagger.

---

Werfen wir einen blick auf einige anwendungsfälle, in denen wir eine anlage ( entityID: 12345678 ) mit einem einzelnen registrierten wechselrichtergerät ( entityID : 87654321 ):