FAQ щодо інтеграції з системою GPS моніторингу Wialon

Досить часто при інтеграції з Wialon у розробників, які починають працювати з SDK Wialon виникає безліч питань з приводу правильного використання Wialon SDK.

Незважаючи на те, що Remote API Wialon всіх редакцій (Wialon Local, Wialon Pro, Wialon Hosting) чудово документований (документація доступна в російській та англійській локалізації), все ж таки деякі аспекти взаємодії з API Wialon не так очевидні.

Мета цієї статті надати відповіді на найважливіше і найчастіше питання при використанні Remote API Wialon.

Головна проблема з якою часто стикаються розробники це авторизація Wialon.

Справа в тому, що авторизація Wialon відбувається згідно з принципами oAuth. Для авторизації необхідно спочатку отримати спеціальний токен авторизації, який потім можна використовувати для авторизації з використанням ID сесії.

Розглянемо приклад авторизації докладніше. Для прикладу буде використано демо доступ до системи моніторингу Wialon Local.

Для отримання токена необхідно спочатку сформувати URL, за яким відбувається авторизація. Докладно про те, як правильно сформувати даний URL описано в документації. У документації описано перелік query-параметрів, необхідних для формування необхідного запиту.

Для різних серверів Wialon Local нашої компанії ці параметри будуть ідентичні.

Розглянемо деякі найважливіші параметри:

Важлива примітка. Токен може мати різні права доступу. У таблиці показано лише базове значення, яке дозволяє вести моніторинг, але не дозволяє виконувати більшість операцій, що змінюють стан об'єктів. Для використання додаткових операцій необхідно згенерувати токен авторизації з додатковими правами (у випадку, якщо користувач, за допомогою якого відбувається авторизація, має необхідні права доступу). Докладніше про різні значення рівня прав токена описано на цій сторінці.

приклад. Використовуючи рекомендовані параметри для сервера http://local2.old.overseer.ua, сформуємо URL та отримаємо токен авторизації.

Рядок URL, необхідний для генерації токена виглядає наступним чином: http://local2.old.overseer.ua/login.html?access_type=….response_type=token

Далі необхідно скопіювати цей рядок у рядок пошуку браузера та перейти за посиланням.

Далі необхідно ввести дані користувача та натиснути "Авторизувати".

Згідно зі скріншотом, при використанні даних параметрів буде отримано токен, який дозволяє вести стеження онлайн.

Далі необхідно ввести дані користувача та натиснути "Авторизувати".

У разі успішної авторизації система повідомить про успішну авторизацію як на скріншоті нижче:

Токен це 72-значне унікальне значення, яке необхідно скопіювати з рядка браузера (значення виділене чорним прямокутником) та використовувати надалі для інтеграції у своїх додатках. За бажання токен можна згенерувати заново. Надалі токен буде використаний для авторизації.

Для авторизації буде використаний REST API клієнт, щоб продемонструвати ще один нюанс авторизації у Wialon Local за допомогою Remote API.

Відповідно до документації для звернення до API Wialon Local необхідно використовувати лише запити POST.

Для авторизації необхідно сформувати та надіслати методом POST запит з наступним вмістом (https://sdk.wialon.com/wiki/ru/local/remoteapi1904/codesamples/login):

Параметр operateAs є обов'язковим, при авторизації його можна не використовувати.

Для Wialon Local OVERSEER запит буде представлений у такій формі:

http://local2.old.overseer.ua/wialon/ajax.html?svc=token/login&params={“token”:“<your token>”}

Якщо авторизація успішна буде отримано вміст приблизно як на скріншоті нижче:

Тут варто звернути увагу на властивість eid у відповіді. Це id сесії і він використовується для виконання запитів через Wialon API в рамках поточної сесії користувача.

У запитах ID сесії повинен передаватися як query-параметр sid для успішного виконання http-запитів від імені авторизованого користувача.

Наприклад, спробуємо завершити сесію. Відповідно до документації, для виконання даної дії необхідно виконати наступний запит http методом POST.

У нашому випадку це буде виглядати як:

http://local2.old.overseer.ua/wialon/ajax.html?svc=core/logout&params={}&sid=<your sid(eid)>

У разі успішного виконання ми отримаємо повідомлення {error:0} як показано на скріншоті:

Таким чином, успішно завершується сесія користувача за допомогою API.