Общее описание СПИК

Сервис Программной Интеграции и Коммуникации (далее будет использоваться аббревиатура СПИК) - API ^[1]  для интеграции с другими системами. Позволяет интегрироваться с различными учётными системами: 1С, SAP, Oracle и другими. СПИК предназначен для взаимодействия с внешними системами и построен на концепции сервис-ориентированной архитектуры (SOA).

СПИК является расширением для СКАУТ-Платформы^[2].  С помощью СПИК можно не только получать данные из системы, а также добавлять и изменять их.

СПИК позволяет:

• Авторизоваться в Системе СКАУТ. ^{Пример кода.}
• Получить доступ к Объектам Мониторинга.
• Получить Текущие данные по доступным Объектам Мониторинга.
• Получить Статистики, собираемые в системе СКАУТ.

Взаимодействие СПИК со сторонними системами осуществляется по двум протоколам:

REST^[3] –  предназначен для ведения коммуникации через стандартные HTTP запросы.

SOAP^[4] –  предназначен для получения описания сервиса (его метаданных^[5]  ) на языке WSDL^[6]   с последующей генерацией прокси-заглушки^[7].  Прокси-заглушки позволяют удаленно вызывать методы сервиса. Таким образом появляется возможность быстро создавать клиентские приложения практически на любом современном языке программирования: C#, Java, 1C и т.д.

Возможности СПИК

Сервис программной интеграции и коммуникации позволяет получать и передавать из СКАУТ-Платформы в стороннюю учётную систему:

• Информацию об объектах мониторинга;
• Онлайн данные;
• Онлайн данные с показаниями датчиков;
• Статистики по объектам мониторинга;

Кроме того, СПИК предоставляет возможность заказывать отправку отчётов по объектам мониторинга на адреса электронной почты. При этом не требуется использовать диспетчерский интерфейс СКАУТ-Платформы – СКАУТ-Студио.

Далее перечисленные возможности СПИК описаны подробнее.

Запрос объектов мониторинга

Запрос объектов мониторинга^[8]  позволяет получить список транспортных средств, доступных данному пользователю. Алгоритм запроса объектов мониторинга в СПИК:

1. Пройти авторизацию в СПИК и получить токен авторизации;^{Пример кода.}
2. Получить количество доступных объектов мониторинга;
3. Составить запрос для постраничной загрузки объектов. В запросе необходимо указать смещение и количество объектов;
4. Получить объект мониторинга, вызвав у сервиса соответствующий метод, описанный в документации по СПИК.

Пример кода, реализующего запрос объектов мониторинга доступен по ссылке.

Так же в документации по СПИК доступны описания контрактов данных отдачи объектов мониторинга и контракты данных отдачи групп объектов мониторинга.

К получаемым по объектам мониторинга данным относятся:

• Марка ТС
• Модель ТС
• Цвет
• Уникальный идентификатор компании
• Поле «Описание»
• Гаражный номер
• Название объекта мониторинга
• Часовой пояс
• Поле «Владелец»
• Питание
• Государственный регистрационный номер
• Уникальный идентификатор
• Тип ТС
• VIN-номер
• Год выпуска

Запрос онлайн данных

Чтобы сделать запрос онлайн данных^[9],  необходимо выполнить следующие действия:

1. Пройти авторизацию в системе СКАУТ (если не пройдена).^{Пример кода.}
2. Получить список идентификаторов Объектов мониторинга, по которым необходимо получить онлайн данные.
3. Сформировать запрос для подписки на получение онлайн данных и указать список идентификаторов объектов мониторинга, по которым требуется получить данные.
4. Подписаться на онлайн данные, вызвав у сервиса соответствующий метод с параметром, полученным на предыдущем шаге. При успешном выполнении сервис вернёт ответ, в котором будет находиться ключ сессии онлайн данных.
5. Получить онлайн данные по подписке. Вызвать у сервиса метод, передав в качестве параметра идентификатор сессии онлайн данных, полученной на предыдущем шаге (по полученному идентификатору подписки можно много раз получать онлайн-данные).

Пример кода, реализующего запрос онлайн данных доступен по ссылке.

Так же в документации по СПИК доступны описания контрактов онлайн-данных.

К получаемым по объектам мониторинга данным относятся:

• Id терминала
• Адрес
• Время подключения
• Дата последнего сообщения
• Дата последнего обновления навигационных данных
• Количество сообщений
• Данные телеметрии
• Корректность навигационных данных

Запрос списка онлайн данных с датчиками

Запрос онлайн данных с датчиками производится аналогично п. 2.2. В ответ на запрос так же будут получены:

К получаемым по объектам мониторинга данным относятся:

• Id терминала;
• Адрес;
• Время подключения;
• Дата последнего сообщения;
• Дата последнего обновления навигационных данных;
• Количество сообщений;
• Данные телеметрии;
• Корректность навигационных данных;

