Fleetrun
Hecterra
NimBus
Другие приложения
Wialon для Android/iOS
Logistics
Wialon Local
Wialon Hosting
WiaTag
Configurator
LeaseControl
ru
Содержание
Введение в SDK: базовые запросы
  • technical_consulting

SDK (Software Development Kit) — это набор инструментов для разработки собственных приложений. Wialon SDK включает в себя несколько API. Самым базовым из них является Remote API, на изучение которого нацелены данные статьи. Remote API предполагает доступ к данным через HTTP-запросы и актуален для 1С, PHP, C++/C# и других языков программирования. JS API и остальные построены на базе Remote API.

В данной статье будут рассмотрены базовые знания, необходимые новичкам для использования Remote API.

Также вам могут быть полезны:

Просмотр запросов в браузере

В начале изучения SDK часто возникает необходимость понять, какой API-запрос отправляется на сервер при совершении того или иного действия в интерфейсе Wialon. Это можно легко отследить, используя встроенные инструменты браузера для мониторинга сетевых запросов.

В браузере Chrome для этого используется вкладка Сеть из Инструментов разработчика, которые открываются при нажатии на клавишу F12. В других браузерах данный инструмент может открываться иначе, о чем можно прочитать в документации браузера.

При просмотре сетевых запросов можно увидеть отправляемый запрос, его параметры и ответ от API-сервера в формате JSON.

 Пример

В качестве примера создадим круговую геозону. Откроем вкладку Сеть, а потом заполним поля Имя, Описание, Тип, Радиус и Координаты.

После нажатия на кнопку Сохранить геозона будет создана, а соответствующий запрос сразу отобразится на панели справа. Для получения информации о запросе кликните на него.

В данной панели присутствуют три удобные вкладки:

  • Заголовки — позволяет увидеть полный URL запроса, используемый метод отправки (POST или GET), статус выполнения запроса и другую полезную информацию.
    Среди прочего здесь можно найти 
    название API-запроса. В данном случае это resource/update_zone.



  • Полезная нагрузка — отображает параметры запроса, про каждый из которых можно прочитать в документации.
    Например, параметры, которые предлагалось указать при создании геозоны: n — имя, d — описание, t — тип (круг), w — радиус круга, x и y — координаты центра.



  • Ответ — отображает ответ от API-сервера в формате JSON (в случае ошибки — ее код).


Некоторые запросы выполняются пакетно. Тогда при просмотре сетевых запросов нужно найти запрос core/batch и изучить его параметры.

Не весь функционал интерфейса мониторинга основан на Wialon API (примером исключения является инструмент Расстояние).

Формат запроса

Запросы HTTP отправляются на сервер в следующем формате:

https://host/wialon/ajax.html?svc=НАИМЕНОВАНИЕ_ЗАПРОСА&params={ПАРАМЕТРЫ}&sid=ИДЕНТИФИКАТОР_СЕССИИ
ПараметрОписание
host

Для Wialon Hosting это обычно hst-api.wialon.com, а для Wialon Local — сайт системы мониторинга или CMS.

svc

Наименование запроса (например, resource/update_zone).

params

Параметры для выполнения запроса в формате JSON. Они перечислены в документации, при этом некоторые из них могут быть опциональными. В некоторых случаях отправляется пустое значение params={}.

sidУникальный идентификатор сессии, который используется практически во всех запросах. Сервер возвращает его при запросе на авторизацию.

Отправлять запросы для тестирования функционала API можно через адресную строку браузера. При этом необходимо, чтобы символы были закодированы для передачи в URL. Например, код символа % имеет вид %25, что можно проверить с помощью общедоступных онлайн-инструментов. Если специальные символы не будут закодированы, то в качестве ответа сервер вернет ошибку с кодом 4.

Получение токена и авторизация

Для авторизации в Wialon используется токен, то есть ключ, применяемый для зашифрованной идентификации пользователя.

