Rightech IoT Core REST API

Возвращает историческую статистику подключений/сессий для одного объекта.

Действие ограничено одним объектом и доступно любому пользователю, у которого есть доступ к этому объекту — удобно для проверки истории подключений конкретного устройства (например, как часто оно выходило в сеть/пропадало из неё).

Особенности:

• параметры запроса from/to задают период времени, за который формируется отчёт.
• объект должен существовать и быть доступен вызывающему; иначе поиск завершается неудачей ещё до получения статистики.

Создаёт новый объект (экземпляр устройства/актива) из модели.

Объект — это экземпляр модели — конкретное устройство, датчик или актив, зарегистрированный на платформе. Этот эндпоинт регистрирует новый объект, привязывая его к существующей модели и присваивая ему идентичность в рамках группы.

Особенности:

• model обязателен и может быть указан либо как id модели, либо как tagname модели; модель уже должна существовать.
• если name не указано, по умолчанию используется id объекта (его id устройства), поэтому для читаемости в UI рекомендуется указывать явное name.
• если базовая модель разрешённой модели отключает валидацию id (idValidate: false), id/deviceid объекта пропускает обычную проверку формата id — полезно для моделей, чей базовый тип не соответствует стандартному формату id устройства.

Возвращает список: объекты.

Возвращает список: команды.

Создает новую запись в коллекции «команды» и возвращает добавленную запись.

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

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

Перманентно удаляет указанную запись из коллекции: команды. Это действие нельзя отменить.

Передаёт потоком необработанные пакеты телеметрии для набора объектов за временной диапазон.

Возвращает историю необработанных пакетов (данные временных рядов, отправленные устройствами) сразу для одного или нескольких объектов, передаваемую потоком непрерывного ответа, а не единой JSON-полезной нагрузкой — полезно для экспорта или анализа телеметрии по нескольким объектам без постраничной разбивки.

Особенности:

• объекты выбираются одним или несколькими параметрами запроса oid; объекты, недоступные/невидимые вызывающему, молча исключаются, а не вызывают ошибку.
• параметры запроса from/to ограничивают временной период; без них вы можете получить очень большой объём данных, так как результат ограничен 10000 пакетами на каждый запрошенный id объекта.
• ответ является потоком, а не буферизованным списком — потребляйте его как поток, а не ожидайте единый JSON-массив.

Получает один объект по его id.

Возвращает полный документ объекта — такую же запись, как возвращает список объектов, но для одного конкретного объекта. {id} может быть как Mongo id объекта, так и его id устройства (deviceid); поиск принимает обе формы.

Особенности:

• доступ ограничен организацией: пользователь может получить только объекты, принадлежащие его собственной группе/организации, или те, к которым ему явно предоставлен доступ.
• параметр запроса only можно использовать, чтобы ограничить ответ подмножеством полей.

Используйте это, чтобы изменить собственные свойства объекта (имя, конфигурацию, группу и т. д.). {id} принимает как Mongo id, так и id устройства.

Особенности:

• это частичное обновление: изменяются только поля, присутствующие в теле запроса, всё остальное остаётся как есть.
• обновляет документ объекта напрямую — это не тот эндпоинт, который следует использовать для изменения живого состояния/значения телеметрии объекта (для этого предусмотрен отдельный механизм пакетов/состояния).

Безвозвратно удаляет объект и связанные с ним данные.

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

Особенности:

• тело запроса должно включать confirm: true, иначе запрос отклоняется — это защита от случайного удаления.
• удаление выполняется как многошаговая фоновая задача (деактивация, отключение, удаление событий, удаление телеметрии, удаление объекта); если один из шагов завершается неудачей на середине, часть данных может быть уже удалена, в то время как сама запись объекта удаляется последней.
• вся телеметрия и история событий объекта удаляются вместе с ним — восстановить эти данные впоследствии невозможно.

Ищет объекты по критериям фильтрации, переданным в теле запроса вместо URL.

Это тот же механизм получения списка/поиска, что и обычный список объектов, но позволяющий отправить фильтры, meta и выбор полей only в JSON-теле, а не как параметры запроса URL. Используйте это, когда ваш фильтр слишком велик или сложен для строки запроса (например, при передаче сразу многих условий фильтрации).

