Сервер:Simple Json API 3.1

Материал из ЛОКАРУС
(Различия между версиями)
Перейти к: навигация, поиск
(Запрос трека за период времени (NEW))
 
Строка 454: Строка 454:
 
:filter - Включает фильтрацию точек
 
:filter - Включает фильтрацию точек
 
:helpers - Если включено, то вместе с точками приходит отчет по треку.
 
:helpers - Если включено, то вместе с точками приходит отчет по треку.
 +
 +
1 - Остановки;
 +
2 - Смены;
 +
3 - Предупреждения;
 +
4 - События посещения контрольных точек;
 +
5 - Список датчиков для графиков;
 +
6 - Значения датчиков для графиков;
 +
 
:shift_vars - Список переменных для расчета по сменам.
 
:shift_vars - Список переменных для расчета по сменам.
 
:Синхронный запрос.  
 
:Синхронный запрос.  

Текущая версия на 12:22, 2 октября 2020

Содержание

HTTP Интерфейс

Сервер позволяет получить данные по любому устройству через HTTP/HTTPS запрос в виде JSON структуры. В качестве целевого URL используется сетевой адрес сервера и порт 8091 (значение по умолчанию, может быть изменен в конфигурации сервера) для HTTP и 8093 для HTTPS.

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

  • Параметры административного входа (параметры SERVER_ADMIN_LOGIN и SERVER_ADMIN_PASSWORD конфигурации сервера)
  • Параметры входа для доступа к навигационной информации на уровне сервера (SERVER_NAVIGATOR_LOGIN и SERVER_NAVIGATOR_PASSWORD)
  • Пароль уровня администратора клиента - автовладельца со списком принадлежащего ему транспорта
  • Пароль уровня пользовательского рабочего места с индивидуальным списком транспорта (д.б. установлено право доступа Navigator)
  • Пароль установленный индивидуально на устройство. В этом случае в качестве логина используется IMEI устройства.

Технические запросы

Версия сервера

Пример запроса

https://lserver.ru:8093/do.get.version

Возвращаемая структура

result: {
  versionCode: 50397387,						Код версии
  revisionCode: 1645,							Код релиза
  version: "3.1.203.1645",						Полная версия
  copyright: "(c) 2011-2014, Locarus Co. LTD, Chelyabinsk, Russia",	Копирайт
  author: "Dmitry G. Qusnetsov <murray@locarus.ru>",			Авторство
  releaseDate: "2014-08-21 09:42:23 +0600 (Чт, 21 авг 2014)"		Время сборки
}

Аутентификация

Пример запроса

https://lserver.ru:8093/do.login

Сброс текущей аутентификации. Сервер выдает в ответ HTTP 307, что в случае интерактивного запроса через браузер приводит к принудительному запросу логина и пароля.

Статус сервера

Пример запроса

https://lserver.ru:8093/do.state

Получение статистической информации о работе сервера, используемой в работе Монитора. Требуется уровень пользователя не ниже супер админа.

Возвращаемая структура

