RIW:Json API

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

Содержание

Структуры данных

На любой запрос сервер возвращает JSON объект, содержащий результат запрошенной операции. Если запрос обработан успешно, сервер возвращает структуру вида:

{
  result: результат запроса
}

В противном случае возвращается описание произошедшей ошибки:

{
  result: "error",
  code: 12345678,
  description: "описание ошибки"
}

Возможны следующие коды ошибок:

   ERROR_SUCCESS 		0x8000	Ошибок нет
   ERROR_IO_ERROR 		0x8001	Ошибка сети
   ERROR_ACCESS_DENIED 	0x8002	Доступ запрещен
   ERROR_INVALID_REQUEST 	0x8003	Ошибка запроса
   ERROR_DEVICE_NOT_FOUND 	0x8004	Устройство не найдено
   ERROR_SQL 			0x8005	Ошибка базы данных
   ERROR_PARSE 		0x8006	Ошибка разбора строки
   ERROR_LICENSE_NOT_FOUND	0x8007	Ошибка лицензии
   ERROR_REQUEST_NOT_SENT 	0x8008	Запрос невозможно отправить
   ERROR_REQUEST_NOT_FOUND 	0x8009	Запрос не обнаружен
   ERROR_REQUEST_TYPE 		0x800A	Несоответствие типа запроса
   ERROR_NO_MORE_DATA 		0x800B	Окончание потока данных
   ERROR_REQUEST 		0x800C	Ошибка при отправке запроса
   ERROR_UNKNOWN 		0x8FFF	Прочие ошибки


Результат запроса содержит объекты или массивы объектов предопределенного типа.

Navigation - единица навигационных данных

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

Основной формат