Особенности:

• filter в теле преобразуется в те же параметры запроса where_*, используемые обычным эндпоинтом списка; таким образом можно фильтровать по любому полю.
• meta и only можно передать в теле, и они объединяются с любыми одноимёнными параметрами, указанными в строке запроса.
• функционально возвращает тот же вид результата, что и обычный список объектов; существует исключительно для обхода ограничений размера/сложности строки запроса.

Возвращает необработанные или обработанные пакеты данных («packets»), которые объект получал с течением времени — например, для отображения графиков истории, построения треков или экспорта в CSV/JSON/GPX. Без дополнительных параметров запроса передаёт потоком историю пакетов для запрошенного временного диапазона; с meta=bounds вместо этого возвращает только самое раннее и текущее известное состояние (min/max), что полезно для определения доступного диапазона дат перед запросом полной истории.

Особенности:

• Базовое хранилище может различаться: пакеты могут читаться из коллекций телеметрии MongoDB или из отдельного обработанного/postgres хранилища временных рядов («pgts»), в зависимости от модели объекта и параметров запроса (db, ofType).
• Параметр db=reserve может перенаправить чтение в резервное расположение хранилища вместо основного.
• meta=bounds возвращает только информацию о границах (min/max), а не полный поток пакетов — используйте это, чтобы узнать доступный диапазон запроса, а не сами данные.

Отправляет новый пакет телеметрии для объекта по обычному HTTP.

Это эндпоинт приёма по обычному HTTP для устройств, сообщающих данные напрямую через REST, а не через MQTT, CoAP, LoRaWAN или один из других поддерживаемых протоколов передачи. Тело запроса сопоставляется с аргументами модели объекта и публикуется как новый пакет состояния, так же как данные, поступающие по любому другому протоколу.

Особенности:

• Предназначен для объектов, чья модель использует базовый протокол http-ric; отправка пакетов для модели, построенной на другом протоколе, является несоответствием (эта проверка существует в коде, но в данный момент отключена).
• Если у объекта прикреплена лицензия, запрос подпадает под ограничения этой лицензии на размер пакета и частоту пакетов — слишком большие полезные нагрузки отклоняются с «Payload Too Large», а превышение дневной квоты пакетов отклоняется с «Too Many Requests».
• Каждый принятый пакет увеличивает статистику использования объекта, которая учитывается при измерении/биллинге.
• Пустые пакеты (тело, которое не сопоставляется ни с одним распознанным аргументом модели) принимаются, но фактически не публикуются.

Каждый вызов POST /objects/{id}/commands/{command} записывается; этот эндпоинт передаёт этот журнал потоком, чтобы вы могли проверить, какие команды были отправлены объекту, когда и с каким результатом. Полезно для отладки поведения устройства или проверки того, что отправленная вами команда (включая отложенные команды, поставленные в очередь, пока объект был офлайн) действительно была доставлена.

Особенности:

• Результаты можно фильтровать по временному диапазону с помощью параметров запроса, так же как и другие эндпоинты журналов/телеметрии на уровне объекта (например, packets, events).
• Ответ передаётся потоком, поэтому может эффективно возвращать большое число записей без постраничной разбивки.

Возвращает определение модели объекта, обогащённое текущими живыми значениями этого объекта.

Там где GET /models/{id} возвращает определение модели изолированно, этот эндпоинт возвращает ту же структуру модели, но с заполненным _value (и его меткой времени) для каждого аргумента из текущего состояния объекта — позволяя увидеть структуру модели и живые данные объекта в одном ответе. Сам документ объекта включён под _object.

Особенности:

• {id} должен быть действительным id объекта (24-символьный шестнадцатеричный Mongo id) — id устройства здесь не принимаются, в отличие от большинства других маршрутов /objects/{id}.
• используйте параметр запроса with, чтобы дополнительно включить дерево data модели, props или правила access, а taggedOnly — чтобы ограничить возвращаемые аргументы теми, у которых есть теги использования; по умолчанию эти дополнительные секции удаляются из ответа.
• если объект находится в режиме «processed», значения берутся из его обработанного состояния, а не из необработанного.