result: {
  serverVersion: "3.1.203.1645",			Версия сервера
  serverAddress: "95.142.101.131",			Внешний адрес
  serverLocal: "95.142.101.131",			Локальный адрес
  serverIdent: "LocarusServer",			Идентификатор внутренний
  serverUUID: "693fe749-297f-45d4-bd79-799ed79ec201",	Идентификатор универсальный
  upTime: 9383,					Время работы
  health: 20,						Здоровье
  tcpPassiveThreads: 63,				Кол-во пассивных TCP процессов
  tcpActiveThreads: 63,				Кол-во активных TCP процессов
  udpPassiveThreads: 0,				Кол-во пассивных UDP процессов
  udpActiveThreads: 0,					Кол-во активных UDP процессов
  memoryFree: 3151401232,				Свободная память
  memoryMax: 4352638976,				Общая максимальная память
  memoryTotal: 4352638976,				Общая выделенная память
  serverStartTime: "2014-08-22T07:35:40.781Z",		Время запуска сервера
  serverTime: "2014-08-22T10:12:04.180Z",		Время на сервере
  dbConnections: 50,					Кол-во соединений к БД
  lastReleaseVersion: "3.1.203.1645",			Последняя доступная версия
  needUpdate: false,					Флаг необходимости обновления версии
  needReboot: false,					Флаг необходимости перезагрузки
  statusLine: "",					Строка статуса
  sessionsCount: 0,					Количество пользовательских сессий
  receiversList: [					Список работающих приемников
    {
      name: "ClientProgram",				Название
      protocolID: 0,					Код протокола (0-TCP, 1-UDP)
      protocol: "TCP",					Имя протокола
      ports: [						Список активных портов
        1130,
        1128,
        1129
      ],
      locked: true,					Флаг запрета редактирования
      active: true,					Флаг активности
      server: false,					Признак HTTP/HTTPS сервера
      speed: 5418,					Средняя скорость обработки данных
      threads: 13,					Кол-во процессов
      loading: 20634,					Показатель нагрузки
      cacheSize: 0,					Размер кэша
      version: 1895,					Номер версии
      type: 201,					Внутренний код типа
      description: "Description not available"	Описание
    },
    ...
  ],
  transmittersList: [					Список работающих передатчиков
    {
      name: "2GIS",					Наименование
      version: 1559,					Версия
      active: false,					Флаг активности
      description: "Описание с HTML тегами",		Описание
      locked: false,					Флаг запрета редактирования
      virtual: false,					Признак динамически созданного передатчика
      broadcast: [					Список трансляторов
        {
          name: "2GIS test",				Наименование транслятора
          transmitter: "2GIS",				Наименование драйвера
          parameters: "params",			Строка параметров
          broadcastID: 15,				Идентификатор транслятора
          active: false,				Флаг активности
          locked: false,				Флаг запрета редактирования
          totaly: true,				Флаг передачи данных со всех устройств
          unhold: false,				Флаг игнорирования ошибок
          period: 0,					Период передачи
          queue: 0,					Размер очереди на передачу
          clients: [ 					Подключенные клиенты
             194,
             101
          ],
          devices: [ 					Подключенные устройства
             "4GI000000",
             "4GI000001",
             "4GI000002"
          ]
        },
       ...
      ]
    },
    ...
  ],
  ports: [						Список активных портов
    {
      protocolID: 1,					Код протокола (0-TCP, 1-UDP)
      protocol: "UDP",					Имя протокола
      port: 1129,					Номер порта
      lastPing: "2014-08-22T12:12:04.189Z",		Время последней активности
      lastDelay: 237,					Последнее время затр. на обработку данных
      health: 20,					Здоровье
      threads: 0,					К-во процессов
      loading: 0,					Показатель нагрузки
      cacheSize: 0,					Размер кэша
      server: false					Признак HTTP/HTTPS сервера
   },
   ...
  ],
  certs: [						Список активных сертификатов
   {
     name: "LOCARUS",					Наименование фирмы
     address: "95.142.101.131",			Адрес
     generated: "2013-03-14T11:35:38.412Z",		Дата активации лицензии
     expired: "2024-05-31T12:35:38.120Z"		Дата окончания лицензии
    },
    ...
   ]
  }
}

Запрос списка активных пользователей RIW

Пример запроса

https://lserver.ru:8093/do.get.online.users

Возвращаемая структура

result: [
  {
    name: "TEST USER",		Имя пользователя
    login: "testUser",		Логин
    count: 0,			Количество активных запросов RIW
    devs: 7,			Количество активных устройств
    host: "root.locarus.ru"	Корневой сервер с которого было подключение
  }
]

Активация приемника

Пример запроса

https://lserver.ru:8093/do.receiver.start?name=<ReceiverName>

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

Деактивация приемника

Пример запроса

https://lserver.ru:8093/do.receiver.stop?name=<ReceiverName>

Происходит остановка приемника с кодовым именем ReceiverName. Если в системе больше нет активных приемников работающих на освобождающихся портах, листенеры этих портов также деактивируются.

Запуск киллера

Пример запроса

https://lserver.ru:8093/do.killer.start

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

Перезапуск сервера

Пример запроса

https://lserver.ru:8093/do.reboot

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