Для создания токена можно использовать форму oAuth. После успешного логина токен отобразится в адресной строке браузера в качестве значения параметра access_token. При этом важно учитывать дополнительные параметры, которые регулируют такие свойства, как срок жизни (параметр duration), имя пользователя (параметр user), права доступа (параметр access_type) и другие.

Пример расширенной формы для получения токена:

https://hosting.wialon.com/login.html?client_id=ИМЯ_ПРИЛОЖЕНИЯ&access_type=256&activation_time=0&duration=0&lang=ru&flags=0&user=ИМЯ_ПОЛЬЗОВАТЕЛЯ

Пример ответа:

https://hosting.wialon.com/login.html?lang=ru&user=ИМЯ_ПОЛЬЗОВАТЕЛЯ&wialon_sdk_url=https%3A%2F%2Fhst%2Dapi%2Ewialon%2Ecom&access_token=ЗНАЧЕНИЕ_ТОКЕНА&svc_error=0

После получения токена его нужно использовать для авторизации. Пример логина под токеном:

https://hst-api.wialon.com/wialon/ajax.html?&svc=token/login&params={"token":"ЗНАЧЕНИЕ_ТОКЕНА"}

В ответе на логин под токеном содержится параметре eid, значение которого является уникальным идентификатором сессии. Далее он будет использоваться практически во всех API-запросах.

Настройка часового пояса

По умолчанию при работе c Remote API данные отображаются согласно часовому поясу GMT+0. Чтобы изменить его на необходимый, используется запрос render/set_locale. Достаточно выполнить данный запрос в рамках одной активной сессии.

Рекомендуется осуществлять настройку часового пояса сразу после авторизации, то есть до выполнения основных действий (запроса сообщений, построения трека и так далее).

При отправке запроса render/set_locale необходимо использовать параметр tzOffset. Стандартный метод вычисления его значения описан в документации.

 Пример

В качестве примера рассчитаем значение параметра tzOffset для клиента из Австралии (Сидней).

Посмотреть нужные значения временных настроек (летнее время и часовой пояс) можно в документации. В данном случае значение часового пояса равно 36000 (в формате DEC), а летнего времени — 0x0A270000 (в формате HEX).

Далее необходимо выполнить два действия:

  1. К часовому поясу применим операцию побитового И по маске f000ffff (HEX).
    Так как используемая операция выполняется для каждой пары битов, то сперва необходимо перевести значения в двоичную систему счисления:

    Часовой пояс

    00000000000000001000110010100000 (BIN)

    36000 (DEC)
    Маска

    11110000000000001111111111111111 (BIN)

    f000ffff (HEX)
    Результат операции

    00000000000000001000110010100000 (BIN)

    36000 (DEC)

    В данном случае операция не изменила значение часового пояса.

  2. К результату из предыдущего пункта применим операцию побитового ИЛИ по маске летнего времени.

    Предыдущей результат

    00000000000000001000110010100000 (BIN)

    36000 (DEC)
    Маска

    00001010001001110000000000000000 (BIN)

    0x0A270000 (HEX)
    Результат операции

    00001010001001111000110010100000 (BIN)

    170364064 (DEC)

Также узнать необходимое значение параметра tzOffset можно с помощью просмотра сетевых запросов в момент изменения часового пояса пользователя в веб-интерфейсе.

Системный ID

В API работа почти со всеми элементами ведется через внутренние идентификаторы, называемые системными ID, которые представлены уникальными цифровыми значениями.

Не нужно путать системный ID объекта с его Уникальным ID, который указывается в свойствах на вкладке Основное.

В веб-интерфейсах системные ID по умолчанию не отображаются, но их можно увидеть тремя методами:

  1. В ответе на запрос поиска элементов по критериям (core/search_items). Он будет рассмотрен подробнее в следующем разделе данной статьи.
  2. В параметрах запросов при просмотре сетевых запросов в браузере.
  3. В столбце avl_id в системе управления.

    Чтобы столбец avl_id отображался, необходимо авторизоваться в CMS, добавив в конец ссылки ?features=avl_id. Пример такой ссылки приведен на изображении ниже.