Возвращает записанную временную шкалу событий для одного объекта, передаваемую потоком в том виде, в каком события хранятся. Это удобный, предварительно отфильтрованный сокращённый путь к GET /events, ограниченный одним id объекта, полезный, когда вы уже знаете, каким объектом интересуетесь, и вам не нужно запрашивать данные по нескольким объектам или типам событий.

Особенности:

• Поддерживает только фильтрацию по временному диапазону (from/to); в отличие от общего эндпоинта /events, не поддерживает фильтрацию по имени события, id пользователя или повышенный уровень доступа администратора — вы всегда получаете события, видимые на обычном уровне доступа для группы объекта.
• Ответ передаётся потоком, без постраничной разбивки.

Позволяет записать пользовательское событие в временную шкалу конкретного объекта, так же как записываются встроенные события (например, поступление пакетов или запуски автоматов). Событие транслируется через поток событий системы и сохраняется, поэтому оно становится частью истории событий этого объекта и доступно всем, кто подписан на живую ленту событий. Используйте это, когда внешней интеграции или скрипту нужно зафиксировать что-то значимое для объекта вне автоматических источников событий системы.

Особенности:

• id объекта берётся из URL, а не из тела запроса — это отличается от общего POST /events, которому требуется id объекта (_oid) в теле.
• Объект должен разрешаться в контексте текущей организации/группы вызывающего, иначе вызов завершается неудачей.
• Требуется имя события, указанное как event, name или type в теле; полезная нагрузка может быть указана как data, payload или body.

Привязывает геозону к объекту, начиная отслеживание его положения относительно неё.

После привязки пакеты координат объекта проверяются на соответствие форме геозоны, и статус объекта «внутри/снаружи» относительно этой геозоны становится видимым на объекте. Вход в геозону или выход из неё вызывает встроенные события «вход в геозону» / «выход из геозоны» (или любые пользовательские события, настроенные на геозоне), которые могут использоваться как триггеры в переходах автомата.

Примечания:

• отслеживание вступает в силу только после поступления нового пакета координат объекта после привязки; ничего не оценивается ретроактивно по прошлым пакетам
• повторный вызов для уже привязанной пары объект/геозона не приводит ни к чему (не является ошибкой)
• удаление самой геозоны автоматически отвязывает её от всех объектов, к которым она была привязана

Отвязывает геозону от объекта, останавливая отслеживание его положения относительно неё.

Это отменяет действие start: объект больше не проверяется на соответствие форме геозоны, его статус «внутри/снаружи» для этой геозоны больше не отслеживается, и события входа/выхода для этой геозоны больше не будут срабатывать для этого объекта.

Примечания:

• вызов этого метода, когда объект не привязан к геозоне, не приводит ни к чему (не является ошибкой)
• это удаляет только связь между конкретным объектом и конкретной геозоной; другие объекты, привязанные к той же геозоне, не затрагиваются
• удаление самой геозоны автоматически оказывает такой же эффект на все привязанные к ней объекты

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

Модели могут иметь прикреплённые автоматы (сценарии конечного автомата), и объект наследует автоматы своей модели. Этот эндпоинт открывает потоковый ответ с текущим состоянием, логами и статусом этих автоматов по мере их выполнения на конкретном объекте — он сообщает состояние выполнения, а не определение автомата (состояния/переходы), которое является отдельным ресурсом /automatons/:id.

Примечания:

• параметр пути {automaton} позволяет отфильтровать поток до одного автомата
• по умолчанию соединение возвращает только текущий снимок; добавьте ?watch=true (или любое значение, кроме false), чтобы держать поток открытым и получать обновления по мере изменения состояния автомата
• передайте ?subscribeToEventsFor=<duration> (например, 30s, 5m), чтобы продлить/обновить TTL подписки объекта на события, пока вы наблюдаете — полезно, чтобы поддерживать активной базовую ленту событий в течение вашей сессии
• если базовый поток автомата выдаёт ошибку, эндпоинт отвечает пустым массивом, а не завершает запрос неудачей

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

