Telemetriai Adatok

Timeseries APIs

A Timeseries APIs főként akkor használják, ha egy bizonyos típusú adatokhoz részletes trendet szeretne szerezni, amely lehetővé teszi valós idejű elemzések és ábrázolások elvégzését egy testreszabott időablakban.

Az ilyen típusú APIs felépítése mindig a következő:

Az path út, amely lehetővé teszi, hogy a kívánt erőforrásokra mutasson, mind:

  • {power,frequency,wind,temperature,voltage,current,energy,kpis}: az erőforrás típusa, amelyre mutatni kell. Ez a paraméter nem a ténylegesen beszerezni kívánt adatokat határozza meg, hanem azt az általános kategóriát, amelyhez a kívánt adat tartozik (kérjük, vegye figyelembe, hogy egy API hívás egyszerre csak egy kategóriát fogad el, jelenleg nem lehetséges BULK hívások kezdeményezése);
  • {entityID}: lehet üzem vagy eszköz EID. Az első esetben a kapott érték figyelembe veszi azon eszközök összesítését, amelyeknél ez az érték létezik, üzemi szinten; a második esetben a kapott érték az egyetlen érdeklődésre számot tartó eszközre vonatkozott;
  • {dataType}: a ténylegesen beszerezendő adatokat jelöli. A rendelkezésre álló dataTypes a megjelölt erőforrásoktól függően változik, a részletes leírás közvetlenül a OpenAPIs Swagger;
  • {valuetype}: az összesítési feltétel típusát jelöli, amellyel a kért adatok megfelelnek megszerezni.

A queries adatok szűrését lehetővé tevő lekérdezésekhez mindig a következő paraméterekre van szükség:

  • {sampleSize}: meghatározza az adatgyűjtéshez szükséges mintavételi gyakoriságot. Minél hosszabb a mintavételi gyakoriság, annál rövidebb a válaszként kapott adattömb hossza (a sampleTime egyenlő a Min5 nek több mintája lesz a választömbben, mint a sampleTime egyenlő a Min15);
  • {startDate}: az alsó korlát, amely lehetővé teszi a kívánt időablak kezdetének meghatározását. A formátuma mindig YYYYMMGG (eg: 20220321);
  • {endDate}: a felső korlát, amely lehetővé teszi határozza meg az érdeklődésre számot tartó időablak végét. A formátuma mindig YYYYMMGG (eg: 20220322) és ideiglenesen a {startDate} után kell lennie;
  • {timezone}: lehetővé teszi, hogy az API hívást a kért időzóna szerinti helyes adat-helyreállításhoz irányítsa. The choice of timeZone affects the epochs returned within the response array.

Az idősoros hívás általában egy értéktömböt ad válaszként.
A tömb hossza közvetlenül függ a {sampleSize} értéktől és a által meghatározott időablaktól {startDate} és a {endDate} paramétereket. A referenciaidő-ablak meghatározása után a {sampleSize} érték gyakrabban vagy ritkábban felszeleteli az ablakot, következésképpen módosítva a válaszként a tömb hosszát: minél nagyobb a {sampleSize} értékét, akkor az időablak ritkábban lesz feldarabolva, így kevesebb elem lesz a választömbben.
Érdemes egy közvetlen példát nézni, hogy jobban megmagyarázzuk ezeket a fogalmakat.

Példa

Tegyük fel, hogy az inverter által termelt teljesítmény valós idejű trendjét szeretnénk megjeleníteni az aktuális napon (tegyük fel, hogy a tavaszi napéjegyenlőségben vagyunk). A legjobb megoldás egy Timeseries API használata, amelynek általános felépítése a következő:

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

A fenti általános szerkezeten belül tudjuk, hogy:

  1. A megcélzandó erőforrások kategóriája a {power} ezen belül pedig a {dataType} a GenerationPower;
  2. A meghívandó {valueType} egyike a Maximum, Minimum és Average (kérjük, olvassa el a részletes elemzést lentebb);
  3. Az időablak a tavaszi napéjegyenlőség napja, ezért a {startDate} értéke 20220321 és {endDate} értéke 20220322;

Ez a felhívás a következő formában történik:

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

