Udostępnianie danych po REST

System WinCN umożliwia dostęp do danych dla systemów zewnętrznych za pomocą REST. Z tej komunikacji korzysta także aplikacja WinCN Mobile.

Do dyspozycji jest zarówno pobieranie danych jak i wykonywanie zdalnego sterowania.

Za obsługę tej funkcji odpowiada moduł WinCNExchangeApi. Posiada on dwa interfejsy REST API. Adresy nasłuchu dla tych interfejsów definiuje się w oknie Słowniki na zakładce Definicje OMK.

Pierwszy pozwala na zdalną zmianę haseł użytkowników. Służy do integracji WinCN z systemami IAM.

Drugi interfejs służy do udostępniania danych dotyczących monitorowanych obiektów. Ten interfejs jest głównym interfejsem systemu i jego dotyczy poniższy opis.

Moduł obsługuje cztery wersje interfejsu (V1-V4), kolejna wersja zastępuje wcześniejszą. System zewnętrzny obsługujący najnowszą wersję nie musi znać wersji poprzednich. Wszystkie wersje opisane są w dokumencie ‘WinCN5 - Versioned API.pdf’.

Po nawiązaniu połączenia z API wymagane jest logowanie. W komendzie logowania należy wpisać login i hasło użytkownika WinCN. Są to te same dane, które są używane podczas logowania do aplikacji desktop i www. Użytkownik, który chce się logować przez REST musi mieć włączony typ logowania Mobile/Rest. Można to sprawdzić w oknie Użytkownicy.

Podczas udostępniania danych sprawdzane są dostępy użytkownika. Jeżeli użytkownik nie ma dostępu do obiektu, sterowania dane nie zostaną przesłane, a polecenie nie zostanie wykonane,

W najnowszej wersji API dostępne są następujące polecenia:

Polecenie Controllers pozwala na pobranie listy sterowników znajdujących się w konfiguracji WinCN. Przesłane zostaną sterowniki, które zalogowany użytkownik ma przypisane w grupach dostępów. Na podstawie pól Name, ObjectCode, Address możliwa jest identyfikacja sterownika.

Pole Id jest to unikalny identyfikator sterownika w bazie danych WinCN. Identyfikator jest niezmienny od chwili utworzenie sterownika w WinCN do jego usunięcia (nieodwracalnego). Wartość tego pola jest używana jako parametr w innych poleceniach (jako ControllerId).

Polecenie Control służy do wysłania do sterownika rozkazu sterującego. Zalogowany użytkownik musi mieć w uprawnieniach włączoną funkcję Sterowanie.

W parametrach wpisuje się identyfikator sterownika, funkcję sterującą, wartości parametrów.

Polecenie Control/History służy do pobrania historii przebiegu sterowania. Historia pobrana tym poleceniem dotyczy tylko sterowania wygenerowanego przez zalogowanego użytkownika.

Jako parametry polecenia w controllerId trzeba wprowadzić identyfikator sterownika, a w orderid trzeba wprowadzić identyfikator rozkazu sterującego.

W pole histId można wpisać wartość 0. Wtedy zostanie przesłany najnowszy rekord historii spełniający pozostałe parametry. W polu Id przesyłany jest identyfikator rekordu historii. Wstawiając tą wartość do histid można odebrać rekord historii spełniający parametry controllerId i orderId, ale o histid niższym niż podanych jako parametr (czyli wcześniejszy rekord). Powtarzając ten krok można pobrać całą historię sterowania (przesłana zostanie pusta odpowiedź, gdy nie ma już wcześniejszych rekordów).

W tablicy Messages przesyłane są komunikaty sterowania opisujące jego przebieg. Znaczenie komunikatów:

Przesyłane są dane wszystkich obiektów, do których użytkownik ma dostęp. Dane obejmują:

Przy wywołaniu polecenia trzeba podać id obiektu. W odpowiedzi przesłany zostanie stan obiektu w postaci listy elementów (płaska lista bez zagłębiana nadrzędny/podrzędny). Jeżeli użytkownik nie ma uprawnień do tego obiektu lub obiekt o takim Id nie istnieje to zwracane jest kod błędu.