Поиск элементов по критериям

Данный запрос позволяет найти элементы по указанным в параметрах критериям.

Поиск осуществляется по следующим типам элементов, которые указываются в поле itemsType:

Одним из возможных критериев поиска могут являться подэлементы. В таком случае для параметра propType устанавливается значение propitemname, а параметр propName будет принимать следующие значения:

  • объекты:
    • unit_sensors — датчики;
    • unit_commands — команды;
    • service_intervals — интервалы техобслуживания;

  • ресурсы:
    • drivers — водители;
    • driver_groups — группы водителей;
    • jobs — задания;
    • notifications — уведомления;
    • trailers — прицепы;
    • trailer_groups — группы прицепов;
    • zones_library — геозоны;
    • reporttemplates — шаблоны отчетов;
    • orders — заявки;

  • маршруты:
    • rounds — рейсы;
    • route_schedules — расписания;

  • ретрансляторы:
    • retranslator_units — ретранслируемые объекты;

  • объекты, пользователи или ресурсы:
    • custom_fields — произвольные поля;
    • admin_fields — административные поля.

Системные ID элементов имеют уникальные числовые значения и присваиваются сервером.

Нумерация системных ID подэлементов ведется в порядке создания и начинается с 1.

Если ранее было создано несколько подэлементов (например, с системными ID 1, 2 и 3), а потом какой-то из них был удален (предположим, нетронутыми остались подэлементы с ID 1 и 3), то следующий созданный подэлемент займет наименьший свободный ID (в данном примере это ID 2).

При помощи запроса поиска нельзя отобразить данные по конкретному подэлементу. В ответе на запрос поиска содержится информация именно о самих элементах (тип устройства, ресурс, ретранслятор, объект, группа объектов, пользователь, маршрут). То есть подэлементы являются критерием для поиска.

Например, можно вести поиск по имени датчика Engine, но в ответе на запрос вернется не только информация о датчиках, а именно об объектах, в которых создан датчик с искомым именем.

Информация в ответе зависит от того, какие флаги указаны в запросе поиска в параметре flags. Флаги задаются в формате DEC.

Флаги можно суммировать между собой, чтобы получить несколько видов данных одновременно, а не выполнять несколько отдельных запросов.

Например, если необходимо вывести основные свойства объекта ("flag":1), созданные в нем команды ("flag":524288) и последнее местоположение ("flag":4194304), то достаточно выполнить поиск по объектам с флагом "flag":4718593, так как 1 + 524288 + 4194304 = 4718593.

Рассмотрим несколько примеров использования запроса о поиске элементов по критерию (другие примеры можно найти в документации).

Поиск элементов с определенным именем

Необходимо получить список всех доступных пользователю объектов, в имени которых есть слово Tractor, а также информацию о датчиках, созданных в объектах.

В таком случае можно использовать следующий запрос:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*Tractor*","sortType":"sys_name"},"force":1,"flags":4097,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значениеОписание
"itemsType":"avl_unit"

Поиск будет выполнен по объектам.

Если оставить значение пустым ("itemsType":""), то поиск будет осуществляться по всем типам элементов.

"propName":"sys_name"

Поиск будет выполнен по имени элемента.

"propValueMask":"*Tractor*"

В ответе будет отображен список объектов, имя которых содержит слово Tractor, а до и после него может быть любое количество символов.

Если задать для данного параметра значение *, то в ответе на запрос будут присутствовать элементы с любым значением именем, то есть все доступные пользователю элементы.

"sortType":"sys_name"Сортировка будет выполнена по имени элемента.
"force":1Результаты предыдущих поисков не будут учитываться.
"flags":4097

В ответе будет содержаться информация об основных свойствах, так как необходимо получить имена объектов, и о созданных датчиках.

1 + 4096 = 4097