Так же в документации по СПИК доступно описание контракта онлайн-данных с датчиками.

И кроме перечисленных данных в ответе на запрос будет содержаться так называемая коллекция датчиков. Для каждого датчика в коллекции будут указаны:

• Тип датчика;
• Номер датчика;
• Значение;

Запрос построения отчета и его отправки на почтовые адреса

В СПИК предусмотрена возможность заказа отчетов на почту. Отчет может быть заказан, если пользователю доступен хотя бы один шаблон отчета. Шаблон отчета содержит настройки отчета, необходимые для его построения и отображения.

Для того, чтобы заказать отчет на почту, необходимо выполнить следующие действия:

1. Пройти авторизацию в системе СКАУТ (если не пройдена).^{Пример кода.}
2. Запросить доступные пользователю отчеты и их шаблоны (путем вызова специального метода сервиса СПИК).
3. Составить запрос на построение отчета, указав необходимые параметры.
4. Отправить запрос на построение в СПИК (необходимо вызвать метод сервиса, передав в параметр запрос на построение, созданный согласно предыдущему пункту).

Пример кода, реализующего запрос построения отчета и его отправки на почтовые адреса доступен по ссылке.

Так же в документации по СПИК доступны описания контрактов отчётов.

В качестве параметров запроса следует указать следующие данные:

• Идентификатор шаблона отчета;
• Идентификатор отчета;
• Тип объекта, по которому будет построен отчет;
• Параметр, показывающий, по одному или по нескольким объектам должен быть построен отчет;
• Идентификаторы объектов, по которым необходимо построить отчет;
• Начальная дата для построения отчета;
• Конечная дана для построения отчета;
• Адреса электронной почты, на которые будет разослан построенный отчет;
• Формат файла отчета.

Запрос статистик

1. Для того, чтобы запросить заказать отчет на почту, необходимо выполнить следующие действия:
2. Пройти авторизацию в системе СКАУТ (если не пройдена).^{Пример кода.}
3. Сформировать запрос на открытие сессии построения статистики.
4. Вызвать метод заглушки с параметром типа. Метод вернёт объект ответа на запрос, но, поскольку на начальном этапе в сессии нет ни одного запроса на построение статистики, в ответе будет только открытая сессия.
5. Следует добавить один или более запросов на построение статистики к сессии. Для этого необходимо вызвать метод в сервисе по построению конкретного вида статистик, передав ему параметры построения статистики, необходимые для ее построения. При успешном выполнении метода добавления к сессии построения статистик добавится информация о том, что будет необходимо строить данный тип статистик. В СПИК существует ограничение, заключающееся в том, что в одной сессии не может быть несколько запросов на построение одного и того же типа конкретной статистики. После того, как все запросы на построение статистик добавлены, необходимо запустить построение этих статистик, вызвав метод сервиса, принимающий в качестве параметра сессию СПИК.
6. После ожидания получения статистик произойдёт забор статистик. После запуска построения статистики можно начинать получение построенных результатов порциями. Построение статистики на сервере обычно занимает некоторое время, поэтому, если статистика еще не построена, при вызове метода получения статистики сервер вернет ответ без построенной статистики, указав при этом статус операции «Processing». Если же статистика построена, то вызов данного метода вернет описание статистики со статусом «Ok» и построенную порцию статистики. Операцию забора порций статистик следует произвести для всех статистик, которые были заказаны в предыдущем пункте.
7. Далее отправляется запрос следующей порции построения статистики. Так как статистики строятся не сразу за весь период запроса, а с разбиением по дням, то после забора статистики следует дать серверу команду приступить к построению новой порции, если текущая порция не являлась последней.
8. Для завершения построения статистик, необходимо закрыть сессию, вызвав соответствующий метод, принимающий в качестве параметра сессию СПИК.

На рисунке 1 в виде блок-схемы показано как происходит описанный выше процесс.

Рисунок 1 – Получение статистик в СПИК

Пример кода, реализующего запрос статистик доступен по ссылке.

Так же в документации по СПИК доступны описания контрактов статистик данных.

СПИК позволяет получать широкий спектр статистик из СКАУТ-Платформы, среди которых:

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

Статистика по одному датчику

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

Статистики по одному датчику можно получать целым набором датчиков.

Описание сервиса статистик по дискретным датчикам доступно по ссылке.

Статистика по расходу топлива

В этой статистике получаются:

• Суммарная статистика;
• Набор статистик по датчикам расхода топлива.

Статистика по датчику расхода топлива

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

• Номер датчика;
• Имя датчика;
• Потребление за время движения, в литрах;
• Потребление топлива за время активной работы двигателя, в литрах;
• Потребление топлива за время холостой работы двигателя, в литрах;
• Общее потребление топлива, в литрах;
• Общее потребление топлива, в килограммах;
• Точки статистики.