Dla każdego elementu przesyłane są pola:

Dla każdej własności elementu przesyłane będą pola:

Polecenie MeasurementsHistory zwraca listę rekordów z tabeli Pomiary. W parametrach polecenie przekazać trzeba ID sterownika (controllerId), czas od (timeFrom), czas do (timeTo), ID własności sterownika (controllerPropertyId). Parametr z ID własności sterownika jest opcjonalny.

W odpowiedzi przesłane zostaną rekordy z pomiarami własności sterownika przypisanych do sterownika controllerId, spełniające warunek zakresu czasowego (timeFrom; timeTo). Jeżeli ID własności sterownika zostanie przesłane w parametrach to pomiary dotyczyć będą tylko tej jednej własności.

Każdy rekord będzie zawierał pola:

Polecenie ControllerHistory zwraca rekordy z tabeli Historia_sterownika. W parametrach polecenie przekazać trzeba ID sterownika (controllerId), czas sterownika od (timeFrom), czas sterownika do (timeTo), Typ_Historii (TypeHistory). Parametr Typ_Historii jest opcjonalny.

W odpowiedzi przesłane zostaną rekordy z rekordami historii sterownika przypisanych do sterownika controllerId, spełniające warunek zakresu czasowego (timeFrom; timeTo). Jeżeli TypeHistory zostanie przesłany to w odpowiedzi będą rekordy mające podany typ historii, jeżeli nie zostanie przesłany to w odpowiedzi będą rekordy z dowolną wartością typu historii.

Każdy rekord będzie zawierał pola:

Polecenie Locations będzie zwraca rekordy z tabeli Lokalizacje. W parametrach polecenie przekazać trzeba ID lokalizacji, nazwę obszaru lub nazwę miasta.

W odpowiedzi przesłane zostaną rekordy spełniające zadane parametry. W tabeli Lokalizacje obszar i miasto przechowywane są w postaci ID. W parametrach polecenia są przekazywane nazwy obszaru lub miasta.

Każdy przesłany rekord będzie zawierał pola:

Polecenie GetMobileActions zwraca listę akcji, do których przypisane są źródła akcji spełniające następujące warunki:

W odpowiedzi zostaje przesłana lista działań przypisanych do powyższych akcji, które są typu Sterowanie. Dla każdego z działań przesłane zostaną następujące dane:

Jako parametr polecenia trzeba przesłać Id działania akcji. Po odebraniu Id wszystkie dane akcji są na nowo odczytywane z bazy danych.

Usługa sprawdza warunki wykonania akcji:

Jeżeli, któryś z warunków nie jest spełniony to zwracany jest komunikat błędu.

Jeżeli warunki są spełnione to do serwera WinCN wysyłane jest polecenie sterowania z parametrami zawartymi w konfiguracji akcji. Zwrotnie przesyłane jest potwierdzenie przesłania sterowania.

Polecenie GetNotifications pozwala na pobranie powiadomień mobilnych. Po jego wywołaniu zwrotnie przesyłane są wszystkie oczekujące powiadomienia przypisane do zalogowanego użytkownika.

Każde powiadomienie zawiera: treść, wagę.

ExchangeApi przechowuje wygenerowane powiadomienia do czasu jaki jest w polu Czas ważności. Wiadomość jest usuwana jeżeli w tym czasie powiadomienie nie zostanie pobrane przez API.

Jeżeli wiadomość zostanie pobrana to jest ona usuwana z ExchangeApi. Nie można jej ponownie pobrać.

Wraz z komendą trzeba przesłać stare i nowe hasło użytkownika. Po zweryfikowaniu starego hasła sprawdzane jest nowe hasło. Jeżeli spełnia wymagania jakości hasła jest zapisywane do bazy danych a zwrotnie przesyłane jest potwierdzenie zmiany. Jeżeli nie spełnia wymagań zwrotnie przesyłane są przyczyny odrzucenia nowego hasła.