"from":0;"to":0Ограничения по количеству найденных элементов не будут применяться.
 Ответ
{
	"searchSpec":{
		"itemsType":"avl_unit",
		"propName":"sys_name",
		"propValueMask":"*Tractor*",
		"sortType":"sys_name",
		"propType":"",
		"or_logic":"0"
	},
	"dataFlags":4097,
	"totalItemsCount":1,
	"indexFrom":0,
	"indexTo":0,
	"items":[
		{
			"nm":"Tractor 1",
			"cls":2,
			"id":22353120,
			"mu":0,
			"sens":{
				"1":{
					"id":1,
					"n":"Ignition",
					"t":"engine operation",
					"d":"",
					"m":"On\/Off",
					"p":"in1",
					"f":0,
					"c":"{\"act\":1,\"appear_in_popup\":true,\"ci\":{},\"cm\":1,\"mu\":0,\"pos\":2,\"show_time\":false,\"timeout\":0}",
					"vt":0,
					"vs":0,
					"tbl":[]
				},
				"2":{
					"id":2,
					"n":"Fuel level",
					"t":"fuel level",
					"d":"",
					"m":"l",
					"p":"adc1",
					"f":0,
					"c":"{\"act\":1,\"appear_in_popup\":true,\"calc_fuel\":0,\"ci\":{},\"cm\":1,\"fuel_params\":{\"fillingsJoinInterval\":300,\"filterQuality\":0,\"flags\":0,\"ignoreStayTimeout\":10,\"minFillingVolume\":20,\"minTheftTimeout\":0,\"minTheftVolume\":10,\"theftsJoinInterval\":300},\"mu\":0,\"pos\":1,\"show_time\":false,\"timeout\":0}",
					"vt":0,
					"vs":0,
					"tbl":[]
				}
			},
			"sens_max":-1,
			"uacl":-1
		}
	]
}

Поиск пользователей, созданных после определенной даты

Необходимо получить список пользователей, которые были созданы после 23 февраля 2021 05:41:46 (GMT+0). В ответе должны содержаться системные ID данных пользователей и их адреса электронной почты.

В таком случае можно использовать следующий запрос:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"user","propName":"rel_creation_time","propValueMask":">=1614058906","sortType":"sys_name"},"force":1,"flags":3,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значениеОписание
"itemsType":"user"

Поиск будет выполнен по пользователям.

"propName":"rel_creation_time"

Поиск будет выполнен по дате создания.

"propValueMask":">=1614058906"

В ответе будет отображен список элементов, время создания которых больше или равно 23 февраля 2021 05:41:46 (GMT+0).

В запросах используется Unix-времяДля перевода даты и времени в Unix-время можно использовать общедоступные онлайн-инструменты.

"sortType":"sys_name"Сортировка будет выполнена по имени элемента.
"force":1Результаты предыдущих поисков не будут учитываться.
"flags":3

В ответе вернется информация об основных свойствах, так как необходимо получить системные ID пользователей, и о произвольных свойствах, так как необходимо получить адреса электронной почты пользователей.

1 + 2 = 3

"from":0;"to":0Ограничения по количеству найденных элементов не будут применяться.

Поиск объектов определенного типа

Необходимо вывести список объектов с типом оборудования Wialon Retranslator, которые отправляли сообщения после 12 февраля 2023 12:00:00 (GMT+0). В ответе необходимо отобразить датчики объектов, время последнего сообщения и местоположения.

В таком случае можно использовать следующий запрос:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"rel_hw_type_name,rel_last_msg_date","propValueMask":"Wialon%20Retranslator,>1676203200","sortType":"rel_creation_time"},"force":1,"flags":1,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значениеОписание
"itemsType":"avl_unit"

Поиск будет выполнен по объектам.

"propName":"rel_hw_type_name,rel_last_msg_date"

Поиск будет выполнен по типу оборудования и времени последнего полученного сообщения.

"propValueMask":"Wialon%20Retranslator,>1676203200"

В ответе будет отображен список элементов с типом оборудования Wialon Retranslator, время отправки последнего сообщения от которых позже, чем 12 февраля 2023 12:00:00 (GMT+0).

