Сервер:Simple Json API 3.1

Материал из ЛОКАРУС
Перейти к: навигация, поиск

Содержание

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

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

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

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

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

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

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

В ответ на этот запрос сервер возвращает данные о текущем положении транспортного средства, оснащенного прибором с указанным 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;      	// Отключение питания
   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|"
}

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

Личные инструменты
Пространства имён
Варианты
Действия
Навигация
Инструменты