{
 time: "2013-09-20T07:44:47.000Z",	Время замера UTC
 referenceID: 1379655893071,		ID записи двоичных нанных на ККС
 navigationID: 90417128608825380,	ID записи нав. данных на ККС
 objectID: "2BK000000",		IMEI прибора
 objectType: "Locarus702",		Тип прибора
 dist: 0,				Дистанция
 mileage: 0,				Пройденный путь
 voltage: 87,				Напряжение бортовой сети
 message: "",				Текстовое сообщение
 extra: [ ],				Доболнительные данныес с прибора
 nativeFlags: 0,			Поле собственных флагов прибора
 digitalIn: 3,				Дискретные входы (битовое поле)
 analogIn: 				Аналоговые входы
 {
  1: 100,
  2: 38,
  3: 0,
  4: 0
 },
 Coords: 				Навигационные данные
 {
  lon: 37.93653869628906,		Долгота
  lat: 59.157073974609375,		Широта
  alt: 0,				Высота над у.м.
  speed: 13,				Скорость
  dir: 95.57012939453125,		Направление
  acceleration: 0,			Ускорение
  valid: true				Признак истинности измерения
 },
 Filter: 				Внутренние фильтры
 {
  filter: 0
 },
 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;     	// Ошибка потока данных 

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

{
 imei: "2BK000000",
 location: [массив объектов Navigation]
}

Краткий формат

{
  time: "2015-01-15T11:10:38.000Z",
  Flags: {
    flags: 50462746
  },
  Coords: {
    lon: 60.757225036621094,
    lat: 53.65165710449219,
    alt: 0,
    speed: 88,
    dir: -4.002501964569092,
    acceleration: 0,
    valid: true
  }
},

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

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

{
 imei: "2BK000000",
 location: [массив сокращенных объектов Navigation]
}

Sensors - значения датчиков

Возвращается в ответ на запрос значений датчиков по уже полученному треку. Имеет основной и краткий формат

Основной формат

{
 result: {
   objectID: "2BK000549",			IMEI устройства
   sensors: [					Массив датчиков
    {
     number: 1,				ID датчика
     value: [					Массив значений датчика
      {
        time: "2014-03-13T03:22:18.000Z",	Время замера
        value: 100				Значение
      },
      ...
     ]
    },
    ...
   ]
 }
}

Краткий формат

{
 result: {
   objectID: "2BK000549",			IMEI устройства
   sensors: [					Массив датчиков
    {
     number: 1,				ID датчика
     value: "12345678;100,12345679;101"	Значения датчиков
    },
    ...
   ]
 }
}

В кратком формате массив значений по каждому датчику представляется в виде строки, содержащей элементы, разделенные запятой. Каждый элемент содержит время замера в UNIXTIME и значение датчика, разделенные точкой с запятой.

Device - дескриптор транспортного средства (устройства)

{ 
 deviceID: 337769972054787800,			ID записи в базе на КС
 licenseID: 1603167583,			ID лицензии лицензии бд КС
 imei: "2BK000000",				IMEI устройства
 type: "Locarus702",				Тип устройства
 licenseDate: "2013-08-25T00:00:00.000Z",	Дата выдачи лицензии
 licenseLimitDate: "2013-08-25T00:00:00.000Z",	Дата начала ограничений по лиц.
 licenseBlackDate: "2013-08-25T00:00:00.000Z",	Дата окончания лицензии
 requestDate: "2013-08-08T00:00:00.000Z",	Не используется
 location: 
 {
   блок Navigation - текущее положение ТС
 },
 locationDate: "2014-05-23T14:00:00.000Z",	Время прихода последней точки
 locationState: 0,				Не используется
 blackDate: "2014-05-23T14:00:00.000Z",	Дата окончания обслуживания
 comment: "",					Комментарий
 number: "",					Гос. ТС
 remark: "",					Заметки владельца
 commentTime: "2013-05-23T12:27:35.147Z",	Дата изменения заметок
 remoteDeviceID: 1566,				ID записи на ККС
 remoteClientID: 106,				ID записи о клиенте владельце на ККС
 state: 0,					Статус устройства
 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.

User - учетная запись Пользователя

{
 userID: 548284664034720800,			Идентификатор в бд КС
 licenseID: 1603167583,			ID лицензии в бд КС
 lastActivity: "2013-09-20T08:19:26.404Z",	Время последней активности
 name: "TEST USER",				Имя пользователя
 email: "test@address.com",			E-mail
 login: "testUser",				логин пользователя
 date: "2013-09-19T10:48:04.702Z",		дата делегирования 
 remoteUserID: 45,				ID на ККС
 remoteClientID: 106,				ID клиента на ККС
 state: 32904,					Статус клиента
 devices: 					Список устройств
 [
   Массив дескрипторов Device
 ],
 parameters: 	
 {
   параметры задаваемые для пользователя/клиента
 },
 checkPoints: 	
 {
   список контрольных точек
 }
}

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

   STATE_CLIENT_ADMIN	0x01		Администратор клиента-автовладельца
   STATE_SUPER_ADMIN 	0x02		Суперадминистратор ККС
   STATE_DISPATCHER 	0x04		Диспетчер службы “Зеленый коридор”
   STATE_NAVIGATOR 	0x08		Доступ к навигационным данным ККС
   STATE_CALCULATOR 	0x10		Доступ к системе биллинга ККС
   STATE_MANAGER 	0x20		Доступ к системе администрирования ККС
   STATE_CHOP 		0x40		Участник службы “Зеленый коридор”
   STATE_DELEGATED 	0x80		Делегирован на Корневой сервер
   STATE_ONLINE 	0x8000		Признак активности Сессии на КС

RequestTrack - информация о запросе трека

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

{
 time: "2013-09-20T08:19:26.404Z",	Время посылки запроса
 state: 15,	Статус запроса
 count: 120,	К-во блоков в результате
 imei: "4GC000000",	IMEI 
 from: "2013-09-18T10:48:04.702Z",	время начала трека
 to: "2013-09-19T10:48:04.702Z",	время конца трека 
 message: "No errors",	Сообщение
}

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

   STATE_SENT	        0x0001	Запрос отправлен
   STATE_RECEIVING	0x0002	Идет процесс получения данных
   STATE_DONE	        0x0004	Все данные успешно получены
   STATE_FORGET 	0x0008	Запрос деактивирован по завершении сессии
   STATE_ERROR	        0x8000	Ошибка запроса. Расшифровка в Request.message

RequestData - информация о запросе данных трека

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

{
 time: "2013-09-20T08:19:26.404Z",	Время посылки запроса
 state: 15,	Статус запроса
 count: 1,	К-во блоков в результате
 message: "No errors",	Сообщение
}

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

   STATE_SENT	0x0001	Запрос отправлен
   STATE_RECEIVING	0x0002	Идет процесс получения данных
   STATE_DONE	0x0004	Все данные успешно получены
   STATE_FORGET 	0x0008	Запрос деактивирован по завершении сессии
   STATE_ERROR	0x8000	Ошибка запроса. Расшифровка в Request.message

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	Истинность
      }
    }
  ]
}

