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 Прочие ошибки
Результат запроса содержит объекты или массивы объектов предопределенного типа.
Представляет собой структуру данных, полученных с навигационного оборудования, прошедшую предварительную обработку.
Основной формат
{ 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; // Отключение питания 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", 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. Например:
{"Параметры":{"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