A{sampleSize} paraméternek a következő értékei lehetnek:

  • Min5: az időablakot 5 percenként szeleteljük, minden egyes, az Aurora Vision on mentett mintát vesz (lásd az Oldal 1);
  • Min15: az időablakot 15 percenként szeleteljük, minden szelethez 3 Aurora Vision minta tartozik;
  • Min30: az időablakot 30 percenként szeleteljük, minden szelethez 6 Aurora Vision minta tartozik;
  • Hour: az időablakot 60 percenként szeleteljük, minden szelethez 12 Aurora Vision minta tartozik;
  • Day: az időablak minden nap fel van vágva, minden szelethez 288 Aurora Vision minta tartozik;
  • Month: az időablakot minden hónapban szeleteljük;
  • Year: az időablakot minden évben szeleteljük.

Mivel arra törekszünk, hogy a teljesítménytrendet a lehető leggyakrabban, valós időben ábrázoljuk, a {sampleSize} értékét Min5 értékre állítjuk (nem lenne értelme a kiválasztott időablak értékénél nagyobb értéket megadni) és a {timeZone} paramétert Europe/Rome értékre kell állítani:

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

A válasz egy bizonyos hosszúságú tömb lesz, amelyben minden elem mindig a következő struktúrából áll:

Amint látjuk, a válasz a következőkből áll:

  • Start: a korszakot jelöli, ami az időérték UTC ben; az timeZone szerint változik (a különböző időzónák különböző korszakaik lesznek ugyanahhoz a teljesítményértékhez) és követi a sampleSize által meghatározott időszeleteket;
  • Units: a mértékegységet jelöli;
  • Value: az értéket jelöli.

Extrapoláljunk egy nagyobb kivonatot a válaszból:

A start mező elemről elemre növekszik, és az 1647875700 értékről 1647876000; értékre lép át; ha különbséget teszünk a két korszak között, akkor pontosan 5 percet kapunk, vagy más szóval a sampleSize paraméternek beállított értéket.
A epoch 1647876000 korszaktól kezdve a start és az value mezők már nem léteznek; ez azért van, mert feltételezve, hogy a hívás 16:20 (Europe/Rome), az adott korszakkal hivatkozott minta a jövőben van, ezért még nem létezik. Mint ilyen, az Aurora Vision nem biztosítja a mezőt az elemen belül; a 16:20, után indított új hívásnál azonban megadja, mert fel van töltve.

Az idősoros API válaszelemeiben lévő bizonyos mezők jelenlétére/hiányára vonatkozó elv (a fenti példa utolsó soraiban kifejezve) alapvető fontosságú: nem csak a jövőbeli minták esetében, de mindenekelőtt az Aurora Visionra vonatkozó adatok teljes hiánya esetén is. Ez lehetővé teszi a telemetriai API-kból kapott válaszok koherenciájának biztosítását, mivel ha a fájlba beírt value jelen van, az azt jelenti, hogy az érték valóban létezik az Aurora Vision rendszeren, különben nem lenne jelen.

Ahogyan az összesített hívásoknál, az idősoros hívásoknál is nagyon fontos a {valuetype} paraméter, mivel az erőforrás-kategóriától függően változik, ezért a {dataType}, amelyet be kell szerezni és a {sampleSize} is befolyásolja.

A {dataType} kategóriába tartozó {power,frequency,wind,temperature,voltage,current,kpis}, esetén a {valueType} három különböző értéket vehet fel:

  • Maximum: a definiált mintában található összes minta közül a maximális értéket, a definiált ban lévő {sampleSize} , adja vissza {startDate} és a {endDate} időablak a kért {dataType} hoz;
  • Minimum: a definiált mintában található összes minta közül a minimális értéket, a definiált ban lévő {sampleSize} , adja vissza {startDate} és a {endDate} időablak a kért {dataType} hoz;
  • Average: a definiált mintában található összes minta közül a átlagértékét, a definiált ban lévő {sampleSize} , adja vissza {startDate} és a {endDate} időablak a kért {dataType} hoz;

MEGJEGYZÉS: kpis kategória esetében a fenti szempontok csak akkor érvényesek, ha Power-Based KPIs hívják. További részletekért tekintse meg a következőt OpenAPIs Swagger.

Vegyünk egy pillantást néhány felhasználási esetre, amikor egy üzemet ( entityID: 12345678 ) egyetlen regisztrált inverteres eszközzel tekintünk ( entityID : 87654321 ):

Use Case 1

Az inverter által termelt teljesítményt valós időben, 5 percenként szeretném megkapni a tavaszi napéjegyenlőség napján. Így meg tudom rajzolni a trendet, és konkrét elemzést végezhetek rajta.