Информационные запросы

Запрос информации по текущему пользователю

Пример запроса

https://lserver.ru:8093/do.get.current.user

Возвращаемая структура содержит информацию о текущем пользователе.

Возвращаемая структура

 {
  result: 
  {	
   name: "TEST USER",                  Имя пользователя
   email: "",                          E-mail
   login: "testUsr",                   Логин
   date: "2013-11-25T10:40:34.827Z",   Дата создания учетной записи
   clientID: 106,                      Внутр. ID родительского клиента
   userID: 45,                         Внутр. ID пользователя
   state: 32937,                       Флаги статуса
   devices:                            Список IMEI доступных устройств
   [
     "2BK000000",
     "2BK000001",
     "2BK000002",
     "2CD000001",
     "2CD000002",
     "4EL000000",
     "FTEST"
   ]
 }

}

Поле state может содержать следующие значения:

 STATE_CLIENT_ADMIN 	0x001	Пользователь является администратором клиента
 STATE_SUPER_ADMIN 	0x002	Пользователь является суперадминистратором 
 STATE_DISPATCHER 	0x004	Статус диспетчера 
 STATE_NAVIGATOR 	0x008	Доступ к навигационной информации
 STATE_CALCULATOR 	0x010	Доступ к системе биллинга
 STATE_MANAGER 		0x020	Доступ к административным функциям
 STATE_CHOP 		0x040	Статус ЧОП Зеленого Коридора
 STATE_DELEGATED 	0x080	Пользователь делегирован для работы в RIW

Запрос информации по устройствам

Пример запроса

https://lserver.ru:8093/do.get.devices?imei=7HB000000

В параметре ?imei= могут быть перечислены несколько идентификаторов устройств через запятую. Если указан только один идентификатор, возвращаемый массив содержит только один элемент. Если в запросе do.get.devices параметр ?imei= отсутствует, запрос возвращает массив, содержащий полный список транспорта, доступный текущему пользователю.

Возвращаемая структура

{
  result: 	Массив объектов
  [
    {
      imei: "2CD000000",			IMEI устройства
      type: "Locarus702",			Тип устройства
      blackDate: "2014-05-23T14:00:00.000Z",	Дата окончания обслуж-я
      number: "",				Гос. номер
      comment: "",				Комментарий
      commentTime: "2013-05-23T12:26:56.854Z",	Время уст. комментария
      remark: "",				Заметки диспетчера
      deviceID: 1554,				Внутр. ID устройства
      clientID: 106,				Внутр. ID владельца
      state: 0,				Статус устройства
      ident: 335545662,			Уникальный ID
      queueSize: 0,				Размер необр. очереди
      queueDelay: 0,				Время задержки обр-ки
      lastPacketTime: "2013-11-25T06:04:37.166Z",	Вр. посл. пакета данных
      lastUploadTime: "2013-11-25T06:04:36.461Z",	Вр. посл. забранного п.
      lastQueryTime: "2013-11-25T06:04:37.166Z",	Вр. посл. запрошенного п.
      daysWaitingUpload: 0,			Период невостребованности
      daysWaitingQuery: 0,			Период невост. по запр.
      balance: 0,				Баланс по устройству
      licenseDate: "1970-01-01T01:00:00.000Z",	Дата выдачи лицензии
      licenseBlackDate: "2014-11-24T22:18:14.832Z",	Дата окончания лицензии
      licenseLimitDate: "2014-11-24T22:18:14.832Z",	Дата наступл-я ограничен.
      parameters: { }				Динамические параметры
    }
  ]
}

Поле state представляет собой битовое поле, которое может содержать следующие значения:

   STATE_BILLING_INACTIVE 	0x10	Признак включения в систему биллинга на ККС
   STATE_LICENSED 		0x20	Признак лицензируемости
   STATE_LICENSED_FOREVER 	0x40	Устройство имеет безлимитную лицензию
   STATE_PROTECTED 		0x80	Устройство защищено паролем
   STATE_OPTIMIZED 		0x100	Устройство работает в режиме DEV_TYPE_NAVI

