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

Существуют ли ограничения на использование API?

Глобальные ограничения описаны в документации. Как правило, достижение этих ограничений говорит о том, что разработанное приложение не оптимизировано под работу с API. Например, оно выполняет множественные запросы авторизации вместо того, чтобы поддерживать одну сессию активной.

Ограничения существуют и у некоторых запросов, они упоминаются в описании запроса в документации. Например, одновременно в сессии может быть выполнен только один отчет. Если в сессии содержатся результаты выполнения предыдущего отчета, то их следует удалить с помощью запроса report/cleanup_result перед выполнением следующего отчета. Также запрос на выполнение отчетов не может выполняться одновременно с некоторыми другими запросами.

Можно ли с помощью API организовать передачу данных из Wialon в реальном времени?

Нет. API-запросы работают по принципу «запрос-ответ». То есть данные на принимающей стороне не будут обновляться без отправления запроса.

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

Как создать локатор через API?

Рассмотрим пример: необходимо создать локатор с неограниченным сроком действия, на котором будут отображаться объекты с системным ID 11111111 и 22222222, а также геозоны из ресурса с системным ID 12345678, но не будут отображаться треки объектов.

Для этого нужно использовать запрос token/update:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/update&params=
{"callMode":"create","app":"locator","at":0,"dur":0,"fl":256,"p":"{\"note\":\"Bus\",\"zones\":1,\"tracks\":0}","items":[11111111,22222222,12345678]}&sid=ИДЕНТИФИКАТОР_СЕССИИ

В ответе на запрос будет присутствовать параметр h, содержащий значение токена. Для получения искомой ссылки необходимо подставить значение токена в ссылку: https://hosting.wialon.com/locator/index.html?t=ЗНАЧЕНИЕ_ТОКЕНА

Как получить токен с максимальным доступом и без ограничения срока жизни?

Если создание токена осуществляется через расширенную форму, то необходимо использовать параметры access_type=-1 и duration=0. Например:

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

Если создание токена осуществляется через запрос token/update, то необходимо использовать параметры fl=-1 и dur=0. Например:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/update&params=
{"callMode":"create","app":"Wialon Hosting","at":0,"dur":0,"fl":-1,"p":"{}"}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Почему при использовании бессрочного токена может возвращаться ошибка с кодом 1?

Ошибка с кодом 1 говорит о том, что текущая сессия недействительна. Срок жизни токена не связан с сессией напрямую.

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

Как исправить ошибку с кодом 4?

Ошибка с кодом 4 соответствует неверному вводу, что может означать:

• неправильный тип данных (числовой, текстовый и т. д.);

• неправильные имена параметров;
• неправильные разделители (запятые, кавычки, пробелы, скобки и т. п.);
• отсутствие кодировки для передачи в URL.

Рассмотрим пример запроса со всеми обозначенными ошибками:

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result&params={"format":"2";"compres":0;"outputFileName":"Список поездок"}&sid=ИДЕНТИФИКАТОР_СЕССИИ

В данном примере были допущены следующие ошибки:

1. параметр format должен содержать число, но так как его значение указано в кавычках, то оно воспринимается, как текст;
2. вместо параметра с именем compress использовался параметр с именем compres;
3. для разделения параметров вместо запятой использовалась точка с запятой;
4. символ пробела не был закодирован для передачи в URL.

Правильный запрос будет выглядеть следующим образом:

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result&params={"format":2,"compress":0,"outputFileName":"Список%20поездок"}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Почему при использовании уникальных ID объектов возникает ошибка с кодом 7?

В API-запросах используются не уникальные ID объектов с вкладки Основное, а внутренние системные ID элементов. По умолчанию они не отображаются в веб-интерфейсах.

Чтобы получить системные ID элементов, можно использовать запрос поиска элементов по критериям (core/search_items). В ответе на данный запрос в параметре id будет находиться искомое значение.

Почему доступ к элементу ограничен, хотя пользователь имеет полные права?

