ІНТЕГРАЦІЯ WIALON LOCAL З СТОРОННІМ ПЗ

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

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

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

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

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

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

ПАРАМЕТР	ОПИС	РЕКОМЕНДОВАНІ ЗНАЧЕННЯ
client_id	название приложения/сайта/клиента,для которого сгенерировать токен	название сайта (title)
access_type	уровень прав токена	0x100 (отслеживание)
activation_time	время активации токена (время UTC в секундах: 0 - сейчас)	0
duration	время жизни токена (в секундах) MAX_DURATION = 8640000 - 100 дней, 0 - срок жизни не ограничен	0 (условно бессрочный токен, удаляется через 100 дней без авторизации)
lang	язык (en, uk, …)
flags	флаги токена	0x1 - возвращать в ответе имя пользователя
user	имя пользователя (подставится в поле логина)
redirect_uri	URL, на который переадресовать страницу и передать результаты авторизации	сама форма login.html
response_type	возвращать в ответе токен (token) или AuthHash (hash)	token
css_url	URL к CSS-файлу с произвольными стилями для формы

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

Приклад: Використовуючи рекомендовані параметри для сервера https://local.overseer.ua сформуємо URL та отримаємо токен авторизації. Рядок URL, необхідний для генерації токена, виглядає наступним чином:

https://local.overseer.ua/login.html?access_type=….response_type=token&lang=uk

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

Далі необхідно ввести дані користувача та натиснути Увійти.

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

Далі необхідно ввести дані користувача та натиснути Увійти.

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

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

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

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

Для авторизації необхідно сформувати та надіслати методом POST запит з наступним змістом:

https://local.overseer.ua/wialon/ajax.html?svc=token/login&
params={
    "token":"2fe8024e0ab91aa6c8ed82717b71bddcECDC362358DF7D90986F5173D405CD0D42DE7B38"
}

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

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

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

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

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

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

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

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

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

http://local.overseer.ua/wialon/ajax.html?svc=core/logout&params={}&sid=8c3101591632f6e7ef686d33fcc0d55

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

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