Autoryzacja zaleceń do systemu sterowania odbywa się za pomocą kluczy dostępu do API, wygenerowanych w ustawieniach systemu sterowania. Aby otrzymać taki klucz, w systemie sterowania należy otworzyć menu Ustawienia i wybrać zakładkę API.
Przed utworzeniem jakichkolwiek zadań monitoringowych należy utworzyć zadanie o wyświetlenie wykazu pojazdów oraz ich cechy indentyfikacyjne. Aby to zrobić, należy utworzyć zadanie (GET)
http://dispatch.navitel.ru/api/1.0/vehicles.xml?apikey=[val]&namefilter=
gdzie „apikey=[val]” jest parametrem typu „imię/znaczenie”, w którym „apikey” jest imieniem, „[val]” — znaczeniem. Na miejsce znaczenia „[val]” należy wstawić klucz dostępu do API, uzyskany w ustawieniach systemu sterowania. Komenda z wprowadzonym znaczeniem będzie wyglądała następująco:
http://dispatch.navitel.ru/api/1.0/vehicles.xml?apikey=00000000000000000000000&namefilter=
Oprócz tego, na końcu zadania powinien być parametr filtra imienia
namefilter=[value]
gdzie „[value]” jest znaczeniem filtra. W znaczeniu można wskazać nazwę imienia obiektu, o którym chcesz otrzymać informacje, jak również można zostawić pustym, jeśli chcesz otrzymać informacje o wszystkich pojazdach ( jak widać na przykładzie wyżej).
<reply> <result type="array"> <v i="0"> <group_name>security_group</group_name> <tracker_id>GALILEOSKY:00000000000000000000000000000000</tracker_id> <tracker_type>GALILEOSKY</tracker_type> <vehicle_id>xxxxx-xxxx-xxxx-xxxxxxxxxxxx</vehicle_id> <vehicle_name>Subaru</vehicle_name> </v> <v i="1"> <group_name>security_group</group_name> <tracker_id>GRANIT:00000000000000000000000000000</tracker_id> <tracker_type>GRANIT04</tracker_type> <vehicle_id>xxxxx-xxxx-xxxx-xxxxxxxxxxxx</vehicle_id> <vehicle_name>cardabalet</vehicle_name> </v> </result> </reply>
Odpowiedź zawiera następujące informacje o pojazdach: Grupa/firma (w systemie sterowania), IMEI/Id trackera, typ trackera, id pojazdu, nazwę pojazdu. Te informacje będą potrzebne do kolejnych zadań, w których należy podawać dane identyfikacyjne pojazdów.
W zadaniu można również podać odpowiedni format odpowiedzi: xml lub json. Aby dokonać tego wyboru, należy w zadaniu po „vehicles” podać format „.xml” lub ".json" (można tego dokonać w każdym rodzaju zadań do systemu sterowania.
Wynik tego zadania będzie dostarczony w formacie XML kodu.
http://dispatch.navitel.ru/api/1.0/vehicles.xml
w przykładzie niżej wynikiem zadania jest kod JSON
http://dispatch.navitel.ru/api/1.0/vehicles.json
Zadanie systemu sterowania można przedstawić jako zbiór elementów: główny adres URL oraz parametry zadania. Do głównego adresu URL należy część zadania do wskazania typu rozszerzenia xml lub json włącznie.
Przykład głównego adresu URL, którego się używa przy dowolnych zapytaniach do systemu sterowania (wyjątkiem jest zapytanie do systemu sterowania z innym adresem URL o uzyskaniu wykazu pojazdów).
http://dispatch.navitel.ru/api/1.0/vehicleinfo.xml?
Parametry zadania są rzędem, składającym się z par typu „imię/znaczenie”, w którym każda para rozdziela się znakiem ampersand („&”). Wykaz parametrów zaczyna się od znaku zapytania po typie rozszerzenia. Każdy parametr wygląda następująco:
field=[value]
gdzie „field” — imię parametru, a „[value]” — wartość. API zapytania do systemy sterowania rozpoznają następne imiona parametrów: „id”, „name”, imei„, „time”, „what”, „apikey”.
Należy pamiętać, że takie zadania uwzględniają wielkość liter.
Zadanie zazwyczaj składa się z następnych parametrów:
Identyfikatory samochodu. Można wybrać pojazd wybierając jeden z trzech identyfikatorów, dostępnych dla każdego samochodu: „id”, "name","imei„. Przykład wprowadzenia parametru:
id=[vehicle_static_id_0]
gdzie „[vehicle_static_id_0]” — ID samochodu, który będzie widoczny w zapytaniu o wykazie pojazdów.
Identyfikatory są parametrami prostymi, takimi jak apikey bądź inne parametry w zapytaniu do systemu sterowania. Zatem w jednym zapytaniu możliwe określać więcej niż identyfikator, co pozwala otrzymać informacje na kilka samochodów na raz.
Tak samo, jak inne parametry, parametry — identyfikatory powinny się oddzielać znakiem ampersand (&):
id=[vehicle_static_id_0]&id=[vehicle_static_id_0]
Również można używać różnych typów identyfikatorów przy wyborze samochodów, na przykład:
id=[vehicle_static_id_0]&name=[vehicle_name]&imei=[vehilce_imei]&id=[vehicle_static_id_N]
Gdyby okazało się, że znaczenia różnych identyfikatorów wskazują ten sam samochód, nie trzeba się martwić, ten samochód nie będzie wyświetlany dwukrotnie.
Klucz dostępu do API. Przykład:
apikey=[val]
gdzie „apikey” jest imieniem, „[val]” — znaczeniem. Na miejsce znaczeniu „[val]” należy wstawić klucz dostępu do API, uzyskany w ustawieniach systemu sterowania.
Wykaz żądanych parametrów:
field=[value]&field=[value]&field=[value]
gdzie „field” imię, a „[value]” jest znaczeniem parametru. Używaj podanych tabeli jak przykładów.
Do tej pory użytkownik powinien umieć wprowadzać parametry identyfikatora oraz API do zapytania. Jednakże parametry monitoringu wciąż zostają nie zbadane. Można ich podzielić na dwie grupy: czasowe i informacyjne. W tym rozdziale zostaną rozpatrzone parametry informacyjne. Odwoływanie się do takich parametrów wykonywane jest przez zapytanie używając imienia „what” i wybierając odpowiednią wartość. Wartości zapytań zostały przedstawione w poniższej tabeli.
Na przykład, jeśli chcesz uzyskać informacje na temat prędkości dla każdego obiektu dla aktualnego punktu w czasie, w polu imię parametru określić „what”, a w wartościach pola, zgodnie z tabelą poniżej, wskazać wartość „speed_kmh”:
what=speed_kmh
Całkowite zapytanie mogłoby wyglądać następująco:
http://dispatch.navitel.ru/api/1.0/vehicleinfo.xml?apikey=00000000000000000000000&name=NaviCar&what=speed_kmh
Ten przykład pokazuje informacje o prędkości obiektu, zwanego dalej „NаviCаr”, również w celach uzyskania dostępu do informacji w systemie sterowania użyty jest kod dostępu do API " 00000000000000000000000„. Podobnie możesz tworzyć również inne zapytania, używając nazwy i wartości parametrów wymienionych w poniższej tabeli.
Istnieją dwa rodzaje parametrów czasu: czas określony oraz przedział czasu. W przypadku gdy żaden parametr czasowy nie był określony, to kwerenda zwraca żądane dane w czasie rzeczywistym.
Aby ręcznie wprowadzić konkretny moment czasu, o którym należy uzyskać informacje, dodaj kolejny parametr:
time=[val]
Gdzie „time” jest nazwą parametru czasowego, a „[val]” jego wartością. W znaczeniu wartości należy podać datę oraz czas zgodnie ze normą ISO 8601 (więcej informacji na ten temat można znaleźć https://pl.wikipedia.org/wiki/ISO_8601).
Należy pamiętać, że kwerenda uwzględnia wielkość liter.
Datę i czas należy wprowadzić w parametrze „time=[val]” w następnym formacie: „RRRR-MM-DDTgg:mm:ss”.
Parametr będzie wyglądał następująco:
time=2015-07-12T12:00:00
Aby określić przedział czasowy, ustaw początek i koniec przedziału w parametrze czasu, jak pokazano poniżej, używając znak oddzielający „/”.
time=[val1]/ [val2]
gdzie „[val1]” jest początkiem przedziału, а „[val2]” jego końcem.
Na przykład:
time=2015-07-12T12:00:00/2015-07-15T15:52:01
Powyższy parametr pokazuje przedział czasowy z początkiem 12 lipca 2015 r. o 12:00:00 i końcem 15 lipca 2015 r. o 15:52:01.
Możesz również ustawić przedział jako „IsoTime / duration”, gdzie czas trwania przedziału czasowego ma następujący widok: PxxYxxMxxDTxxHxxMxxS ( po prefiksie P podany czas trwania przedziału czasowego). Jeśli czas jest ustawiony, to dla parametrów z grupy A będzie stosowany najdłuższy czas trwania z określonego przedziału czasowego.
W tabeli poniżej są wyznaczone parametry informacyjne „what”, które mogą być stosowane tylko jednocześnie z przedziałami czasowymi: