Введение в SDK: базовые запросы

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

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

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

• Портал для разработчиков с документаций и подробным описанием каждого запроса.
• Примеры готовых решений с использованием SDK из раздела Маркетплейс.
• Серия вебинаров Wialon API и SDK: обучающие видео.
• Коллекция примеров в приложении Postman для тестирования API-запросов.
• Раздел форума Собственные разработки под Wialon.

В начале изучения 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=ИДЕНТИФИКАТОР_СЕССИИ

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

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

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

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

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

2. В параметрах запросов при просмотре сетевых запросов в браузере.

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

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

   

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

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

Here’s the Markdown with bold text replaced by backticks (inline code):

• 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 — административные поля.

Системные 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=ИДЕНТИФИКАТОР_СЕССИИ

Ответ

{
  "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.

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

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