> 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/pt-br/guide/account/iot-logic/nodes/data-source-node.md).
# Fonte de Dados
O nó Fonte de Dados é o ponto de entrada do IoT Logic para a telemetria do dispositivo. Ele recebe dados via TCP, UDP, HTTP ou MQTT, os decodifica e os passa para nós subsequentes. Também pode enriquecer um dispositivo já conectado
## Visão geral técnica e capacidades
{% columns %}
{% column %}
**Fonte de Dados** o nó é um ponto de entrada para dados de telemetria de dispositivos IoT e plataformas OEM no sistema IoT Logic. Ele funciona como um tradutor universal, recebendo dados por meio dos protocolos TCP/UDP/HTTP nas interfaces de rede e por filas MQTT, depois decodificando os fluxos de dados recebidos de acordo com o protocolo selecionado. O nó transforma mensagens do dispositivo em um formato padronizado que pode ser processado posteriormente no seu fluxo.
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
Além de receber telemetria, um **Fonte de Dados** nó também pode enriquecer um dispositivo que você já tenha adicionado a ele. Um sistema externo, como uma plataforma telemática separada que não envia dados para a Navixy por padrão, envia atributos extras para o fluxo do dispositivo. Às vezes, essa plataforma externa é a própria do fabricante do dispositivo. Em vez de migrar o dispositivo para a ingestão nativa da Navixy, o **Software** a aba o mantém registrado como está. Ela enriquece continuamente o fluxo do dispositivo com dados dessa outra plataforma, então ambos os fluxos rodam em paralelo. Veja [Como os dados enviados são tratados](#how-pushed-data-is-handled) para a mecânica, e [Opções de configuração](#configuration-options) para configurá-lo.
### Integração com a arquitetura do fluxo
**nó Fonte de Dados** funciona como o ponto de entrada de dados em um fluxo do IoT Logic. Um único fluxo pode conter vários nós de origem, cada um com configurações independentes. Essa arquitetura permite:
* Aquisição inicial de dados de vários tipos de dispositivos e formatos de protocolo
* Transformação padronizada de dados de vários fabricantes em formatos unificados
* Caminhos de processamento paralelos ao conectar uma fonte de dados a vários nós subsequentes
* Filtragem seletiva de dispositivos para incluir apenas as fontes de dados relevantes no seu fluxo
* Enriquecimento do fluxo para dispositivos já conectados, usando atributos enviados por um sistema externo via HTTP
### Capacidades do nó
O **nó Fonte de Dados** por si só oferece:
* **Diversidade de protocolos**: Suporta vários fabricantes de dispositivos, incluindo Teltonika, Queclink, Suntech, Jimi e outros, por meio dos analisadores e decodificadores herdados da Navixy
* **Flexibilidade de transporte**: Aceita protocolos TCP, UDP, HTTP e conexões com broker MQTT
* **Transformação unificada de dados**: Converte mensagens específicas do dispositivo para um formato padronizado para processamento consistente
* **Filtragem de dispositivos**: Oferece recursos de filtragem para selecionar modelos ou protocolos específicos
* **Processamento em tempo real**: Trata fluxos de dados de telemetria recebidos em tempo real para processamento imediato
* **Enriquecimento via push HTTP**: Mescla atributos enviados por um sistema externo ao fluxo de um dispositivo já selecionado neste nó. HTTP é o único tipo de push suportado hoje, com a arquitetura preparada para mais no futuro
## Opções de configuração
{% columns %}
{% column width="58.333333333333336%" valign="middle" %}
Configurar um **Fonte de Dados** o nó determina quais dispositivos enviam dados para o seu fluxo e, opcionalmente, como um sistema externo pode enriquecer esses dispositivos com dados enviados.
A caixa de diálogo de configuração está organizada em duas abas:
* **Dispositivos**: seleciona quais dispositivos enviam telemetria para o fluxo. Obrigatório, e funciona exatamente como antes.
* **Software**: configura o enriquecimento via push HTTP para os dispositivos que você selecionou na aba Devices. Opcional, e depende dessa seleção.
{% endcolumn %}
{% column width="41.666666666666664%" %}
{% endcolumn %}
{% endcolumns %}
{% hint style="info" %}
O **Software** a aba depende da **Dispositivos** aba. O seu **Dispositivo de origem** seletor lista apenas os dispositivos já selecionados em **Dispositivos**, e não mostra dados disponíveis até que você selecione pelo menos um lá.
{% endhint %}
Vamos ver quais elementos este nó usa e o que você pode configurar ao trabalhar com ele:
### Etapas de configuração
{% stepper %}
{% step %}
#### Especificar o nome do nó
Insira um nome descritivo para esta fonte de dados:
* Use um nome que ajude você a identificar o fabricante, os modelos ou outras informações relevantes.
* Este nome será exibido no diagrama do fluxo para fácil identificação.
{% endstep %}
{% step %}
#### Selecionar fontes
Na lista filtrada, selecione os dispositivos a incluir. Somente dispositivos registrados na sua conta de usuário da Navixy estão disponíveis para seleção. Essa seleção também é o pré-requisito para a aba opcional **Software** que só pode mapear os dispositivos selecionados aqui.
{% endstep %}
{% step %}
#### Salvar a configuração do nó
Salvar **Aplicar alterações** para concluir a criação do nó.
{% endstep %}
{% step %}
#### Configurar enriquecimento via push HTTP (opcional)
Mude para a **Software** aba para enriquecer os dispositivos que você selecionou em Dispositivos com dados enviados por um sistema externo. Esta etapa é opcional. Veja [Configurando o enriquecimento via push HTTP](#configuring-http-push-enrichment) para a configuração completa.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
Se você alterar as configurações de fabricante ou modelo depois de selecionar dispositivos, a Navixy avisa se algum dos dispositivos selecionados não corresponder aos novos parâmetros, mas não os remove automaticamente da sua seleção.
{% endhint %}
### Configurando o enriquecimento via push HTTP
O enriquecimento via push HTTP permite que um sistema externo adicione atributos a um dispositivo já selecionado na aba deste nó **Dispositivos** aba, enviando dados para uma URL gerada. É opcional e requer pelo menos um dispositivo selecionado em [Etapas de configuração](#configuration-steps) primeiro.
Isso é útil quando um dispositivo já envia dados para um sistema separado que, por padrão, não alimenta a Navixy, por exemplo, uma plataforma de gerenciamento de baterias que monitora o nível de bateria do mesmo veículo. Em vez de migrar o dispositivo para a ingestão nativa da Navixy, você pode mantê-lo registrado como está e fazer com que essa outra plataforma envie suas leituras aqui. Um push com `vehicle_id: "truck_12"`, `bms_battery_soc: 76`{{longitude}} `bms_battery_temp: 34.2` adiciona `bms_battery_soc` Webhook `bms_battery_temp` como novos atributos no dispositivo mapeado, juntamente com sua telemetria GPS nativa.
{% stepper %}
{% step %}
#### Definir o tipo de conector
Mude para a **Software** guia e defina **Tipo de conector** para **HTTP**, atualmente a única opção.
{% endstep %}
{% step %}
#### Salve o fluxo e copie a URL gerada
Salve o fluxo inteiro, não apenas este nó. O **: a URL completa do endpoint para onde a solicitação POST é enviada, por exemplo** o campo só gera um valor depois que o fluxo é salvo com **Tipo de conector** definido. Até lá, ele mostra um espaço reservado solicitando que você salve o fluxo. Assim que a URL aparecer, clique no ícone de copiar ao lado dela, desativado apenas enquanto o campo estiver vazio.
{% endstep %}
{% step %}
#### Autentique o sistema externo
Forneça ao sistema externo uma chave de API válida da [Navixy](/docs/user/pt-br/guide/account/api-keys.md), e configure-o para enviar `Authorization: NVX ` com cada solicitação push, juntamente com a URL. Um push sem esse cabeçalho falha, portanto tanto a URL quanto o cabeçalho são necessários antes que os dados possam chegar.
{% endstep %}
{% step %}
#### Defina a chave primária e os mapeamentos
Insira um **Chave primária**: o nome do campo que o sistema externo usa para identificar a qual dispositivo pertence um registro enviado por push. Aceita até 64 caracteres, somente letras, dígitos e sublinhados.
Adicionar um **Mapeamentos** linha por dispositivo para enriquecer. Para cada linha, selecione o **Dispositivo de origem**, limitado aos dispositivos já selecionados em Dispositivos, e insira o **Valor da chave** que identifica esse dispositivo em pushes de entrada. Esse campo armazena até 255 caracteres, mas o próprio endpoint de push aceita apenas até 100 caracteres por campo, então, na prática, mantenha o valor bem abaixo de 100 caracteres.
{% hint style="warning" %}
Tanto Primary key quanto Valor da chave aceitam apenas letras, dígitos e sublinhados, sem hífens nem qualquer outra pontuação. A validação geral de campos do endpoint de push é mais permissiva e aceita hífens em qualquer campo sem reclamar, mas um valor com hífen nunca pode corresponder a um Valor da chave armazenado, então pushes que usam um são descartados silenciosamente exatamente como se o valor não correspondesse. Se os identificadores do sistema externo usarem hífens (por exemplo `caminhão-12`), traduza-os, por exemplo, para `truck_12`, antes de publicar.
{% endhint %}
{% endstep %}
{% step %}
#### Aplicar e salvar
Salvar **Aplicar alterações**, então salve o fluxo novamente se você configurou a aba Software após o salvamento inicial.
{% endstep %}
{% endstepper %}
### Especificidades do processamento de dados
**Nó de Fonte de Dados** herda todos os analisadores e decodificadores da Navixy, proporcionando compatibilidade com uma ampla gama de dispositivos IoT. Quando os dados chegam a este nó, eles passam pelo seguinte processo:
1. O fluxo de dados de entrada é recebido por meio do protocolo de transporte especificado
2. Os dados são encaminhados ao decodificador de protocolo apropriado com base na sua configuração
3. As mensagens do dispositivo são transformadas em um formato padronizado que o IoT Logic pode processar
4. Os dados unificados são encaminhados para o próximo nó no seu fluxo
Esse processo de padronização permite que você construa fluxos de processamento consistentes, independentemente do formato original dos dados de diferentes fabricantes de dispositivos.
### Como os dados enviados são tratados
Navixy corresponde cada push de entrada, pelo valor de sua chave primária, ao Nó configurado **Mapeamentos**, em seguida, mescla os campos restantes no fluxo de dados do dispositivo mapeado como atributos: novo, se o nome do campo for novo, ou gravado no histórico existente desse atributo, se o nome corresponder a um que já exista, seja reportado nativamente pelo dispositivo ou enviado pelo conector de outro fluxo. Eles não afetam a localização nem outras telemetrias. O campo nomeado em **Chave primária**, juntamente com `fluxo_id` Webhook `nó_id`, é usado para roteamento e nunca se torna um atributo em si. Uma solicitação pode terminar em um dos três estados:
| Resultado | Resposta HTTP | Dados mesclados? |
| ----------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| O valor da chave primária corresponde a um mapeamento | 200, `sucesso: true` | Sim. Os campos restantes são mesclados como atributos: novos se o nome for novo, histórico existente se corresponder a um já em uso |
| O valor da chave primária não corresponde a nenhum mapeamento | 200, `sucesso: true` | Não. Descartado silenciosamente |
| Ausente ou inválido `cabeçalho para autenticação baseada em token, por exemplo` cabeçalho | erro 400 | Não. Rejeitado antes que Navixy verifique a chave primária |
{% hint style="info" %}
Uma resposta 200 confirma apenas que Navixy aceitou a solicitação, não que os dados foram mesclados. Um valor de chave primária incompatível é descartado silenciosamente, sem nenhum erro para sinalizá-lo. Se você não tiver certeza de que um envio foi correspondido, verifique os atributos do dispositivo mapeado em [Analisador de dados](/docs/user/pt-br/guide/account/iot-logic/data-stream-analyzer.md) em vez de confiar na resposta.
{% endhint %}
{% hint style="warning" %}
Um nome de campo enviado compartilha um único espaço de nomes com os atributos nativos do próprio dispositivo e com nomes enviados pelo conector de outro fluxo que enriquece o mesmo dispositivo. Se o nome corresponder a um já em uso, seja nativo do dispositivo ou enviado por outro fluxo, o envio substitui o histórico existente desse atributo em vez de criar um separado.
Sensores, Relatórios e Alertas leem o valor mesclado como uma leitura real, de modo que um nome em conflito pode produzir dados falsos a jusante. Por exemplo, um campo enviado chamado `nível de combustível` que corresponda ao atributo nativo de combustível de um dispositivo injetaria uma leitura falsa, produzindo eventos falsos de queda de combustível ou reabastecimento em Relatórios.
Para evitar isso, adicione um prefixo aos nomes dos campos enviados para que eles não possam colidir com os atributos nativos de um dispositivo ou com nomes enviados por outro fluxo, por exemplo `bms_battery_soc` em vez de `battery_soc`.
Campos de mensagem do sistema, como `velocidade`, `latitude`, `longitude`, `rumo`, `satélites`{{longitude}} `hdop` não podem ser substituídos dessa forma. Os envios apenas criam ou atualizam atributos, nunca telemetria em nível de mensagem. Um campo enviado que use um desses nomes ainda aparece com esse nome em [Analisador de dados](/docs/user/pt-br/guide/account/iot-logic/data-stream-analyzer.md), separado da telemetria real do dispositivo.
{% endhint %}
Um atributo mesclado entra como uma entrada pontual no histórico de atributos do dispositivo, e não como um valor atual persistente. Se o dispositivo reportar sua própria telemetria com muito mais frequência do que o sistema externo enviar atualizações, os próprios pacotes do dispositivo podem avançar o histórico do atributo além do valor enviado em segundos, mesmo que a mesclagem tenha sido bem-sucedida.
{% hint style="info" %}
Isso é uma consequência esperada de dois fluxos de dados operando em velocidades diferentes, não um defeito. Referencie o atributo a jusante como `value('attribute_name', 0, 'valid')` em vez de apenas seu nome. `'válido'` volta pelo histórico do atributo até a última leitura não nula, para que os nós a jusante recebam o valor enviado independentemente do momento. Veja [Valores ausentes e roteamento de null](/docs/user/pt-br/guide/account/iot-logic/nodes/logic-node/logic-node-expressions-and-syntax.md#missing-values-and-null-routing) para ver como `'válido'` se compara a `'todos'` em uma condição de um nó de lógica.
{% endhint %}
O endpoint de envio aceita até 1 solicitação por segundo por chave de API, com tamanho de rajada de 1. Ajuste a cadência das solicitações do sistema externo de acordo.
## Perguntas frequentes
#### Posso usar múltiplos nós Fonte de Dados em um fluxo?
Sim, você pode usar vários **nós de Fonte de Dados** em um único espaço de trabalho. Isso é útil quando você precisa processar dados de diferentes tipos de dispositivos de maneiras diferentes ou deseja mesclar vários fluxos de dados após transformações específicas.
#### O que acontece se um dispositivo já estiver sendo usado em outro fluxo?
Um dispositivo pode pertencer a vários fluxos ao mesmo tempo. Se você adicionar um dispositivo que já esteja sendo usado em outro fluxo, ambos os fluxos processam seus dados simultaneamente e os resultados são mesclados para evitar perda de dados. Estar atribuído a outro fluxo não é uma restrição. Se os conectores de dois fluxos enviarem o mesmo nome de atributo para esse dispositivo, porém, eles não se mesclam sem consequências. O histórico de um envio substitui o do outro. Veja [Como os dados enviados são tratados](#how-pushed-data-is-handled) para evitar nomes em conflito.
#### Todos os meus dispositivos Navixy estão automaticamente disponíveis no IoT Logic?
Sim, todos os dispositivos da sua conta de usuário Navixy podem ser usados no processamento no IoT Logic. Isso inclui dispositivos GPS, plataformas OEM, dispositivos e gateways MQTT e conectores MQTT/Kafka. Um dispositivo já selecionado em um **Fonte de Dados** nó também pode ser enriquecido com atributos enviados de um sistema externo via HTTP, por meio do **Software** aba.
#### Como sei qual fabricante selecionar para meus dispositivos?
O protocolo deve corresponder ao protocolo de comunicação usado pelo fabricante do seu dispositivo. A maioria dos dispositivos usa um protocolo associado ao seu fabricante (por exemplo, dispositivos Teltonika usam o protocolo Teltonika). Verifique a documentação do seu dispositivo ou consulte o fornecedor do seu dispositivo se você não tiver certeza.
#### Posso conectar um nó Fonte de Dados a vários nós a jusante?
Sim, você pode conectar um **nó Fonte de Dados** a vários nós de processamento para criar caminhos de processamento paralelos. Isso permite aplicar diferentes transformações ao mesmo fluxo de dados. Aqui está um exemplo:
#### Posso trazer dados de um sistema que não seja um dispositivo Navixy?
Sim, por meio da **Software** aba, mas apenas para enriquecer um dispositivo que você já adicionou na **Dispositivos** aba. Isso não é uma forma de criar um fluxo sem dispositivos nele.
#### O sistema de origem reporta com menos frequência do que meu dispositivo; os dados enviados se perderão?
Não, mas um atributo enviado pode deixar de ser o valor atual rapidamente se o dispositivo reportar com muito mais frequência, já que ambos os contribuintes compartilham o mesmo histórico rolante. Referencie o atributo a jusante como `value('attribute_name', 0, 'valid')` em vez de seu nome bruto para obter de forma confiável a última leitura real, independentemente do momento. Isso é uma consequência esperada de dois fluxos executando em velocidades diferentes, não um defeito. Consulte [Como os dados enviados são tratados](#how-pushed-data-is-handled) Webhook [Valores ausentes e roteamento de null](/docs/user/pt-br/guide/account/iot-logic/nodes/logic-node/logic-node-expressions-and-syntax.md#missing-values-and-null-routing) para o `'válido'` vs `'todos'` a distinção em uma condição do nó de lógica.
#### Enviei dados, mas eles não aparecem; o que está errado?
Verifique estes itens nesta ordem:
1. Confirme que a solicitação incluiu um `Authorization: NVX ` cabeçalho válido. Um cabeçalho ausente ou inválido falha de forma explícita com um erro HTTP 400.
2. Confirme que o nome do campo enviado corresponde exatamente à configuração do nó **Chave primária** e que seu valor corresponde exatamente a um dos **Mapeamentos** configurados: apenas letras, dígitos e sublinhados. Um valor com hífen é a causa mais comum: ele passa pela validação do próprio endpoint de envio sem erro, mas nunca pode corresponder a um valor Key armazenado, então a solicitação ainda retorna sucesso, enquanto nada é mesclado.
3. Verifique o histórico do atributo no Analisador de dados, e não apenas seu valor atual. Um dispositivo que reporta sua própria telemetria muitas vezes pode deslocar um valor mesclado para fora do slot atual em questão de segundos, mesmo que a mesclagem tenha sido bem-sucedida.
#### Enviei um campo e as leituras do próprio dispositivo parecem incorretas
O nome do campo enviado provavelmente correspondia a um atributo nativo que o dispositivo já reporta, ou a um enviado pelo conector de outro fluxo, e sobrescreveu seu histórico em vez de criar um atributo separado. Renomeie o campo enviado com um prefixo distinto e depois verifique o histórico do atributo em [Analisador de dados](/docs/user/pt-br/guide/account/iot-logic/data-stream-analyzer.md) para confirmar que os valores enviados e nativos não estão mais misturados.
---
# 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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://navixy.com/docs/user/pt-br/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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.
.png?alt=media)
