Перейти до змісту

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

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

Мал. 1. Генерація токена (крок 1)

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

Мал. 2. Генерація токена (крок 2)

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

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

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

Мал. 3. Генерація токена (крок 3)

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

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

Мал. 4. Успішна авторизація

Варто звернути увагу на властивість 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} як показано на скріншоті:

Мал. 5. Завершення сесії

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