Старшие 15 бит ((state >> 16) & 0x7FFF) определяют код типа лицензии, в случае если установлен бит STATE_LICENSED.

Helpers - дополнительные данные по треку

Данные возвращаемые в ответ на запрос информации по идентификатору ранее отправленного запроса данных.

{
  1: 	Код хелпера. 1 - остановки
  [	Массив значений хелпера
    {
      indexBegin: 0,	Индекс нач. ост. в треке
      indexEnd: 21,	Индекс конца ост. в треке
      timeBegin: "2013-10-10T07:13:47.000Z",	Время начала остановки
      timeEnd: "2013-10-10T07:22:47.000Z",	Время конца остановки
      coords: 	Координаты остановки
      {
        lon: 37.936851501464844,	Долгота
        lat: 59.15705871582031,	Широта
        alt: 0,	Высота
        speed: 0,	Скорость
        dir: 0,	Направление
        acceleration: 0,	Ускорение
        valid: true	Истинность
      }
    }
  ]
}


Запрос последней зафиксированной точки

В ответ на этот запрос сервер возвращает данные о текущем положении транспортного средства, оснащенного прибором с указанным IMEI. Данные могут быть получены в полной версии - при этом возвращается JSON пакет содержащий все навигационные и параметрические данные прибора, либо в краткой версии - при этом возвращается только время и координаты прибора. Для указания необходимости получения полной версии данных используется параметр “m” (mode) со знавением “full” (полный).

Пример запроса полной версии данных

http://lserver.ru:8091/do.locator?f=now&m=full&imei=6FI000000

Возвращаемая структура

{
  result: 
  {
     time: "2013-11-25T05:14:13.000Z",	Время измерения UTC
     referenceID: 1385356498797,	Внутренний идентификатор данных
     navigationID: 90790723505881120,	Внутренний идентификатор записи
     objectID: "2CD000000",		IMEI устройства
     objectType: "Locarus702",		Тип устройства
     dist: 0,				Дистанция (не используется)
     mileage: 0,			Пройденный путь 
     voltage: 90,			Напряжение бортовой сети
     message: "",			Текстовое сообщение
     extra: [ ],			Дополнительные данные
     nativeFlags: 0,			Оригинальные флаги устройства
     digitalIn: 3,			Дискретные датчики (битовое поле)
     analogIn: 			Аналоговые датчики
     {
       1: 96,
       2: 129,
       3: 0,
       4: 0
     },
     Coords: 				Навигационные данные
     {
       lon: 39.92680358886719,		Долгота
       lat: 59.223106384277344,	Широта
       alt: 0,				Высота
       speed: 0,			Скорость
       dir: 168.43283081054688,	Направление
       acceleration: 0,		Ускорение
       valid: true,			Признак истинности измерения
       packetSize: 26			Внутренний размер пакета
     },
     Filter: 
     {
       filter: 1			Внутренняя фильтрация данных
     },
     Flags: 
     {
       flags: 2			Флаги
     },
     Satellites: 
     {
       count: 0,			Количество спутников
       countGlonass: 0,		Из них спутников ГЛОНАСС
       hdop: 0,			HDOP
       vdop: 0				VDOP
     },
     changes: 51539607582,		Битовое поле признаков смены данных
     parsedPacketSize: 148,		Внутренний размер пакета
     framePacket: false		Внутренний признак фрейма
  }
}

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

   FLAG_MOTION = 0x01;        	// Признак движения транспортного средства
   FLAG_ONLINE = 0x02;        	// Прибор на связи с сервером
   FLAG_ALERT = 0x04;         	// Тревожная кнопка
   FLAG_POWEROFF = 0x08;      	// Отключение питания
   FLAG_CURRENTSTATE = 0x10;    // Внеочередные текущие координаты
   FLAG_SATELLITE = 0x20;       // Точка со спутника. Вне основного потока данных.
   ENGINE1_ON = 0x100;        	// Признак работы двигателя №1
   ENGINE2_ON = 0x200;        	// Признак работы двигателя №2
   DEVICE_MESSAGE = 0x2000;   	// Сообщение от устройства 
   DEVICE_ERROR = 0x4000;     	// Ошибка от устройства 
   STREAM_ERROR = 0x8000;     	// Ошибка потока данных 


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

