Dane Telemetryczne

Timeseries APIs

Timeseries APIs szeregów czasowych są używane głównie, gdy chcesz uzyskać, dla określonego typu danych, szczegółowy trend, który pozwala na przeprowadzanie analiz i reprezentacji w czasie rzeczywistym dla dostosowanego okna czasowego.

Tego typu interfejsy APIs mają zawsze następującą strukturę:

Ten path, która umożliwia wskazanie żądanych zasobów, zawsze wymaga następujących parametrów:

  • {power,frequency,wind,temperature,voltage,current,energy,kpis}: typ zasobu, na który należy wskazać. Ten parametr nie określa rzeczywistych danych, które chcesz uzyskać, ale ogólną kategorię, do której należą żądane dane (proszę zauważyć, że wywołanie API akceptuje tylko jedną kategorię na raz, obecnie nie jest możliwe wykonywanie wywołań BULK);
  • {entityID}: może to być EID zakładu lub urządzenia. W pierwszym przypadku uzyskana wartość uwzględnia agregację wszystkich urządzeń, dla których ta wartość istnieje, na poziomie zakładu; w drugim przypadku uzyskana wartość odnosiła się do pojedynczego urządzenia będącego przedmiotem zainteresowania;
  • {dataType}: reprezentuje rzeczywiste dane do uzyskania. Dostępne dataTypes różnią się w zależności od wskazanych zasobów, szczegółowy opis jest dostępny bezpośrednio w OpenAPIs Swagger;
  • {valuetype}: reprezentuje typ kryterium agregacji, z którym żądane dane są do uzyskania.

Ten queries, które umożliwiają filtrowanie żądanych danych, zawsze wymagają następujących parametrów:

  • {sampleSize}: określa częstotliwość próbkowania, z jaką należy uzyskać dane. Im dłuższa częstotliwość próbkowania, tym krótsza długość tablicy danych uzyskanej w odpowiedzi (i sampleTime równa się Min5 będzie miał więcej próbek w tablicy odpowiedzi niż sampleTime równa się Min15);
  • {startDate}: dolna granica, która pozwala zdefiniować początek interesującego okna czasowego. Jego format to zawsze YYYYMMGG (eg: 20220321);
  • {endDate}: górna granica, która umożliwia zdefiniować koniec interesującego okna czasowego. Jego format to zawsze YYYYMMGG (eg: 20220322) i musi być czasowo następujący po {startDate};
  • {timezone}: pozwala poprowadzić wywołanie API do prawidłowego odzyskiwania danych zgodnie z żądaną strefą czasową.

Wywołanie serii czasowej zwykle dostarcza array wartości jako odpowiedź.
Długość tablicy zależy bezpośrednio od wartości {sampleSize} i od okna czasowego zdefiniowanego przez {startDate} i {endDate}. Po zdefiniowaniu referencyjnego okna czasowego wartość {sampleSize} będzie dzielić to okno z większą lub mniejszą częstotliwością, w ten sposób konsekwentnie modyfikując długość tablicy w odpowiedzi: im większy jest {sampleSize}, okno czasowe zostanie podzielone, co spowoduje zmniejszenie liczby elementów w tablicy odpowiedzi.
Warto spojrzeć na bezpośredni przykład, aby lepiej wyjaśnić te koncepcje.

Example

Załóżmy, że chcemy przedstawić trend w czasie rzeczywistym mocy wytwarzanej przez falownik w bieżącym dniu (załóżmy, że mamy do czynienia z równonocą wiosenną). Najlepszym rozwiązaniem jest użycie Timeseries API, które będzie miało następującą ogólną strukturę:

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

W ramach ogólnej struktury powyżej wiemy, że:

  1. Kategoria zasobów, do których należy dążyć, to {power}, a w ramach tej kategorii {dataType} do wywołania to GenerationPower;
  2. {valueType} do wywołania to jeden z Maximum, Minimum i Average (proszę zapoznać się ze szczegółową analizą poniżej);
  3. Okno czasowe to dzień wiosennej równonocy, dlatego {startDate} będzie wynosić 20220321 i {endDate} będzie 20220322;

To skłania nas do przyjęcia następującej formy:

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