Запросы

Все параметры запросов могут передаваться как через POST так и через GET. Сервер понимает оба способа передачи данных. Описание приведено для запросов через GET.

Запросы могут быть двух видов - синхронные и асинхронные. Синхронные запрос возвращает результат сразу, асинхронный - только отправляет запрос на обработку Конечному серверу, и возвращает идентификатор этого запроса.

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

  • Проверять статус запроса
  • Многократно получать данные результата
  • Отправлять запрос повторно

Получение информации о Пользователе

https://server.ru:8094/do.main?q=info
Синхронный запрос. Корневой сервер возвращает структуру User. Если в момент аутентификации связанный с Сессией Конечный сервер не был доступен, массив devices может быть пустым, т.к. запрос списка устройств производится в начале каждой Сессии.
В запросе может быть передан дополнительный параметр mode=<short|full>, определяющий формат возвращаемых данных. При значение mode=short в качестве списка устройств передается массив строк IMEI, full - передается список полных дескрипторов Device. Если параметр mode не указан данные возвращаются в основном формате.

Получение списка устройств Пользователя

https://server.ru:8094/do.main?q=devices
Синхронный запрос. Корневой сервер возвращает структуру массив структур Devices, если не указан параметр mode или его значение mode=full. Если установлен параметр mode=short возвращается массив строк IMEI.
В запросе может быть задан параметр imei, который может задавать либо один IMEI прибора, либо несколько, перечисленных через запятую.
Если прибор защищен паролем, его необходимо указать в виде <imei>!<password>, отделив восклицательным знаком.

Принудительное завершение сессии

https://server.ru:8094/do.main?q=logout
Синхронный запрос. Корневой сервер завершает текущую сессию, отправляет запрос на прекращение трансляции на Конечный сервер и возвращает строку сообщения об успешном выходе Пользователя из системы.

Получение текущего положения транспортного средства

https://server.ru:8094/do.main?q=location&imei=<imei>
Синхронный запрос. Корневой сервер возвращает структуру или массив структур Navigation, отражающих текущее положение одного или нескольких транспортных средств. Параметр imei может задавать либо один IMEI прибора, либо несколько, перечисленных через запятую.
Если прибор защищен паролем, его необходимо указать в виде <imei>!<password>, отделив восклицательным знаком. Если при этом для указанного IMEI применяются другие параметры, например @..., то они должны быть указаны ПОСЛЕ пароля.
В запросе может быть передан дополнительный параметр mode=<short|full>, определяющий формат возвращаемых данных. При значение short навигационные данные возвращаются в кратком формате, full - в основном. Если параметр не передается данные возвращаются в основном формате.
Кроме того, некоторое количество поступивших координат кэшируется сервером. По умолчанию период кэширования установлен в 30 минут. Кэш координат создается для устройства в момент активизации трансляции текущих данных с ТТС, и уничтожается при деактивации устройства, т.е. спустя некоторое время после того как все пользовательские сессии, связанные с этим прибором, будут закрыты.
Содержимое этого кэша можно получить этим же запросом, добавив к IMEI дополнительный параметр <imei>@2013-09-13T15:01:53Z - указав время, ПОСЛЕ которого нужно получить список координат, либо <imei>@full - для того чтобы получить все содержимое кэша. При одновременном использовании в списке IMEI пароля и указания границы кэша сначала нужно указать пароль:
imei=2DD00024!password@2013-09-13T15:01:53Z 

Получение списка событий

