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

В данной статье собраны ответы на наиболее часто задаваемые вопросы касательно 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=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значениеОписание
"callMode":"create"

В качестве действия выбрано создание (также доступны редактирование и удаление).

"app":"locator"Значение locator необходимо для отображения в списке ссылок в веб-интерфейсе.
"at":0

Время активации токена в UNIX-time равно 0, то есть локатор начнет работу сразу после создания.

"dur":0

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

"fl":256Данное значение флагов доступа предоставит возможность только отслеживать объекты в режиме онлайн.
"p":"{\"note\":\"Bus\",\"zones\":1,\"tracks\":0}"В качестве примечания будет использоваться слово Bus, которое позволит отличить локатор от других в общем списке. Локатор будет отображать геозоны, но не будет отображать треки объектов.
"items":[11111111,22222222,12345678]

В локаторе будут отображаться объекты с системными ID 11111111 и 22222222, а также геозоны из ресурса с системным ID 12345678.

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

Токен автоматически удаляется, если он не используется в течение 100 дней, даже если срок его жизни не ограничен (параметр duration или dur равны 0).

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

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

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

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

Как исправить ошибку с кодом 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.

Для проверки кодировки в 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 будет находиться искомое значение.

Другие методы отображения системных ID описаны в статье Введение в SDK: базовые запросы.

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

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

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

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

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

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

Н
апример, если необходимо предоставить право на слежение онлайн ("fl":256) и доступ к большей части информации ("fl":512), то стоит использовать значение "fl":768, так как 256 + 512 = 768.

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

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

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

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

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