Вероятно, проблема возникает из-за нехватки прав у используемого токена.

Для проверки прав токена выполните логин под ним:

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

В ответе будет содержаться параметр fl, который отображает текущие права токена. Чтобы их изменить, отредактируйте текущий токен или создайте новый.

Как получить последние координаты объектов?

Для получения последних координат от нескольких объектов можно использовать запрос поиска элементов по критериям (core/search_items). При этом необходимо указать флаги доступа, согласно которым в ответе отобразятся имена объектов ("flag":1") и информация о последнем местоположении объектов ("flag":1024). Флаги можно суммировать между собой, поэтому в запросе будет использоваться значение 1 + 1024 = 1025.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*","sortType":"sys_name"},"force":1,"flags":1025,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Как получить список всех доступных пользователю объектов?

Для вывода всех доступных пользователю объектов можно использовать запрос поиска элементов по критериям (core/search_items) со значением "propValueMask":"*".

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

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

Как получить имена групп, в которые включен определенный объект?

Чтобы получить имена групп, в которые входит объект с системным ID 11112222, необходимо использовать запрос поиска элементов по критериям (core/search_items) со значениями "itemsType":"avl_unit_group", "propName":"sys_units" и "propType":"list".

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit_group","propName":"sys_units","propValueMask":11112222,"sortType":"sys_name","propType":"list"},"force":1,"flags":1,"from":0,"to":0}}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Как получить имена объектов из определенной группы?

Чтобы получить имена объектов, которые входят в группу с именем Group, необходимо использовать два запроса поиска элементов по критериям (core/search_items): первый будет искать по группе объектов (avl_unit_group), а второй — по объекту (avl_unit).

1. Сначала нужно получить список системных ID объектов, которые входят в группу (ее имя нужно указать в параметре propValueMask):

   https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit_group","propName":"sys_name","propValueMask":"Group","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

    Ответ

   {
   	"searchSpec":{
   		"itemsType":"avl_unit_group",
   		"propName":"sys_name",
   		"propValueMask":"Group",
   		"sortType":"sys_name",
   		"propType":"",
   		"or_logic":"0"
   	},
   	"dataFlags":1,
   	"totalItemsCount":1,
   	"indexFrom":0,
   	"indexTo":0,
   	"items":[
   		{
   			"nm":"Group",
   			"cls":5,
   			"id":10000000,
   			"mu":0,
   			"u":[
   				20000001,
   				20000002,
   				20000003
   			],
   			"uacl":-1
   		}
   	]
   }
   

2. В ответе на предыдущий запрос необходимо найти параметр u с системными ID объектов. Их нужно подставить в параметр propValueMask для следующего запроса поиска:
   

   https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"sys_id","propValueMask":"20000001,20000002,20000003","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

    Ответ

   {
   	searchSpec:{
   		itemsType:"avl_unit",
   		propName:"sys_id",
   		propValueMask:"20000001,20000002,20000003",
   		sortType:"sys_name",
   		propType:"",
   		or_logic:"0"
   	},
   	dataFlags:1,
   	totalItemsCount:3,
   	indexFrom:0,
   	indexTo:0,
   	items:[
   		{
   			nm:"Unit_1",
   			cls:2,
   			id:20000001,
   			mu:0,
   			uacl:-1
   		},
   		{
   			nm:"Unit_2",
   			cls:2,
   			id:20000002,
   			mu:0,
   			uacl:-1
   		},
   		{
   			nm:"Unit_3",
   			cls:2,
   			id:20000003,
   			mu:0,
   			uacl:-1
   		}
   	]
   }
   

   Имена объектов будут отображаться в параметрах nm.

Почему отличаются результаты отчета в интерфейсе и в ответе на API-запрос?

При выполнении отчетов через API-запросы важно не забыть настроить часовой пояс для текущей сессии. Для этого сразу после авторизации следует однократно применить настройки локализации пользователя.

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