https://server.ru:8094/do.main?q=events
Синхронный запрос. Корневой сервер возвращает массив структур Navigation, соответствующих моменту наступления какого-либо события. В настоящее время контролируется только сигнал тревоги (маска 0x04 поля Navigation.Flags.flags).
В запросе могут быть переданы дополнительные параметры:
  • action=count - запрос возвратит количество объектов в массиве.
  • tail=2013-09-13T15:01:53Z - запрос будет учитывать только события произошедшие позже указанного времени. :По умолчанию возвращается весь список событий с начала Сессии.

Запрос трека

https://server.ru:8094/do.main?q=track&imei=<imei>
Асинхронный запрос. Корневой сервер отправляет запрос Конечному серверу, возвращает идентификатор отправленного запроса и встает в состояние ожидания результата. По умолчанию будет сформирован запрос на получение навигационных данных за последние 10 минут от последней зафиксированной в системе точки. Если ни одной точки не зафиксировано отсчет ведется от текущего времени.
В запросе могут быть переданы дополнительные параметры:
  • period=<n> - определяет период в минутах, за который будут сформированы навигационные данные.
  • to=2013-09-13T15:01:53Z - дата и время в UTC конечной точки трека. Если не указано время начала трека то для его расчета используется параметр period. Если параметр period не указан - принимается продолжительность трека 10 минут.
  • from=2013-09-13T15:01:53Z - дата и время в UTC начальной точки трека.
  • filter=<on|off> - включение и отключение фильтрации данных на стороне ККС. По умолчанию фильтрация включена.
  • mode=<short|full> - режим short позволяет запросить сокращенный вариант данных по треку. С конечного сервера будут получены только координаты и время.
Если прибор защищен паролем, его необходимо указать в виде imei!password, разделив восклицательным знаком.

Повторная отправка запроса

https://server.ru:8094/do.main?q=track&id=<request-id>&action=again
Асинхронный запрос. Корневой сервер повторно направляет запрос Конечному серверу используя ранее сформированные параметры.

Получение статуса запроса

https://server.ru:8094/do.main?q=track&id=<request-id>&action=state
Синхронный запрос. Корневой сервер возвращает структуру RequestTrack, отражающую состояние запроса с идентификатором <request-id>.

Получение очередного блока данных

https://server.ru:8094/do.main?q=track&id=<request-id>

или

https://server.ru:8094/do.main?q=track&id=<request-id>&action=next
Синхронный запрос. Корневой сервер возвращает массив структур Navigation из очередного блока данных, полученного с Конечного сервера. После получения данных указатель запроса устанавливается на первый полученный блок. При первом запросе осуществляется парсинг первого полученного блока данных, после чего указатель сдвигается на следующий блок. При следующем запросе будет возвращен следующий блок данных, и т.д. В случае отсутствия данных возвращается пустой массив. В случае достижения конца полученных данных возвращается ошибка с кодом ERROR_NO_MODE_DATA.
В запросе могут быть переданы дополнительные параметры:
  • mode=<short|full> - В случае включения режима short возвращается массив структур Navigation в сокращенном формате.

Сброс указателя запроса

https://server.ru:8094/do.main?q=track&id=<request-id>&action=reset
Синхронный запрос. Корневой сервер устанавливает указатель запроса на первый полученный блок данных.

Получение количества полученных блоков данных

https://server.ru:8094/do.main?q=track&id=<request-id>&action=count
Синхронный запрос. Корневой сервер возвращает количество полученных блоков данных. Если при этом флаг статуса запроса STATE_DONE не установлен возвращается фактически полученное на текущий момент количество блоков. Если установлен - общее количество блоков в результате запроса.

Получение блока данных по индексу

https://server.ru:8094/do.main?q=track&id=<request-id>&block=<index>
Синхронный запрос. Корневой сервер возвращает массив структур Navigation из блока данных определяемого индексом index. Нумерация блоков начинается с 0. Если индекс выходит за рамки количества принятых блоков возвращается пустой массив.
В запросе могут быть переданы дополнительные параметры:
  • mode=<short|full> - В случае включения режима short возвращается массив структур Navigation в сокращенном формате.

Получение данных по датчикам отдельным списком

