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.

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

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

https://host/wialon/ajax.html?svc=НАИМЕНОВАНИЕ_ЗАПРОСА&params={ПАРАМЕТРЫ}&sid=ИДЕНТИФИКАТОР_СЕССИИ

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

Для авторизации в 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 можно с помощью просмотра сетевых запросов в момент изменения часового пояса пользователя в веб-интерфейсе.

Системный ID

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

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

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

3. В столбце avl_id в системе управления.

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

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

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

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

• avl_hw — тип устройства;
• avl_resource — ресурс;
• avl_retranslator — ретранслятор;
• avl_unit — объект;
• avl_unit_group — группа объектов;
• user — пользователь;
• avl_route — маршрут.

Одним из возможных критериев поиска могут являться подэлементы. В таком случае для параметра 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 — административные поля.

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

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

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

Необходимо получить список всех доступных пользователю объектов, в имени которых есть слово 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=ИДЕНТИФИКАТОР_СЕССИИ

{
	"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=ИДЕНТИФИКАТОР_СЕССИИ

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

Необходимо вывести список объектов с типом оборудования 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=ИДЕНТИФИКАТОР_СЕССИИ

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

Необходимо вывести список объектов, в которых создан датчик с именем 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=ИДЕНТИФИКАТОР_СЕССИИ

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

Необходимо получить список групп объектов, которые были созданы пользователем 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=ИДЕНТИФИКАТОР_СЕССИИ

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

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

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

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

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

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

Екатерина Гриб,Инженер Customer Service 2023-07-18