Статистика по заправкам и сливам топлива

Данная статистика позволяет получать следующие данные:

• Начальный объем в литрах;
• Конечный объем в литрах;
• Минимальный объем в литрах;
• Максимальный объем в литрах;
• Объем заправок в литрах;
• Объемом сливов в литрах;
• Общий расход топлива в литрах;
• Количество заправок;
• Количество сливов;
• Набор топливных событий.

Статистика по топливному событию

В рамках статистики по топливному событию можно получать:

• Период происхождения события;
• Период происхождения исходного события (для разделённых событий);
• Время совершения события;
• Тип события (Может принимать значения: заправка, слив, неизвестно);
• Начальный уровень топлива в литрах;
• Конечный уровень топлива в литрах;
• Начальный уровень топлива в литрах для исходного события (для разделённых событий);
• Конечный уровень топлива в литрах для исходного события (для разделённых событий);
• Координаты места происхождения события.

Статистика по режимам работы двигателя

Статистика по режимам работы двигателя позволяет получать данные о:

• Периодах режимов работы;
• Времени работы двигателя;
• Суммарном времени с выключенным двигателем;
• Времени активной работы двигателя;
• Времени работы на холостом ходу.

Статистика по периоду работы двигателя

В рамках статистики по отдельному периоду СПИК позволяет получать информацию о:

• Типе периода. Тип периода может принимать следующие значения:
• Unknown – Не удалось определить;
• Movement – Движение;
• TralMovement – Движение на трале;
• ActiveWorkParking – Активная работа на стоянке;
• ActiveWorkMovement – Активная работа в движении;
• Parking – Стоянка;
• IdleParking - Стоянка на холостом ходу;
• Break – Разрыв;
• NoData – Нет данных;
• Временные рамки периода;
• Состояние двигателя (включен, выключен);
• Состояние датчика активной работы (активен, неактивен);

Статистика данных по навигации прошедших предварительную проверку

Эта статистика позволяет получать данные о:

• Количестве валидных точек;
• Количестве невалидных точек;
• Точках навигации;

Точки навигации передаются набором. Каждый из элементов набора содержит следующие данные:

• Момент получения данных;
• Валидность навигационной точки;
• Навигационные данные. К ним относятся:
• Координаты (Широта и долгота);
• Высота в метрах;
• Курс (0 = North, 90 = East);
• Количество спутников;
• Скорость (Км/ч);
• Тип используемой навигационной системы (систем) (Может принимать одно из строковых значений: Unknown, Gps, Glonass, GpsGlonass, Galileo, Lbs)
• Флаг проверки корректности навигационных данных (GPS Fix от терминала).

Статистика по фильтрации навигационных данных

Статистика по фильтрации навигационных данных позволяет получать отфильтрованные точки навигации. Полученные точки содержат данные, которые описаны в предыдущем пункте.

При отправке запроса на получение статистики по фильтрации навигационных данных в СПИК следует передать Запрос построения статистики по фильтрации навигационных данных, который должен содержать:

• Сессию получения статистик;
• Настройки построения статистики по фильтрации навигационных данных:

Параметры фильтрации точек;

Параметры фильтрации отрезков пути;

• Параметры фильтрации навигационных данных:
• Флаг "Исключить валидные точки";
• Флаг "Исключить невалидные точки";
• Флаг "Исключить точки, которые не получилось провалидировать".

Статистика трека с пробегом по каждому периоду

В рамках этой статистики СПИК позволяет получать:

• Общее время в движении;
• Общее время на стоянках;
• Общее время в разрывах;
• Общая продолжительность;
• Пробег в движении, км;
• Пробег в разрывах, км;
• Общий пробег, км;
• Пробег в рабочее время, км;
• Минимальная скорость, км/ч;
• Максимальная скорость, км/ч;
• Пробеги по периодам трека, которые состоят из отдельных пробегов каждого периода и включают в себя данные о:
• Типе периода. Тип может принимать одно из строковых значений:
• Unknown – Не удалось определить;
• Movement – Движение;
• TralMovement – Движение на трале;
• ActiveWorkParking – Активная работа на стоянке;
• ctiveWorkMovement – Активная работа в движении;
• Parking – Стоянка;
• IdleParking - Стоянка на холостом ходу;
• Break – Разрыв;
• NoData – Нет данных.
• Временные рамки периода (Периоды "стыкуются" без пропусков, т.е. время начала периода совпадает со временем завершения предыдущего периода);
• Пробег в данном периоде (Вычисляется алгоритмом определения расстояния с учетом кривизны земли)
• Пробег в рабочее время, км
• Средняя скорость, км/ч
• Минимальная скорость, км/ч
• Максимальная скорость, км/ч.