Parametr {sampleSize} może mieć następujące wartości:

  • Min5: okno czasowe jest dzielone co 5 minut, pobierając każdą pojedynczą próbkę zapisaną w Aurora Vision (patrz Strona 1);
  • Min15: okno czasowe jest dzielone co 15 minut, 3 próbki Aurora Vision są dołączone do każdego wycinka;
  • Min30: okno czasowe jest dzielone co 30 minut, 6 próbki Aurora Vision są dołączone do każdego wycinka;
  • Hour: okno czasowe jest dzielone co 60 minut, 12 próbki Aurora Vision są dołączone do każdego wycinka;
  • Day: okno czasowe jest wycinane każdego dnia, 288 próbek Aurora Vision jest dołączanych do każdego wycinka;
  • Month: okno czasowe jest dzielone co miesiąc;
  • Year: okno czasowe jest dzielone co rok.

Ponieważ jesteśmy zainteresowani reprezentowaniem trendu mocy w czasie rzeczywistym, tak często, jak to możliwe, wybieramy ustawienie {sampleSize} na Min5 (nie ma sensu wpisywać wartości większej niż w wybranym oknie czasowym) i ustawiać parametr {timeZone} na Europe/Rome:

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

Odpowiedź będzie tablicą o określonej długości, w której każdy element będzie zawsze składał się z następującej struktury:

Jak widzimy, odpowiedź składa się z:

  • Start: reprezentuje epokę, która jest wartością czasu w UTC; zmienia się zgodnie ze timeZone (różne strefy czasowe będą miały różne epoki dla tej samej wartości mocy) i postępują zgodnie z wycinkami czasowymi zdefiniowanymi przez sampleSize;
  • Units: reprezentuje jednostkę miary;
  • Value: reprezentuje wartość.

Przeprowadźmy ekstrapolację większego fragmentu odpowiedzi:

Pole start zwiększa się od elementu do elementu, przechodząc od wartości 1647875700 do wartości 1647876000; jeśli zrobimy różnicę między dwiema epokami, otrzymamy dokładnie 5 minut, czyli innymi słowy wartość, którą ustawiliśmy dla parametru sampleSize.
Z epoki 1647876000 pola start i value już nie istnieją; dzieje się tak, ponieważ zakładając, że połączenie zostało wykonane przed 16:20 (Europe/Rome), próbka, do której odnosi się ta epoka, jest w przyszłości, a zatem jeszcze nie istnieje. W związku z tym Aurora Vision nie zapewnia pola w żywiole; jednak w przypadku nowego połączenia wykonanego po 16:20 udostępni je, ponieważ zostało wypełnione.

Zasada obecności/nieobecności pewnych pól w elementach odpowiedzi interfejsu API serii czasowych (wyrażona w ostatnich wierszach powyższego przykładu) ma fundamentalne znaczenie: nie ma ona zastosowania tylko w w przypadku przyszłych próbek, ale także i przede wszystkim w przypadku całkowitego braku danych na temat Aurora Vision. Pozwala to zapewnić spójność odpowiedzi otrzymanych z interfejsów API telemetrii, ponieważ gdy podana jest podana value oznacza to, że ta wartość faktycznie istnieje w Aurora Vision, w przeciwnym razie nie byłaby obecna.

Podobnie jak w przypadku wywołań agregowanych, również w przypadku wywołań szeregów czasowych parametr {valuetype} ma ogromne znaczenie, ponieważ różni się w zależności od kategorii zasobów, a zatem {dataType}, który ma zostać uzyskany i na który ma również wpływ {sampleSize}.

Dla {dataType} należącego do kategorii {power,frequency,wind,temperature,voltage,current,kpis}, ten {valueType} może przyjmować trzy różne wartości:

  • Maximum: zwraca maksymalną wartość znalezioną wśród wszystkich próbek w każdym przedziale czasu, określoną przez wartość {sampleSize}, zdefiniowanym oknie czasowym {startDate} i {endDate} przedział czasowy dla żądanego {dataType};
  • Minimum: zwraca minimalną wartość znalezioną wśród wszystkich próbek wewnątrz każdego wycinka czasu, określoną przez wartość {sampleSize}, zdefiniowanym oknie czasowym {startDate} i {endDate} przedział czasowy dla żądanego {dataType};
  • Average: zwraca średnią wartość wszystkich próbek wewnątrz każdego wycinka czasu, określone przez wartość {sampleSize}, zdefiniowanym oknie czasowym {startDate} i {endDate} przedział czasowy dla żądanego {dataType};

UWAGA: dla kategorii kpis , powyższe uwagi są ważne tylko wtedy, gdy Nazywane są Power-Based KPIs. Więcej informacji znajdziesz w OpenAPIs Swagger.

Rzućmy okiem na kilka przypadków użycia, w których rozważamy instalację ( entityID: 12345678 ) z jednym zarejestrowanym falownikiem ( entityID : 87654321 ):

Przypadek Użycia 1

