API dostępowe - GPSDR - API v3

Opis i wymagania - API v3

Moduł synchronizacji danych GPSDR posiada wbudowane API pozwalające na bezpośredni dostęp do danych zarejestrowanych przez urządzenia GPS. Oprogramowanie jak i usługa są bezpłatne dla użytkownika.

Aplikacja wymaga systemu operacyjnego Windows XP lub nowszego, innego kompatybilnego z Windows XP, emulowanego bądź wirtualnego, pozwalającego na pracę aplikacji Win32 (może nie działać poprawnie na Windows 10s). 

Dane GPS w systemie pogrupowane są wg numerów rejestratorów, poszczególne dane z każdego z nich mają unikalny numer rekordu (próbki). Każda pojedyncza próbka prócz numeru posiada takie parametry jak czas, współrzędne, prędkość, kierunek oraz szereg dodatkowych wartości zależnych od rejestratora i firmware w nim.

W celu aktywacji API v3 należy:

1. Posiadać aplikację GPSDR w wersji 2.4.47 (lub nowszej) lub posiadać poprawnie skonfigurowaną usługę dla Windows GPS DR.
2. Dokonać edycji pliku konfiguracyjnego navicar.ini znajdującego się w folderze:

• • {app}\network\

  • c:\ProgramData\Navisoft\NaviCar2\

• • c:\Document and Settings\All Users\Application Data\Navisoft\NaviCar2\

 Jeśli plik występuje w więcej niż 1 z powyższych lokalizacji - edycja dotyczy pliku z lokalizacji wymienionej w pierwszej kolejności.

W sekcji GPSDR pliku navicar.ini należy dodać następujące wartości:

• LocalHttp - numer portu TCP na którym usługa zostanie aktywowana. Wartość 0 lub brak klucza - usługa nieaktywna

• API - numer wersji API. Dopuszczalne wartości to 2 i 3. Aktywacja API v3 wymaga wartości API=3 bądź usunięcia klucza. API w wersji 1 zostało usunięte i nie jest wspierane

Komunikacja

Dostęp do API odbywa się za pomocą standardowego protokołu HTTP aktywowanego na wybranym porcie TCP. Odpowiedź zawsze jest tekstowa, w formacie JSON, zgodnym ze specyfikacją RFC 8259. Kodowanie znaków: UTF-8

Składnia podstawowego zapytania

Podstawowe zapytanie do usługi:

http://server:port/api/command/authkey/configname/?params

• adres serwera i numer portu ustalane są podczas konfiguracji usług

• command to polecenie wykonywane przez API

• authkey - klucz autoryzacyjny / dostępowy do API

• configname - nazwa konfiguracji dostępnej z API

• params - dodatkowe opcjonalne parametry, można podawać jako parametry GET lub opcjonalnie jako POST

Obsługiwane polecenia

Testowanie konfiguracji

Polecenie służy do testowania poprawności konfiguracji (aktywacji usługi). Jako jedyne nie wymaga podania poprawnych parametrów do autoryzacji konta. Zwraca wersję API oraz podane parametry wejściowe.

 /api/test/key/configname/?param1=abc&param2=xyz

Pobranie listy urządzeń

 Polecenie zwraca listę urządzeń dla danej konfiguracji:

/api/devices/apiKey/configName/

•  ilość parametrów dostępnych dla pojazdów może być większa, podstawowe gpsID oraz name są dostępne zawsze

Pobieranie danych GPS

Lista dostępnych parametrów zapytania

Parametr “devices”

Struktura przedstawia się następująco:

ID1[:pack1],ID2[:pack2],ID3[:pack3],....,ID[n,packn]

gdzie:

• ID oznacza numer ID urządzenia

• pack oznacza numer pierwszego pakietu danych który jest żądany, parametr jest opcjonalny

• brak numeru pakietu oznacza prośbę o ostatni (najświeższy) pakiet danych dostępny na serwerze

• ujemna wartość oznacza ilość ostatnich (najświeższych) pakietów danych

• brak listy oznacza: ostatni pakiet z każdego z urządzeń

Przykłady:

• devices=1000:12345

wszystkie dane od rekordu 12345 dla urządzenia 1000

• devices=1000

ostatni rekord z urządzenia 1000

• devices=1000:-3

3 ostatnie rekordy z urządzenia 1000

• devices=1000:12345,1001:22222,1002:0,1003,1004:-3

z urządzenia 1000 wszystkie rekordy od 12345

z urządzenia 1001 wszystkie rekordy  od 22222

z urządzenia 1002 wszystkie rekordy  od początku danych

z urządzenia 1003 najświeższy rekord

z urządzenia 1004 - 3 ostatnie

• devices=  lub brak parametru devices

po jednej ostatniej próbce dla każdego z urządzeń

Dostęp do danych 

Polecenie dostępu do danych przedstawia się w następujący sposób:

/api/history/key/configname/?parametry 

• pusta tablica records oznacza brak danych spełniających warunek zapytania

• jeśli numer ostatniego rekordu (pack) w tablicy records pokrywa się z wartością last oznacza to, że odczytano wszystkie dane

• jeśli numer pierwszego rekordu (pack) w tablicy records jest większy niż żądany zapytaniem (from) oznacza to, że serwer nie posiada tych danych

• jeśli numer from jest ujemny (zgodnie z zapytaniem) - oznacza to, że pytamy o dane od końca

• Urządzenia cyfrowe oraz wielostanowe 1 z N zwracają wartość integer

• Urządzenia licznikowe oraz analogowe zwracają wartość float

• W przypadku braku możliwości obliczenia należy oczekiwać wartości null

•  urządzenia licznikowe oraz analogowe zwracają wartość float

• urządzenia cyfrowe oraz wielostanowe 1 z N zwracają obiekt zawierający stan (state) jako integer oraz nazwę stanu jako name

• w przypadku braku możliwości obliczenia należy oczekiwać wartości null

Kody odpowiedzi HTTP / błędy 

Definiowanie konfiguracji

Pliki konfiguracji określają listę dostępnych urządzeń i parametrów, ich nazw oraz formatu. Pliki tworzy się za pomocą dostępnej aplikacji navicarSetup. 

Folder dla konfiguracji API znajduje się w podfolderze wg poniższej ściezki:

  ….plik.exe\APIv3\configs\

• poszczególne konfiguracje jako pliki o rozszerzeniu .file należy umieścić w podfolderach

• podfolder odpowiada parametrowi authkey

• nazwa pliku po usunięciu rozszerzenia - to configname

Przykład:

….\APIv3\configs\XyZ5ai5ad\client1.file

authkey=XyZ5ai5ad

configname=client1

Prztkładowy link dla listy urządzeń: http://127.0.0.1:1234/api/devices/XyZ5ai5ad/client1/

Udostępnij stronę innym