https://server.ru:8094/do.main?q=track&id=<request-id>&sensors=<список ID датчиков через запятую>
Синхронный запрос. Корневой сервер возвращает структуру Sensors содержащую список значений запрошенных датчиков, содержащихся в полученном треке. Возможно использование ключа &mode=short или &mode=full, что влияет на представление массива значений датчиков. в случае &mode=short массив представляется в виде строки вида <unixtime>;<value>,<unixtime>;<value>,...

Запрос дополнительной информации по треку

https://server.ru:8094/do.main?q=data&track=<track-request-id>
Асинхронный запрос. Корневой сервер отправляет запрос Конечному серверу, возвращает идентификатор отправленного запроса и встает в состояние ожидания результата. Запрашиваются данные по треку, ранее полученному через Запрос трека. В качестве параметра track используется идентификатор, возвращаемый Запросом трека.

Повторная отправка запроса информации

https://server.ru:8094/do.main?q=data&id=<request-id>&action=again
Асинхронный запрос. Корневой сервер повторно направляет запрос Конечному серверу используя ранее сформированные параметры. В качестве параметра id используется идентификатор запроса информации по треку.

Получение статуса запроса информации

https://server.ru:8094/do.main?q=data&id=<request-id>&action=state
Синхронный запрос. Корневой сервер возвращает структуру RequestData, отражающую состояние запроса с идентификатором <request-id>.

Получение данных запроса

https://server.ru:8094/do.main?q=data&id=<request-id>
Синхронный запрос. Корневой сервер возвращает JSON структуру формата Helpers, соответствующую полученной информации. В качестве параметра id используется идентификатор запроса информации по треку. Получение информации возможно только после того как статус запроса данных будет установлен в STATE_DONE. До этого, либо в случае отсутствия дополнительной информации, возвращается пустой JSON объект.

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

Изменение параметров устройства

Запрос позволяет конечному приложению изменить состав блока parameters устройства, хранящийся на Конечном сервере. Пользователь, от имени которого направляется запрос, должен иметь статус STATE_MANAGER, устанавливаемый на Конечном сервере. Устройство должно быть включено в список транспорта Пользователя.

https://server.ru:8094/do.main?q=update&imei=<imei>
Синхронный запрос. Корневой сервер через запрос POST принимает JSON структуру, содержащую параметры устройства, в формате объекта parameters структуры Devices. Например:
{"SpyCPIn":"0","Model":"m549","Sensors":"Uбс"}
Запрос перезаписывает параметры устройства на Конечном сервере в соответствии с полученными данными.

Изменение параметров Клиента Пользователя

Запрос позволяет конечному приложению изменить состав блока parameters Пользователя, хранящийся на Конечном сервере. Пользователь, от имени которого направляется запрос, должен иметь статус STATE_MANAGER, устанавливаемый на Конечном сервере. Параметры будут установлены для Клиента, зарегистрированного на Конечном сервере, к которому относится Пользователь, т.о. все Пользователи этого Клиента получат изменения в параметрах.

https://server.ru:8094/do.main?q=update
Синхронный запрос. Корневой сервер через запрос POST принимает JSON структуру, содержащую параметры Клиента, в формате объекта parameters структуры User. Например:
{"Options":{"IsTurnOn":"5","EuristicPoints":"2"}}
Запрос перезаписывает параметры Клиента на Конечном сервере в соответствии с полученными данными.

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

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

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

Установка задания таск-менеджера системы отчетов

Передача конечному серверу данных для задания таск-менеджера системы отчетов

https://server.ru:8094/do.main?q=task&id=<taskID>
Синхронный запрос.
Запрос возвращает Ok

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

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

https://server.ru:8094/do.main?q=calc_vars&imei=<imei>&vars=<vars>&from=<from>&to=<to>
Пакетный запрос. <imei> и <vars> - списки, в которых элементы разделены запятой.
Синхронный запрос.
Запрос возвращает Json пакет
Пример запроса: https://server:8094/do.main?q=calc_vars&imei=2NN000001,2NN000002&from=2018-01-01T00:00:00.000Z&to=2018-04-01T00:00:00.000Z&vars=Duration,Distance
RIW:Переменные
Личные инструменты
Пространства имён
Варианты
Действия
Навигация
Инструменты