> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/user/ru/guide/account/iot-logic/nodes/data-source-node.md).
# Источник данных
## Технический обзор и возможности
{% columns %}
{% column %}
**Источник данных** Узел — это точка входа для телеметрических данных от IoT-устройств и OEM-платформ в системе IoT Logic. Он работает как универсальный преобразователь: принимает данные по протоколам TCP/UDP/HTTP через сетевые интерфейсы и очереди MQTT, а затем декодирует входящие потоки данных в соответствии с выбранным протоколом. Узел преобразует сообщения устройств в стандартизированный формат, который можно дополнительно обработать в вашем потоке.
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
Помимо приема телеметрии, **Источник данных** узел также может обогащать устройство, которое вы уже добавили в него. Внешняя система, например отдельная телематическая платформа, которая по умолчанию не отправляет данные в Navixy, передает дополнительные атрибуты в поток устройства. Иногда такой внешней платформой является собственная платформа производителя устройства. Вместо переноса устройства на собственный механизм приема Navixy, **Программное обеспечение** вкладка оставляет его зарегистрированным без изменений. Она непрерывно обогащает поток устройства данными из другой платформы, так что оба потока работают параллельно. См. [Как обрабатываются отправленные данные](#how-pushed-data-is-handled) для подробностей механики, а [Параметры конфигурации](#configuration-options) чтобы настроить его.
### Интеграция в архитектуру потока
**узле «Источник данных»** служит точкой входа для данных в потоке IoT Logic. Один поток может содержать несколько узлов-источников, каждый со своей независимой конфигурацией. Эта архитектура позволяет:
* Первичное получение данных от нескольких типов устройств и протокольных форматов
* Стандартизованное преобразование данных от разных производителей в унифицированные форматы
* Параллельные пути обработки за счет подключения одного источника данных к нескольким нижестоящим узлам
* Выборочная фильтрация устройств, чтобы включить в ваш поток только релевантные источники данных
* обогащение потока для уже подключенных устройств с использованием атрибутов, передаваемых из внешней системы по HTTP
### Возможности узла
Блок **узле «Источник данных»** сам по себе предлагает:
* **Разнообразие протоколов**: Поддерживает нескольких производителей устройств, включая Teltonika, Queclink, Suntech, Jimi и других, через унаследованные парсеры и декодеры Navixy
* **Гибкость транспорта**: Поддерживает протоколы TCP, UDP, HTTP и подключения к брокеру MQTT
* **Единообразное преобразование данных**: Преобразует сообщения, специфичные для устройства, в стандартизированный формат для согласованной обработки
* **Фильтрация устройств**: Предоставляет возможности фильтрации для выбора конкретных моделей или протоколов
* **Обработка в реальном времени**: Обрабатывает входящие потоки телеметрических данных в реальном времени для немедленной обработки
* **HTTP-обогащение**: Объединяет атрибуты, передаваемые из внешней системы, в поток устройства, уже выбранного в этом узле. Сегодня поддерживается только HTTP-обогащение, а архитектура рассчитана на дальнейшее расширение
## Параметры конфигурации
{% columns %}
{% column width="58.333333333333336%" valign="middle" %}
Настройка **Источник данных** узел определяет, какие устройства отправляют данные в ваш поток, и, при необходимости, как внешняя система может обогащать эти устройства отправленными данными.
Диалог настройки разделён на две вкладки:
* **Устройства**: выбирает, какие устройства отправляют телеметрию в поток. Обязательно и работает точно так же, как раньше.
* **Программное обеспечение**: настраивает HTTP-обогащение для устройств, выбранных вами на вкладке Устройства. Необязательно и зависит от этого выбора.
{% endcolumn %}
{% column width="41.666666666666664%" %}
{% endcolumn %}
{% endcolumns %}
{% hint style="info" %}
Блок **Программное обеспечение** вкладка зависит от **Устройства** вкладки. Ее **Исходное устройство** селектор показывает только устройства, уже выбранные в **Устройства**, и не показывает доступных данных, пока вы не выберете там хотя бы одно.
{% endhint %}
Давайте рассмотрим, какие элементы использует этот узел и что вы можете настроить при работе с ним:
### Шаги настройки
{% stepper %}
{% step %}
#### Укажите имя узла
Введите описательное имя для этого источника данных:
* Используйте имя, которое поможет вам определить производителя, модели или другую релевантную информацию.
* Это имя будет отображаться на схеме потока для удобной идентификации.
{% endstep %}
{% step %}
#### Выберите источники
Из отфильтрованного списка выберите устройства, которые нужно включить. Для выбора доступны только устройства, зарегистрированные в вашей учетной записи Navixy. Этот выбор также является обязательным условием для необязательной **Программное обеспечение** вкладки, которая может сопоставлять только устройства, выбранные здесь.
{% endstep %}
{% step %}
#### Сохраните конфигурацию узла
Нажмите **Примените изменения** чтобы завершить создание узла.
{% endstep %}
{% step %}
#### Настройте HTTP-обогащение (необязательно)
Переключитесь на **Программное обеспечение** вкладку, чтобы обогатить устройства, выбранные вами на вкладке Устройства, данными, отправленными из внешней системы. Этот шаг необязателен. См. [Настройка HTTP-обогащения](#configuring-http-push-enrichment) для полной настройки.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
Если вы измените настройки производителя или модели после выбора устройств, Navixy уведомит вас, если какие-либо выбранные устройства не соответствуют новым параметрам, но не удалит их автоматически из вашего выбора.
{% endhint %}
### Настройка HTTP-обогащения
HTTP-обогащение позволяет внешней системе добавлять атрибуты к устройству, уже выбранному на вкладке этого узла **Устройства** отправляя данные на сгенерированный URL. Это необязательно и требует, чтобы сначала было выбрано как минимум одно устройство [Шаги настройки](#configuration-steps) сначала.
Это полезно, когда устройство уже передает данные в отдельную систему, которая по умолчанию не передает их в Navixy, например платформу управления батареей, отслеживающую заряд батареи того же автомобиля. Вместо переноса устройства на собственный механизм приема Navixy вы можете оставить его зарегистрированным без изменений и позволить той другой платформе отправлять сюда свои показания. Отправка с `vehicle_id: "truck_12"`, `bms_battery_soc: 76`, а также `bms_battery_temp: 34,2` добавляет `bms_battery_soc` и `bms_battery_temp` как новые атрибуты на сопоставленном устройстве, наряду с его собственной GPS-телеметрией.
{% stepper %}
{% step %}
#### Задайте тип разъема
Переключитесь на **Программное обеспечение** вкладку и задайте **Тип разъема** в **HTTP**, на данный момент это единственный вариант.
{% endstep %}
{% step %}
#### Сохраните поток и скопируйте сгенерированный URL
Сохраните весь поток, а не только этот узел. Поле **URL** генерирует значение только после сохранения потока с **Тип разъема** установлено. До этого оно показывает заполнитель с подсказкой сохранить поток. Когда URL появится, нажмите значок копирования рядом с ним; он отключён только пока поле пусто.
{% endstep %}
{% step %}
#### Аутентифицируйте внешнюю систему
Предоставьте внешней системе действительный [API-ключ Navixy](/docs/user/ru/guide/account/api-keys.md), и настройте её на отправку `Authorization: NVX ` с каждым push-запросом вместе с URL. Push-запрос без этого заголовка завершится ошибкой, поэтому до поступления данных необходимы и URL, и заголовок.
{% endstep %}
{% step %}
#### Определите первичный ключ и сопоставления
Введите **Первичный ключ**: имя поля, которое внешняя система использует для определения, какому устройству принадлежит отправленная запись. Допускается до 64 символов, только буквы, цифры и символы подчёркивания.
Добавьте одну **Сопоставления** строку на каждое устройство, которое нужно обогатить. Для каждой строки выберите **Исходное устройство**; ограничено устройствами, уже выбранными в Devices, и введите **Значение ключа** которое идентифицирует это устройство во входящих push-данных. Это поле хранит до 255 символов, но сам push-эндпоинт принимает только до 100 символов на поле, поэтому на практике значение следует держать значительно меньше 100 символов.
{% hint style="warning" %}
И Primary key, и Key value принимают только буквы, цифры и символы подчёркивания — без дефисов и другой пунктуации. Общее валидационное правило полей push-эндпоинта более permissive и допускает дефисы в любом поле без ошибок, но значение с дефисом никогда не сможет совпасть с сохранённым значением Key value, поэтому push-данные с таким значением будут незаметно отброшены точно так же, как если бы значение не совпало. Если идентификаторы вашей внешней системы используют дефисы (например `truck-12`), переведите их, например в `truck_12`, перед отправкой.
{% endhint %}
{% endstep %}
{% step %}
#### Применить и сохранить
Нажмите **Примените изменения**, затем снова сохраните поток, если вы настроили вкладку Software после первоначального сохранения.
{% endstep %}
{% endstepper %}
### Особенности обработки данных
**Узел-источник данных** наследует все парсеры и декодеры от Navixy, обеспечивая совместимость с широким спектром IoT-устройств. Когда данные поступают в этот узел, они проходят следующий процесс:
1. Входящий поток данных принимается через указанный транспортный протокол
2. Данные передаются соответствующему декодеру протокола в соответствии с вашей конфигурацией
3. Сообщения устройства преобразуются в стандартизированный формат, который может обрабатывать IoT Logic
4. Объединенные данные передаются в следующий узел в вашем потоке
Этот процесс стандартизации позволяет выстраивать единообразные потоки обработки независимо от исходного формата данных разных производителей устройств.
### Как обрабатываются отправленные данные
Navixy сопоставляет каждое входящее push-уведомление по значению его первичного ключа с настроенным Узлом **Сопоставления**, затем объединяет оставшиеся поля в поток данных сопоставленного устройства в виде атрибутов: новые, если имя поля новое, или записываются в существующую историю этого атрибута, если имя совпадает с уже существующим, независимо от того, переданы ли они самим устройством или отправлены коннектором другого потока. Они не влияют на местоположение или другие телеметрические данные. Поле, указанное в **Первичный ключ**, а также `поток_id` и `узел_id`, используется для маршрутизации и никогда не становится атрибутом само по себе. Запрос может оказаться в одном из трех состояний:
| Результат | HTTP-ответ | Данные объединены? |
| ------------------------------------------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Значение первичного ключа соответствует сопоставлению | 200, `success: true` | Да. Остальные поля объединяются как атрибуты: новый — если имя новое, существующая история — если оно совпадает с уже используемым |
| Значение первичного ключа не соответствует ни одному сопоставлению | 200, `success: true` | Нет. Отбрасывается молча |
| Отсутствует или недействителен `Authorization` заголовок | ошибка 400 | Нет. Отклоняется до того, как Navixy проверит первичный ключ |
{% hint style="info" %}
Ответ 200 только подтверждает, что Navixy приняла запрос, но не то, что данные были объединены. Несовпадающее значение первичного ключа отбрасывается молча, без ошибки, которая бы это показала. Если вы не уверены, что отправка была сопоставлена, проверьте атрибуты сопоставленного устройства в [Анализе данных](/docs/user/ru/guide/account/iot-logic/data-stream-analyzer.md) а не полагайтесь на ответ.
{% endhint %}
{% hint style="warning" %}
Имя отправленного поля использует то же пространство имён, что и собственные нативные атрибуты устройства, а также имена, отправленные коннектором другого потока, который обогащает то же устройство. Если имя совпадает с уже используемым — нативным для устройства или отправленным другим потоком, — отправка перезаписывает существующую историю этого атрибута вместо создания отдельной.
Датчики, Отчеты и Контроль событий считывают объединённое значение как реальное показание, поэтому совпадающее имя может привести к ложным данным на последующих этапах. Например, отправленное поле с именем `уровень топлива` которое совпадает с нативным атрибутом уровня топлива устройства, внесло бы ложное показание и вызвало бы ложные события падения уровня топлива или заправки в Отчетах.
Чтобы избежать этого, добавляйте префикс к именам отправляемых полей, чтобы они не могли совпасть с нативными атрибутами устройства или именами, отправленными другим потоком, например `bms_battery_soc` вместо `battery_soc`.
Поля системного сообщения, такие как `скорость`, `широта`, `долгота`, `heading`, `satellites`, а также `hdop` нельзя перезаписать таким способом. Отправки создают или обновляют только атрибуты, но не телеметрию на уровне сообщения. Отправленное поле с одним из этих имён всё равно отображается под этим именем в [Анализе данных](/docs/user/ru/guide/account/iot-logic/data-stream-analyzer.md)отдельно от реальной телеметрии устройства.
{% endhint %}
Объединённый атрибут попадает в историю атрибутов устройства как запись на определённый момент времени, а не как фиксированное текущее значение. Если устройство отправляет свою телеметрию гораздо чаще, чем внешняя система отправляет обновления, собственные пакеты устройства могут всего за секунды продвинуть историю атрибута дальше отправленного значения, даже если объединение прошло успешно.
{% hint style="info" %}
Это ожидаемое следствие того, что два потока данных работают с разной скоростью, а не дефект. Используйте атрибут на последующих этапах как `value('attribute_name', 0, 'valid')` вместо его простого имени. `'valid'` возвращается по истории атрибута до последнего ненулевого значения, чтобы последующие узлы получали отправленное значение независимо от времени.
{% endhint %}
Конечная точка push принимает не более 1 запроса в секунду на каждый API-ключ, с размером всплеска 1. Подстраивайте запросы внешней системы соответственно.
## Часто задаваемые вопросы
#### Могу ли я использовать несколько узлов «Источник данных» в одном потоке?
Да, вы можете использовать несколько **узлов-источников данных** в одном рабочем пространстве. Это полезно, когда вам нужно по-разному обрабатывать данные с устройств разных типов или объединять несколько потоков данных после определённых преобразований.
#### Что произойдёт, если устройство уже используется в другом потоке?
Устройство может одновременно принадлежать нескольким потокам. Если вы добавите устройство, которое уже используется в другом потоке, оба потока будут обрабатывать его данные одновременно, а результаты будут объединяться, чтобы избежать потери данных. Назначение другому потоку не является ограничением. Однако если коннекторы двух потоков отправят на это устройство одно и то же имя атрибута, они не объединятся безболезненно. История одной отправки перезапишет историю другой. См. [Как обрабатываются отправленные данные](#how-pushed-data-is-handled) чтобы избежать совпадающих имён.
#### Все ли мои устройства Navixy автоматически доступны в IoT Logic?
Да, все устройства из вашей учётной записи Navixy могут использоваться в обработке IoT Logic. Это включает GPS-устройства, OEM-платформы, устройства и шлюзы MQTT, а также коннекторы MQTT/Kafka. Устройство, уже выбранное в **Источник данных** узле, также может быть дополнено атрибутами, отправленными из внешней системы по HTTP, через **Программное обеспечение** вкладку.
#### Как понять, какого производителя выбрать для моих устройств?
Протокол должен соответствовать протоколу связи, используемому производителем вашего устройства. Большинство устройств используют протокол, связанный со своим производителем (например, устройства Teltonika используют протокол Teltonika). Проверьте документацию устройства или обратитесь к поставщику устройства, если вы не уверены.
#### Могу ли я подключить узел «Источник данных» к нескольким последующим узлам?
Да, вы можете подключить **узле «Источник данных»** к нескольким узлам обработки, чтобы создать параллельные пути обработки. Это позволяет применять разные преобразования к одному и тому же потоку данных. Вот пример:
#### Могу ли я получить данные из системы, которая не является устройством Navixy?
Да, через **Программное обеспечение** вкладку, но только чтобы дополнить устройство, которое вы уже добавили в **Устройства** вкладку. Это не способ создать поток без устройств в нём.
#### Система, из которой я отправляю данные, сообщает их реже, чем моё устройство, потеряются ли отправленные данные?
Нет, но отправленный атрибут может быстро перестать быть текущим значением, если устройство сообщает данные гораздо чаще, поскольку оба источника используют одну и ту же скользящую историю. Используйте атрибут на последующих этапах как `value('attribute_name', 0, 'valid')` вместо его простого имени, чтобы надежно получать последнее реальное значение независимо от времени. Это ожидаемое следствие того, что два потока работают с разной скоростью, а не дефект.
#### Я отправил данные, но они не отображаются. Что не так?
Проверьте это по порядку:
1. Убедитесь, что запрос содержал действительный `Authorization: NVX ` заголовок. Отсутствующий или недействительный заголовок вызывает явную ошибку HTTP 400.
2. Убедитесь, что имя отправленного поля точно совпадает с именем узла **Первичный ключ** точно, а его значение совпадает с одним из настроенных **Сопоставления** точно: только буквы, цифры и символы подчёркивания. Значение с дефисом — самая частая причина: оно проходит собственную проверку push-эндпоинта без ошибки, но никогда не может совпасть с сохранённым значением Key, поэтому запрос по-прежнему возвращает успех, хотя ничего не объединяется.
3. Проверьте историю атрибута в Анализ данных, а не только его текущее значение. Устройство, которое передает собственную телеметрию, часто может за несколько секунд вытеснить объединенное значение из текущего слота, хотя объединение прошло успешно.
#### Я отправил поле, и показания самого устройства выглядят неверными
Имя отправленного поля, вероятно, совпадало с системным атрибутом, который устройство уже передает, или с атрибутом, отправленным коннектором другого потока, и перезаписало его историю вместо создания отдельного атрибута. Переименуйте отправленное поле, добавив уникальный префикс, затем проверьте историю атрибута в [Анализе данных](/docs/user/ru/guide/account/iot-logic/data-stream-analyzer.md) чтобы убедиться, что отправленные и системные значения больше не смешиваются.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://navixy.com/docs/user/ru/guide/account/iot-logic/nodes/data-source-node.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.