Problémaelemzés

Tekintettel arra, hogy az üzem és a regisztrált eszközök aránya 1:1, közömbösen megadhatom a kettő közül az egyik entityID ját. Meg akarom termelni a teljesítményt, ezért rámutatok a power kategória erőforrásaira, és kérem a GenerationPower. A sampleSize paraméter egyenlő lesz a Min5 , értékkel, mert minden egyes mintát szeretnék megkapni. The valueType paramétert csak ebben az esetben lehet közömbösen beállítani Maximum, Minimum vagy Average értékre, mivel az idő Az ablak úgy van szeletelve, hogy minden szelethez egyetlen minta legyen, ezért egyetlen tényleges művelet sem tesz különbséget, ha egyetlen minta van referenciaként.

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

Use Case 2

Az inverter által termelt átlagos teljesítményt szeretném 15 percenként, a tavaszi napéjegyenlőség napján lekérni. Így meg tudom rajzolni a trendet, és konkrét elemzést végezhetek rajta.

Problémaelemzés

Tekintettel arra, hogy az üzem és a regisztrált eszközök aránya 1:1, közömbösen megadhatom a kettő közül az egyik entityID ját. Meg akarom termelni a teljesítményt, ezért rámutatok a power kategória erőforrásaira, és kérem a GenerationPower. Ebben az esetben a sampleSize paraméter egyenlő lesz a Min15 értékkel. A valueType paraméternek Average nak kell lennie, mivel az időablak úgy van szeletelve, hogy minden szelethez 3 minta legyen, és ezért az átlagot a 3 mintán hajtják végre. az egyes szeletekhez tartozó.

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

A {dataType} kategóriába tartozó {energy,kpis}, esetén a {valueType} két különböző értéket vehet fel:

  • Cumulative: minden időszeleten belül az utolsó összesített értéket adja vissza, amelyet a {sampleSize}, érték határoz meg a definiált {startDate} és {endDate} időablak a kért {dataType} esetén;
  • Delta: a minden időszeleten belül elérhető utolsó és első kumulatív érték közötti különbség, amelyet a {sampleSize}, érték határozza meg a definiált {startDate} és {endDate} paraméterekben időablak, a kért {dataType} esetén;

MEGJEGYZÉS: kpis kategória esetében a fenti szempontok csak akkor érvényesek, ha Energy-Based KPIs hívják. További részletekért tekintse meg a következőt OpenAPIs Swagger.

Vegyünk egy pillantást néhány felhasználási esetre, amikor egy üzemet ( entityID: 12345678 ) egyetlen regisztrált inverteres eszközzel tekintünk ( entityID : 87654321 ):

Use Case 1

Az inverter által termelt energiát valós időben szeretném megkapni, 5 percenként, a tavaszi napéjegyenlőség napján; az energiatrend ábrázolása érdekében.

Problémaelemzés

Tekintettel arra, hogy az üzem és a regisztrált eszközök aránya 1:1, közömbösen megadhatom a kettő közül az egyik entityID ját. Szeretném megtermelni az energiát, ezért rámutatok az energy kategória erőforrásaira, és kérem a GenerationEnergy. A sampleSize paraméter egyenlő lesz a Min5 , értékkel, mert minden egyes mintát szeretnék megkapni. A valueType paraméter egyenlő lesz a delta paraméterrel, mivel az időablak úgy van szeletelve, hogy minden szelethez egyetlen minta legyen, és így a minták közötti különbség biztosítja az 5 perc alatt ténylegesen megtermelt energiát.

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

Use Case 2

Az inverter által termelt energiát szeretném megkapni a tavaszi napéjegyenlőség hét minden napjára, hogy megrajzolhassam a heti energiatrendet.

Problémaelemzés

Tekintettel arra, hogy az üzem és a regisztrált eszközök aránya 1:1, közömbösen megadhatom a kettő közül az egyik entityID ját. Azt akarom, hogy a tavaszi napéjegyenlőség hetének minden egyes napján megtermeljen az energia, ezért rámutatok az energy kategória erőforrásaira, és kérem a GenerationEnergy. A sampleSize paraméter egyenlő lesz a Day, paraméterrel, mert a hét minden egyes napján fel szeretném vágni az időablakot. A valueType paraméter egyenlő lesz a delta paraméterrel, mivel az időablak úgy van szeletelve, hogy a hét minden napjának első és utolsó mintája között legyen különbség (időablak).

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