http://lserver.ru:8091/do.locator?f=now&imei=6FI000000

Возвращаемая структура

{
  result: "|1372850393;55.2964249;61.2055283;0;0|"
}

В пакете три поля, определяющие положение устройства, разделенные точкой с запятой. Первое поле - время UTC в формате UNIX TIME. Второе - широта (latitude) в градусах и долях градуса, третье - долгота (longitude). Значение широты может быть отрицательным для южных широт. Значение долготы может быть отрицательным для западной долготы.

Запрос трека за период времени

Для запроса данных, полученных с прибора, за нужный период, в запросе нужно указать начальное и конечное время. Время указывается в UTC, используется SOAP формат, без миллисекунд. Для задания начального времени используется параметр “f” (from), для конечного - “t” (to). Для указания необходимости получения полной версии данных используется параметр “m” (mode) со значением “full” (полный).

Пример запроса полной версии данных

http://lserver.ru:8091/do.locator?f=2013-04-09T12:26:17Z&t=2013-04-11T12:26:17Z&m=full&imei=7HB000000

Возвращаемая структура

Запрос возвращает массив объектов, описанных в разделе “запрос последней зафиксированной точки”

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

http://lserver.ru:8091/do.locator?f=2013-04-09T12:26:17Z&t=2013-04-11T12:26:17Z&m=full&imei=7HB000000

Возвращаемая структура

{
  result:"|1365587776;55.199173;61.3906021;0;0|...|1365594254;55.199173;61.3905945;0;0|"
}

Сервер возвращает строку, содержащую список координат в кратком формате. Данные в строке разделены символом “|”.

Запрос текущего положения и хвостов

Получение последней точки или хвоста по приборам(imei).

http://lserver.ru:8091/do.locator?q=location&imei=<imei>@full&mode=<mode>
Пакетный запрос.
<mode> - Указывает формат точки.
<imei> - Список приборов, в которых элементы разделены запятой.
Полный синтаксис <imei> = imei!password@tail.
password - указывается в случае необходимости.
tail - указывает время, начиная с которого нужен хвост. Есть спец значение full для всего хвоста.
Если параметр tail не указан, то возвращает последнюю точку. Иначе массив точек.
Синхронный запрос.
Запрос возвращает Json пакет

Пример запроса

http://lserver.ru:8091/do.locator?q=location&imei=2NN000001,2NN000002!123,2NN000003@full&mode=short

Возвращаемая структура

{
 "result":
 {
  "2NN000001":{"sensors":[<sensors list>],"status":"OK","data":[<navi list>]},
  "2NN000002":{"sensors":[<sensors list>],"status":"OK","data":[<navi list>]},
  "2NN000003":{"sensors":[<sensors list>],"status":"OK","data":[<navi list>]}
 }
}

Запрос трека за период времени (NEW)

Для запроса данных, полученных с прибора, за нужный период, в запросе нужно указать начальное и конечное время. Время указывается в UTC, используется SOAP формат, без миллисекунд. Для задания начального времени используется параметр “from”, для конечного - “to”. Для указания необходимости получения полной версии данных используется параметр “mode” со значением “full” (полный).

http://lserver.ru:8091/do.locator?q=track&imei=<imei>&from=<date>&to=<date>&filter=<true/false>&helpers=<true/false>&mode=<mode>&shift_vars=<vars list>
Пакетный запрос.
<mode> - Указывает формат точки. short/full
imei - Указывает прибор, по которому получаем трек.
Полный синтаксис <imei> = imei!password.
password - указывается в случае необходимости.
filter - Включает фильтрацию точек
helpers - Если включено, то вместе с точками приходит отчет по треку.
1 - Остановки;
2 - Смены;
3 - Предупреждения;
4 - События посещения контрольных точек;
5 - Список датчиков для графиков;
6 - Значения датчиков для графиков; 
shift_vars - Список переменных для расчета по сменам.
Синхронный запрос.
Запрос возвращает Json пакет

Пример запроса

