Сервер:Simple Json API 3.1
Murray (обсуждение | вклад) (Новая страница: «== HTTP Интерфейс == Сервер позволяет получить данные по любому устройству через HTTP/HTTPS запр…») |
Murray (обсуждение | вклад) |
||
Строка 11: | Строка 11: | ||
== Технические запросы == | == Технические запросы == | ||
+ | |||
+ | === Запрос информации по устройству === | ||
+ | |||
+ | '''Пример запроса''' | ||
+ | https://lserver.ru:8093/do.get.devices?imei=7HB000000 | ||
+ | для устаревших версий до 3.1.197 | ||
+ | https://lserver.ru:8093/do.admin?q=dg&imei=7HB000000 | ||
+ | |||
+ | В параметре ?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. | ||
+ | |||
+ | == Информационные запросы == | ||
+ | |||
+ | === Запрос последней зафиксированной точки === | ||
+ | |||
+ | В ответ на этот запрос сервер возвращает данные о текущем положении транспортного средства, оснащенного прибором с указанным 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|1365587868;55.199173;61.3906021;0;0|1365587963;55.199173;61.3906021;0;0|1365588035;55.199173;61.3906021;0;0|1365588106;55.199173;61.3906021;0;0|1365589583;55.199173;61.3906021;0;0|1365589588;55.199173;61.3906021;0;0|1365589595;55.199173;61.3906021;0;0|1365589677;55.1990204;61.39077;0;0|1365589692;55.1990204;61.39077;0;0|1365589704;55.1990204;61.39077;0;0|.... | ||
+ | |||
+ | ....|1365594194;55.199173;61.3906021;0;0|1365594200;55.199173;61.3906021;0;0|1365594254;55.199173;61.3905945;0;0|" | ||
+ | } | ||
+ | |||
+ | Сервер возвращает строку, содержащую список координат в кратком формате. Данные в строке разделены символом “|”. |
Версия 07:01, 29 ноября 2013
Содержание |
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.devices?imei=7HB000000
для устаревших версий до 3.1.197
https://lserver.ru:8093/do.admin?q=dg&imei=7HB000000
В параметре ?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.
Информационные запросы
Запрос последней зафиксированной точки
В ответ на этот запрос сервер возвращает данные о текущем положении транспортного средства, оснащенного прибором с указанным 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|1365587868;55.199173;61.3906021;0;0|1365587963;55.199173;61.3906021;0;0|1365588035;55.199173;61.3906021;0;0|1365588106;55.199173;61.3906021;0;0|1365589583;55.199173;61.3906021;0;0|1365589588;55.199173;61.3906021;0;0|1365589595;55.199173;61.3906021;0;0|1365589677;55.1990204;61.39077;0;0|1365589692;55.1990204;61.39077;0;0|1365589704;55.1990204;61.39077;0;0|....
....|1365594194;55.199173;61.3906021;0;0|1365594200;55.199173;61.3906021;0;0|1365594254;55.199173;61.3905945;0;0|" }
Сервер возвращает строку, содержащую список координат в кратком формате. Данные в строке разделены символом “|”.