Описание API Навител Мониторинг

Для всех запросов публичного JSON-RPC API используется префикс «public-1.0-». В последующем описании всех методов этот префикс подразумевается. Например, метод, описанный ниже как group.get должен вызываться как public-1.0-group.get.

• Поле id — монотонно увеличивающийся идентификатор запроса, целое число;

• Поле method — название метода, строка;

• Поле params — список, возможно, пустой аргументов метода.

Поскольку JSON-RPC API предназначено для роботов, то входящие запросы сейчас не будут поддерживать фильтры и пейджирование. Вся фильтрация должна осуществляться на стороне инициатора запроса.

Все методы возвращают код HTTP и тело ответа. В случае, если запрос является допустимым HTTP-запросом, возвращается код HTTP 200, а в качестве тела ответа — JSON объект. Если запрос завершился успешно, то возвращаемый объект содержит поле result.

Возвращаемое в поле result значение специфично для каждого из запросов и описано ниже.

Если запрос был отклонен по причинам, связанным с корректностью формирования HTTP-запроса, то возможны соответствующие коды ошибок HTTP (например, 400, 403, 404, 405 и т.п.).

Если запрос был синтаксически корректен, но при выполнении произошла ошибка уровня Диспетчерской Системы, то возвращается код HTTP 200, но возвращаемый JSON-объект имеет не поле result, а поле error:

Форматы возможных ошибок при выполнении запросов описаны ниже.

Перед созданием каких-либо мониторинговых запросов необходимо создать запрос на вывод списка транспортных средств и их идентификационных характеристик. Для этого нужно создать запрос в формате GET:

где «apikey=[val]» — параметр типа «имя/значение», в котором «apikey» является именем, а «[val]» — значением. Полученный в настройках диспетчерской системы API ключ необходимо вставить на место значения «[val]» данного параметра. Таким образом, запрос с введенным значением параметра apikey будет выглядеть следующим образом:

Кроме того, в конце запроса также должен быть параметр фильтра имени

где «[value]» — значение фильтра. Вы можете указать название имени объекта, информацию о котором вы хотите получить, или оставить поле пустым, чтобы получить информацию о всех объектах, как показано в примере выше.

В качестве ответа на такой запрос будет представлен список машин с указанием их идентификационных характеристик. Код будет представлен в формате XML или JSON.

Ответ содержит следующую идентификационную информацию о средствах передвижения: группа/компания (в диспетчерской системе), imei/id трекера, тип трекера, id машины, имя машины. Эта информация потребуется для выполнения последующих запросов, в которых вам понадобится указывать идентификационные данные тех объектов, по которым вы хотите сделать запрос.

При написании запроса вы можете указать предпочтительный формат получаемого ответа: xml или json. Для этого, в запросе после «vehicles» напишите «.xml» или «.json» (это возможно сделать в любом типе запросов к диспетчерской системе).

Результат этого запроса будет доставлен в форме xml кода

в этом примере результатом запроса будет код json

JSON-RPC API использует для идентификации API ключ, который является первым обязательным параметром всех методов, кроме apikey.get. Для получения API ключа в строке меню нажмите Настройки (). В открывшемся диалоговом окне выберите вкладку API, нажмите кнопку Создать.

• apikey.get - получение API ключа по имени пользователя и паролю

  • Параметры:

    • login - имя пользователя (логин)

    • password - пароль

  • Результат:

    • строка API ключа

• group.get — получение списка групп.

  • Параметры:

    • Объект, содержащий следующие поля:

      • (опциональный) parent_group_uuid_list – необязательный список родительских групп. Родительские группы должны быть доступны пользователю, выполняющему запрос. В случае отсутствия или пустого списка в запросе результат содержит все группы верхнего уровня, доступные пользователю, или все группы, если параметр recursive равен True.

      • recursive — boolean перечислять ли группы рекурсивно.

  • Результат:

    • список структур, описывающих группы. Документированы следующие поля в структурах:

      • обязательные:

        • uuid — UUID группы

        • name — название группы

      • необязательные:

        • parent_group_uuid — UUID родительской группы, если родительская группа существует и пользователю доступен API ключ

        • limits — объект, содержащий список ограничений, если ограничения заданы для группы (группа является компанией):

          • max_users — максимальное количество пользователей, целое число или null, если ограничение не задано

          • max_vehicles — максимальное количество машин, целое числи или null, если ограничение не задано

          • valid_until — срок действия лицензии, строка в формате ISO-8601 или null, если ограничение не задано