http://lserver.ru:8091/do.locator?q=track&imei=2NN000001&mode=short&helpers=true&filter=true&from=2019-02-01T00:00:00Z&to=2019-02-02T00:00:00Z

Возвращаемая структура

{
 "result":
 {
  "data":[],
  "helpers":{}
 }
}

Получение переменных устройства

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

http://server.ru:8091/do.get.vars?imei=<imei>
Синхронный запрос.
Запрос возвращает Json пакет, содержащий массив строк


Расчет переменных

Расчитать переменные(vars) по приборам(imei) за выбранный промежуток времени (from - to).

http://server.ru:8091/do.calc.vars?imei=<imei>&vars=<vars>&from=<from>&to=<to>
Пакетный запрос. <imei> и <vars> - списки, в которых элементы разделены запятой.
Синхронный запрос.
Запрос возвращает Json пакет
Пример запроса: http://server:8091/do.calc.vars?imei=2NN000001,2NN000002&from=2018-01-01T00:00:00.000Z&to=2018-04-01T00:00:00.000Z&vars=Duration,Distance
RIW:Переменные


Запрос отчета

Сформировать отчет типа type по переменным(vars) для приборам(imei) с опциями options и параметрами params.

http://server.ru:8091/do.get.report?imei=<imei>&vars=<vars>&type=<type>&options=<optioins>&params=<params>
Пакетный запрос.
type - Тип отчета. (REPORT_RACE_LIST = 0; REPORT_CHECK_POINTS = 1; REPORT_WARNINGS = 2; REPORT_MOVING_CONTROL = 3;)
<imei> - список, в котором элементы разделены запятой.
Параметр запроса vars - json list. Содержит объекты с ключами: name, format, hide, sort.
Параметр запроса options - json object. Содержит единые набор парметров для отчетов всех типов.
options = {
 "from":<timestamp? / long ms / double ms>,
 "to":<timestamp? / long ms / double ms>,
 "offset":<long> // timeZoneOffset, minutes
};
Параметр запроса params - json object. Содержит только те параметры, которые нужны для расчета именно указанного отчета.
shifts_param = {
 "only_total_shift": <boolean>,
 "divide_on_days": <boolean>
};

repCPCurrent = 1; repCPMoving = 2; repCPListVisited = 3; repCPListAll = 4; repCPUnVisited = 5;

check_param = {
 "list_type": <double> // int list_type = (int) (getParamAsDouble(params, "list_type", 0) + 1.5);
};
war_param = {
 "use_mask": <boolean>
 "warning_mask": <string>,//",,,,",
 "reconnection_warn","power_loss_warn", "navigation_loss_warn", "sensor1_warn", "sensor2_warn", 
                             "", "", "", "fuelling_warn", "fuel_drain_warn", "others_warn",
                             "","", "",
                             "", "accum_warn" <boolean>
};
moving_param = {
 "moved_out_flag": <boolean>,
 "moved_out_start": <long>,
 "moved_out_end": <long>,
 "not_moved_out_flag": <boolean>,
 "not_moved_out_start": <long>,
 "not_moved_out_end": <long>,
 "started_after_flag": <boolean>,
 "started_after": <long>,
 "finished_later_flag": <boolean>,
 "finished_later": <long>
};
Синхронный запрос.
RIW:Переменные


Запрос значений датчиков за период

http://server:port/do.get.sensor.values?imei=<imei>&from=<datetime>&to=<datetime>&varname=<varnameList>

Запрос работает по одному прибору
imei - прибор по которому идет запрос
from - левая граница периода
to - правая граница периода
varname - список имен переменных для расчета через запятую


Пример запроса

http://server:8091/do.get.sensor.values?imei=2NN000002&from=2020-08-01T00:00:00Z&to=2020-08-02T00:00:00Z&varname=Speed,UPower

Возвращаемая структура

{
 "result":
 {
  "data":
  [
   {
    "time":1596240094000,
    "values":
    {
     "Speed":0.0,
     "UPower":18.428571428571427
    }
   },
   .....
  ]
 }
}
Личные инструменты
Пространства имён
Варианты
Действия
Навигация
Инструменты