"sortType":"rel_creation_time"Сортировка будет выполнена по дате создания элементов.
"force":1Результаты предыдущих поисков не будут учитываться.
"flags":1

В ответе вернется информация об основных свойствах объекта.

"from":0;"to":0Ограничения по количеству найденных элементов не будут применяться.

Поиск объектов по имени датчика

Необходимо вывести список объектов, в которых создан датчик с именем Engine.

В таком случае можно использовать следующий запрос:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propType":"propitemname","propName":"unit_sensors","propValueMask":"Engine","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значениеОписание
"itemsType":"avl_unit"

Поиск будет выполнен по объектам.

"propType":"propitemname"

Поиск будет выполнен по имени подэлемента.

"propName":"unit_sensors"

Поиск будет выполнен по имени датчика.

"propValueMask":"engine"

В ответе будет отображен список объектов, в свойствах которых создан датчик с названием Engine.

"sortType":"sys_name"Сортировка будет выполнена по имени элемента.
"force":1Результаты предыдущих поисков не будут учитываться.
"flags":1

В ответе вернется информация об основных свойствах объектов.

"from":0;"to":0Ограничения по количеству найденных элементов не будут применяться.

Поиск групп объектов по нескольким критериям

Необходимо получить список групп объектов, которые были созданы пользователем User, и в которые добавлено более 5 объектов.

В таком случае можно использовать следующий запрос:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit_group","propName":"rel_user_creator_name,rel_group_unit_count","propValueMask":"User,>5","sortType":"sys_name"},"force":1,"flags":133,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значениеОписание
"itemsType":"avl_unit_group"

Поиск будет выполнен по группам объектов.

"propName":"rel_user_creator_name,rel_group_unit_count"

Поиск будет выполнен по имени создателя и количеству элементов в группе.

"propValueMask":"User,>5"

В ответе будет отображен список групп объектов, создателем которых является пользователь User, и в которые добавлено более 5 объектов.

"sortType":"sys_name"Сортировка будет выполнена по имени элемента.
"force":1Результаты предыдущих поисков не будут учитываться.
"flags":133

В ответе вернется информация об основных свойствах, свойствах биллинга и административных записях.

1 + 4 + 128 = 133

"from":0;"to":0Ограничения по количеству найденных элементов не будут применяться.

Список частых ошибок

Ошибка отображается в случае невозможности выполнить запрос. Полный список возвращаемых ошибок можно найти в документации.

Наиболее частыми ошибками являются:

  • {error: 1} — недействительная сессия.
    Данная ошибка отображается, когда истек срок действия уникального идентификатора сессии. Чтобы исправить ошибку, достаточно выполнить логин под токеном еще раз и использовать новый идентификатор сессии (sid) для выполнения запросов.

    Если в течение 5 минут в рамках сессии не выполняется ни одного запроса, то она становится неактивной. Чтобы поддерживать сессию, вы можете каждые 5 минут отправлять запрос avl_evts.

  • {error: 4} — неверный ввод.
    Данная ошибка отображается, если в тексте запроса присутствует ошибка: указаны не все требуемые параметры, текстовые параметры не заключены в кавычки, нет открывающей или закрывающей скобки и т. д. Чтобы исправить ошибку, необходимо исправить текст выполняемого запроса согласно его описанию в документации.

  • {error: 7} — доступ запрещен.
    Данная ошибка отображается, если у пользователя недостаточно прав на выполнение запроса. Чтобы исправить ошибку, необходимо проверить, достаточно ли прав у токена, который используется для получения уникального идентификатора сессии, а также достаточно ли у пользователя, для которого был сгенерирован токен, прав в отношении используемых элементов.


Екатерина Гриб,Инженер Customer Service

Если вы заметили ошибку в тексте, пожалуйста, выделите её и нажмите Ctrl+Enter.
Спасибо за ваш отзыв!
Сообщить об ошибке
Текст с ошибкой Комментарий
Максимум 500 символов