ІНТЕГРАЦІЯ 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

URL для генерування токена без терміну дії:

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

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

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

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

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

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

Токен - це 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.