Chcę otrzymywać moc generowaną przez falownik w czasie rzeczywistym, co 5 minut, w dniu wiosennej równonocy. W ten sposób mogę wykreślić trend i przeprowadzić na nim określoną analizę.

Analiza Problemu

Biorąc pod uwagę, że stosunek między zakładem a zarejestrowanymi urządzeniami wynosi 1:1, mogę obojętnie wpisać entityID jednego z nich. Chcę wytwarzać moc, więc wskażę zasoby kategorii power i zażądam GenerationPower. Parametr sampleSize będzie równy Min5 , ponieważ chcę pobrać każdą pojedynczą próbkę. Parametr valueType można, tylko w tym przypadku, ustawić obojętnie jako Maximum, Minimum lub Average ponieważ czas okno jest podzielone w taki sposób, aby mieć pojedynczą próbkę dla każdego wycinka, a zatem żadna rzeczywista operacja nie ma znaczenia, jeśli istnieje pojedyncza próbka jako odniesienie.

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

Przypadek Użycia 2

Chcę otrzymywać średnią moc generowaną przez falownik co 15 minut w dniu wiosennej równonocy. W ten sposób mogę wykreślić trend i przeprowadzić na nim określoną analizę.

Analiza Problemu

Biorąc pod uwagę, że stosunek między zakładem a zarejestrowanymi urządzeniami wynosi 1:1, mogę obojętnie wpisać entityID jednego z nich. Chcę wytwarzać moc, więc wskażę zasoby kategorii power i zażądam GenerationPower. W takim przypadku parametr sampleSize będzie równy Min15. Parametr valueType musi mieć wartość Average ponieważ okno czasowe jest podzielone w taki sposób, aby na każdy wycinek przypadały 3 próbki i dlatego średnia jest wykonywana na 3 próbkach należące do każdego plasterka.

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

Dla {dataType} należącego do kategorii {energy,kpis}, ten {valueType} może przyjąć dwie różne wartości:

  • Cumulative: zwraca ostatnią skumulowaną wartość dostępną w każdym przedziale czasu, określoną przez wartość {sampleSize}, w zdefiniowanym oknie czasowym {startDate} i {endDate}, okno czasowe dla żądanego {dataType};
  • Delta: zwraca różnica między ostatnią a pierwszą skumulowaną wartością dostępną w każdym przedziale czasu, określona przez wartość {sampleSize}, w zdefiniowanym oknie czasowym {startDate} i {endDate}, okno czasowe dla żądanego {dataType};

UWAGA: dla kategorii kpis , powyższe uwagi są ważne tylko wtedy, gdy Nazywane są Energy-Based KPIs. Więcej informacji znajdziesz w OpenAPIs Swagger.

Rzućmy okiem na kilka przypadków użycia, w których rozważamy instalację ( entityID: 12345678 ) z jednym zarejestrowanym falownikiem ( entityID : 87654321 ):

Przypadek Użycia 1

Chcę otrzymywać energię generowaną przez falownik w czasie rzeczywistym, co 5 minut, w dniu wiosennej równonocy; w celu wykreślenia trendu energetycznego.

Analiza Problemu

Biorąc pod uwagę, że stosunek między zakładem a zarejestrowanymi urządzeniami wynosi 1:1, mogę obojętnie wpisać entityID jednego z nich. Chcę wyprodukowanej energii, więc wskażę zasoby kategorii energy i zażądam GenerationEnergy. Parametr sampleSize będzie równy Min5, ponieważ chcę pobrać każdą pojedynczą próbkę. Parametr valueType będzie równy delta ponieważ okno czasowe jest podzielone w taki sposób, aby mieć pojedynczą próbkę dla każdego wycinka, a zatem różnicę między próbkami dostarczy energię faktycznie wytworzoną w ciągu 5 minut.

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

Przypadek Użycia 2

Chcę uzyskać energię generowaną przez falownik dla każdego dnia tygodnia równonocy wiosennej, aby wykreślić tygodniowy trend energii.

Analiza Problemu

Biorąc pod uwagę, że stosunek między zakładem a zarejestrowanymi urządzeniami wynosi 1:1, mogę obojętnie wpisać entityID jednego z nich. Chcę, aby energia była generowana każdego dnia tygodnia równonocy wiosennej, więc wskażę zasoby kategorii energy i zażądam GenerationEnergy. Parametr sampleSize będzie równy Day, ponieważ chcę podzielić okno czasowe każdego dnia tygodnia. Parametr valueType będzie równy delta ponieważ okno czasowe jest podzielone w taki sposób, aby uzyskać różnicę między pierwszą a ostatnią próbką każdego dnia tygodnia (okno czasowe).

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