Модели могут иметь прикреплённые автоматы (сценарии конечного автомата), и объект наследует автоматы своей модели. Этот эндпоинт открывает потоковый ответ с текущим состоянием, логами и статусом этих автоматов по мере их выполнения на конкретном объекте — он сообщает состояние выполнения, а не определение автомата (состояния/переходы), которое является отдельным ресурсом /automatons/:id.

Примечания:

• по умолчанию соединение возвращает только текущий снимок; добавьте ?watch=true (или любое значение, кроме false), чтобы держать поток открытым и получать обновления по мере изменения состояния автомата
• передайте ?subscribeToEventsFor=<duration> (например, 30s, 5m), чтобы продлить/обновить TTL подписки объекта на события, пока вы наблюдаете — полезно, чтобы поддерживать активной базовую ленту событий в течение вашей сессии
• если базовый поток автомата выдаёт ошибку, эндпоинт отвечает пустым массивом, а не завершает запрос неудачей

Запускает выполнение сценария автоматизации на объекте.

Используйте это, чтобы начать выполнение сценария конечного автомата (автомата) для конкретного объекта — например, чтобы запустить сценарий мониторинга или управления, когда устройство выходит в сеть. Вы можете передать vars в теле запроса, чтобы задать начальные переменные автомата.

Примечания:

• если автомат ещё не привязан к объекту, он привязывается автоматически в рамках запуска (не нужно предварительно вызывать API связей отдельно)
• некоторые автоматы построены сразу на нескольких моделях («мультимодельный» сценарий, координирующий более одного объекта вместе, например датчик и исполнительное устройство, действующие как единый логический блок). Для них объект уже должен принадлежать заранее сформированной группе объектов (по одному на каждую требуемую модель), привязанной к этому автомату — запуск завершается ошибкой «insufficient objects», если группа не заполнена, и «invalid link data», если связи объекта с автоматом не хватает идентификатора группы
• для обычных (одномодельных) автоматов требования к группировке отсутствуют — любой привязанный объект можно запустить независимо

Отправляет пользовательское событие в работающий автомат.

Сценарии автоматов реагируют на события, чтобы переходить между состояниями. Этот эндпоинт позволяет вызвать произвольное событие (с опциональной полезной нагрузкой) напрямую в конкретный экземпляр автомата, работающий на объекте, так же как это сделал бы автоматический триггер (например, порог телеметрии). Это программный эквивалент ручной генерации события для автомата, работающего на объекте.

Примечания:

• требует event (идентификатор события) в теле запроса; payload опционален и передаётся в логику перехода автомата
• автомат не обязательно должен быть запущен через ту же сессию — для генерации события требуется только то, чтобы экземпляр автомата в данный момент работал на объекте

Останавливает работающий сценарий автоматизации на объекте.

Используйте это, чтобы прекратить сценарий, ранее запущенный на объекте, например, при выводе устройства из эксплуатации или приостановке автоматического управления.

Примечания:

• по умолчанию автомат остаётся привязанным к объекту после остановки, чтобы его можно было запустить снова позже
• передайте unlink: true в теле запроса (или ?unlink=true), чтобы также удалить связь между автоматом и объектом в рамках остановки

Запускает выполнение команды, определённой в модели объекта, для этого конкретного объекта. Тело запроса передаётся как параметры команды (например, заданное значение, целевое состояние). Это API, используемый для управления устройством/объектом — например, включения реле, изменения значения конфигурации или вызова любого другого действия, предоставляемого моделью объекта.

Особенности:

• Имя команды должно существовать в модели объекта; неизвестные команды отклоняются.
• Некоторые команды помечены в модели как требующие подтверждения (confirm: true). Для них первый вызов без ?confirm=true завершается неудачей, чтобы клиент мог показать пользователю запрос на подтверждение; команда фактически выполняется только после повторения запроса с ?confirm=true. Это предназначено для команд, случайный запуск которых может иметь нежелательные последствия (например, перезагрузка или разблокировка).
• Если целевой объект офлайн, команда ставится в очередь как отложенная команда и доставляется, когда объект снова выходит в сеть, а не завершается неудачей сразу; команды в очереди, не выполненные слишком долго, отбрасываются.
• Используйте GET /objects/{id}/logs/commands, чтобы просмотреть историю команд, отправленных объекту, и их результаты.