• group.create — создание групп.

  • Параметры:

    • groups — список объектов, описывающих создаваемые группы. В каждом объекте документированы те же поля, что и поля group.get. Не следует указывать UUID группы, поле будет проигнорировано.

  • Результат

    • список UUID созданных групп.

• group.edit — изменение выбранных полей в существующих группах.

  • Параметры:

    • group_fields — словарь объектов, описывающих изменяемые поля групп. Ключами в словаре являются UUID групп. Поля в объектах соответствуют полям в group.get. Неуказанные в объекте поля не изменяются. Отсутствие на момент выполнения запроса группы с указанным UUID является ошибкой.

  • Результат отсутствует

• group.delete — удаление групп.

  • Параметры:

    • uuid_list — список UUID удаляемых групп. Отсутствие на момент выполнения запроса группы с указанным UUID ошибкой не считается.

  • Результат отсутствует

• vehicle.get — получение списка устройств слежения для указанной группы.

  • Параметры:

    • parent_group_uuid — UUID группы.

  • Результат:

    • список структур, описывающих объекты мониторинга в данной группе. В каждой структуре документированы следующие поля:

      • обязательные:

        • uuid — UUID объекта мониторинга

        • name — название объекта мониторинга

        • parent_group_uuid — UUID родительской группы

        • tracker_type — строка идентифицирующая тип трекера, из фиксированного списка строк (enum), В настоящее время в списке ровно один элемент - OLYMPSTROY. В дальнейшем список трекеров, поддерживаемых данным API, будет расширен

        • tracker_identifier — строка или набор строк, идентифицирующие экземпляр трекера данного типа.
          Примечание: в настоящее время трекеров, требующих массив строк, нет, позднее они будут явно перечислены

      • необязательные:

        • display_icon — номер иконки. В настоящее время стандартизованы номера от 0 до 14 включительно.

        • display_color — цвет иконки, строка в формате CSS hexadecimalcolors (#RRGGBB).

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

• vehicle.create — создание новых объектов мониторинга.

  • Параметры:

    • vehicles — список структур, описывающих создаваемые объекты мониторинга. UUID не указывается (задается сервером). Допустимые поля соответствуют полям в vehicle.get. Обязательными для указания являются поля:

      • name

      • parent_group_uuid

      • tracker_type

      • tracker_identifier

  • Результат:

    • список UUID'ов созданных объектов мониторинга или ошибка, если хотя бы один из запрошенных объектов не может быть создан.

• vehicle.edit — редактирование свойств объектов мониторинга.

  • Параметры:

    • vehicle_fields — словарь, ключами которого являются UUID объектов мониторинга, а значениями — структуры, описывающие изменения в объектах. Допустимые поля соответствует полям в vehicle.get. Неуказанные в запросе поля не изменяются. Невозможность по тем или иным причинам отредактировать хотя бы один из объектов из перечисленных приводит к ошибке всего запроса, никакие изменения не применяются.

  • Результат:

    • отсутствует, если операция завершена успешно, либо отображается сообщение об ошибке в установленном формате.

• vehicle.delete — удаление объектов мониторинга.

  • Параметры:

    • uuid_list — список UUID удаляемых объектов мониторинга. Отсутствие на момент выполнения запроса объекта с указанным UUID ошибкой не считается.

  • Результат: отсутствует, если операция завершена успешно, или сообщение об ошибке в установленном формате.

• role.get — получение списка ролей для указанной группы.

  • Параметры:

    • parent_group_uuid — UUID группы.

  • Результат:

    • список структур, описывающих роли в данной группе. В каждой структуре документированы поля:

      • uuid — UUID роли

      • name — название роли

• user.get — получение списка пользователей для указанной группы.

  • Параметры:

    • parent_group_uuid — UUID группы.

  • Результат:

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

• user.create — создание пользователей.

  • Параметры:

    • Users — список структур, описывающих создаваемых пользователей. UUID не указывается (задается сервером).

  • Результат:

    • список UUID созданных пользователей.

• user.edit — изменение выбранных полей у существующих пользователей.

  • Параметры:

    • user_fields — словарь структур, описывающих изменяемые поля пользователей. Ключами в словаре являются UUID пользователей. Неуказанные в структуре поля не изменяются. Отсутствие на момент выполнения запроса пользователя с указанным UUID является ошибкой.

  • Результат отсутствует

• user.setPassword – установка пароля пользователю.

  • Параметры:

    • uuid – UUID пользователя

    • password – новый пароль

• user.delete — удаление существующих пользователей.

  • Параметры:

    • uuid_list — список UUID удаляемых пользователей. Отсутствие на момент выполнения запроса пользователя с указанным UUID ошибкой не считается.

  • Результат отсутствует

JSON-RPC запрос выглядит так:

Формат ответа:

Запрос к диспетчерской системе можно представить как совокупность элементов: основной URL и параметры запроса. К базовому (основному) URL относится вся та часть запроса, которая находится до окончания указания расширения xml или json.
Пример основного URL, используемого при создании любых запросов к диспетчерской системе:

(исключением является запрос на получение списка машин, обращающийся к другому URL)
Параметры запроса представляют собой ряд пар типа «имя/значение», где каждая пара отделяется амперсандом («&»). Список параметров начинается сразу после вопросительного знака, следующего за указанием расширения. Всякий параметр имеет следующую форму:

где «field» — имя параметра, а «[value]» — значение. API запросы к диспетчерской системе распознают следующие имена параметров: «id», «name», «imei», «time», «what», «apikey».
Обратите внимание, что такие запросы чувствительны к регистру букв.

Запрос обычно содержит набор следующих параметров:

1. Идентификаторы автомобиля. Автомобиль можно выбрать, используя один из трех доступных для каждого автомобиля идентификаторов: «id», «name», «imei». Пример ввода параметра:

где «[vehicle_static_id_0]» — это ID автомобиля, который можно узнать, сделав запрос на получение списка машин.

Идентификаторы — простые параметры, такие же, как параметры apikey или какой бы то ни было еще в запросах к диспетчерской системе. Таким образом, в одном запросе можно указать больше одного идентификатора, что позволит получить информацию о нескольких автомобилях сразу.

Как и прочие параметры, параметры-идентификаторы должны отделяться друг от друга амперсандом:

Вы также можете использовать разные типы идентификаторов для выбора автомобилей, например:

Если получилось так, что значения разных идентификаторов определяют один и тот же автомобиль, ничего страшного, этот автомобиль не будет отображен дважды.

2. Ключ API Пример:

где «apikey» является именем, а «[val]» — значением. Полученный в настройках диспетчерской системы API ключ необходимо вставить на место значения «[val]» данного параметра.

3. Набор запрашиваемых параметров, each parameter separated by an ampersand ("&"):

где «[field]» — имя параметра, «[value]» — значение параметра. Используйте таблицы ниже в качестве руководства по написанию мониторинговых запросов.

К этому моменту вы должны уметь включать в запрос идентификаторы автомобилей и API ключ. Однако неисследованными остались мониторинговые параметры. Их можно условно разделить на две группы: временные и информационные. В этой главе будут рассмотрены информационные параметры. Обращение к таким параметрам осуществляется через запросы с помощью использования имени «what» и выбора подходящего значения. Значения разных запросов указаны в таблице ниже.

Например, если бы было необходимо получить информацию о скорости какого-либо объекта на текущий момент времени, потребовалось бы в поле имени параметра указать «what», а в поле значения, согласно таблице, приведенной ниже, указать значение «speed_kmh»:

полный запрос выглядел бы следующим образом:

В этом примере была запрошена информация о скорости объекта, именуемого «NaviCar», а также использован ключ API «00000000000000000000000» для получения доступа к информации диспетчерской системы. Аналогичным образом вы можете создавать и иные запросы, используя имена и значения для параметров, указанные в таблице ниже.

Существуют временные параметры двух типов. Первый — фиксированное время. Второй — интервал времени. Если ни один из временных параметров не задан, то запрос возвращает запрашиваемые данные на текущий момент времени.
Чтобы самостоятельно указать какой-либо момент времени, на который вас интересует запрашиваемая информация, добавьте очередной параметр:

где «time» — название временного параметра, а «[val]» — значение. В значении должна быть указана дата и время в соответствии со стандартом ISO 8601. Примечание: Запросы чувствительны к регистру букв.

Укажите дату и время в значении параметра «time=[val]» в следующем формате: «ГГГГ-ММ-ДДTчч:мм:сс».
Параметр в запросе будет выглядеть так:

указана дата: 12 июля 2015 года, время: 12:00:00. Обратите внимание: символ «T», разделяющий дату и время, — латинская буква.

Вы можете обозначить тайм зону, добавив в конце значения времени аббревиатуру соответствующей тайм зоны (например, «MSK» или «Asia/Novosibirsk»).

Чтобы в качестве зоны указать UTC, в конце временного значения добавьте латинскую букву «Z».

Тайм зона также может быть задана смещением времени вперед или назад относительно UTC.

Чтобы указать временной интервал, установите начало и конец интервала во временном параметре так, как показано ниже, используя разделяющий символ «/».

где «[val1]» — начало интервала, а «[val2]» его конец.

Например:

Параметр выше обозначает временной интервал с началом, датирующимся на 12 число июля 2015 года в 12:00:00 и концом 15 июля 2015 года в 15:52:01.

Также можно задать интервал в виде «IsoTime/duration», где длительность интервала имеет вид PxxYxxMxxDTxxHxxMxxS (за префиксом P следует длительность интервала). Если задан интервал, то для параметров из группы A берется наибольшее время из этого интервала.

В таблице ниже обозначены те информационные параметры «what», которые могут использоваться только вкупе с временными интервалами:

Ответ при положительном исходе:

Каждый слой описывается следующей структурой:

Данный метод очищает слой, указанный в параметре "", и затем заполняет этот слой списком новых объектов.

Запрос:

Каждый объект имеет следующую структуру:

Ответ при положительном исходе:

В ответе порядковый номер UUID-а соответствует номеру объекта в запросе. Все запрошенные изменения применяются атомарно: или все применились, или состояние слоев не изменилось.

Аналогично "public-1.0-layer.objects.replace", но без предварительного удаления имеющихся в слое объектов.

Запрос:

Каждый объект имеет следующую структуру:

Ответ при положительном исходе:

В ответе порядковый номер UUID-а соответствует номеру объекта в запросе. Все запрошенные изменения применяются атомарно: или все применились, или состояние слоев не изменилось.

Аналогично "public-1.0-layer.objects.replace", но перечисляемые объекты, идентифицируемые по полю "uuid", уже должны существовать в слое. Указание свойств объектов, кроме "uuid", является необязательным. Неуказанные в запросе поля объекта не изменяются в диспетчерской системе.

Запрос:

Каждый объект имеет следующую структуру:

<RequestId> - уникальный ID запроса-ответа, integer.

<LangId> - код предпочтительного языка ответа, language is a lowercase, two-letter, ISO 639 language code.

<Interval> - интервал времени в секундах, integer.

<Timestamp> - количество секунд с 01.01.1970 00:00 UTC.

<Address> - массив, элементами которого являются строки, соответствующие компонентам адреса, перечисленным в поле address_fields.

<Kmh> - скорость, км/ч, float.

<Km> - расстояние, км, float.

<Litres> - объем, л, float.