> 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
## Visão geral técnica e recursos
{% 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 as mensagens do dispositivo em um formato padronizado que pode ser processado posteriormente em 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á adicionou a ele. Um sistema externo, como uma plataforma de telemetria 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 **aba Software** o mantém registrado como está. Ela enriquece continuamente o fluxo do dispositivo com dados dessa outra plataforma, de modo que ambos os fluxos operem em paralelo. Veja [Como os dados enviados por push são tratados](#how-pushed-data-is-handled) para entender os detalhes de funcionamento e [Opções de configuração](#configuration-options) para configurá-lo.
### Integração da arquitetura do fluxo
**nó Fonte de Dados** funciona como o ponto de entrada dos 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 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**: Oferece suporte a vários fabricantes de dispositivos, incluindo Teltonika, Queclink, Suntech, Jimi e outros, por meio dos analisadores e decodificadores herdados da Navixy
* **Flexibilidade de transporte**: Acomoda os protocolos TCP, UDP, HTTP e conexões com broker MQTT
* **Transformação unificada de dados**: Converte mensagens específicas de dispositivos 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**: Processa fluxos de dados de telemetria recebidos em tempo real para processamento imediato
* **Enriquecimento por push HTTP**: Mescla atributos enviados por um sistema externo ao fluxo de um dispositivo já selecionado neste nó. O HTTP é o único tipo de push suportado hoje, com a arquitetura projetada para oferecer 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 por push.
A caixa de diálogo de configuração está organizada em duas abas:
* **lista de Dispositivos**: seleciona quais dispositivos enviam telemetria para o fluxo. Obrigatório, e funciona exatamente como antes.
* **aba Software**: configura o enriquecimento por push HTTP para os dispositivos que você selecionou na aba Dispositivos. Opcional, e depende dessa seleção.
{% endcolumn %}
{% column width="41.666666666666664%" %}
{% endcolumn %}
{% endcolumns %}
{% hint style="info" %}
O **aba Software** A aba Software depende da **lista de Dispositivos** aba Dispositivos. Sua **Dispositivo de origem** seletor lista apenas os dispositivos já selecionados em **lista de Dispositivos**, e não mostra dados disponíveis até que você selecione pelo menos um ali.
{% 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 nome do nó
Digite 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.
* Esse nome será exibido no diagrama do fluxo para facilitar a identificação.
{% endstep %}
{% step %}
#### Selecionar fontes
Na lista filtrada, selecione os dispositivos a incluir. Somente os dispositivos registrados na sua conta de usuário Navixy estão disponíveis para seleção. Essa seleção também é o pré-requisito para a aba opcional **aba Software** aba, que só pode associar os dispositivos selecionados aqui.
{% endstep %}
{% step %}
#### Salvar a configuração do nó
Clique **Aplicar alterações** para concluir a criação do nó.
{% endstep %}
{% step %}
#### Configurar o enriquecimento por push HTTP (opcional)
Mude para a **aba Software** a aba para enriquecer os dispositivos que você selecionou em Dispositivos com dados enviados por um sistema externo. Esta etapa é opcional. Veja [Configurar o enriquecimento por 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 os 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 %}
### Configurar o enriquecimento por push HTTP
O enriquecimento por push HTTP permite que um sistema externo adicione atributos a um dispositivo já selecionado na **lista de 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 não alimenta a Navixy por padrão, por exemplo, uma plataforma de gerenciamento de bateria 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 para cá. Um push com `vehicle_id: "truck_12"`, `bms_battery_soc: 76`, e `bms_battery_temp: 34.2` adiciona `bms_battery_soc` e `bms_battery_temp` como novos atributos no dispositivo mapeado, juntamente com sua telemetria GPS nativa.
{% stepper %}
{% step %}
#### Defina o tipo de conector
Mude para a **aba Software** aba e defina **Tipo de conector** para **HTTP**, atualmente a única opção.
{% endstep %}
{% step %}
#### Salve o fluxo e copie a URL gerada
Salve todo o fluxo, não apenas este Nó. O **URL** o campo só gera um valor depois que o fluxo é salvo com **Tipo de conector** definido. Até lá, ele exibe um espaço reservado solicitando que você salve o fluxo. Quando 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 [chave de API 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, então tanto a URL quanto o cabeçalho são necessários antes que os dados possam chegar.
{% endstep %}
{% step %}
#### Definir chave primária e mapeamentos
Insira um **Chave primária**: o nome do campo que o sistema externo usa para identificar a qual dispositivo um registro enviado pertence. Ele aceita até 64 caracteres, somente letras, dígitos e sublinhados.
Adicionar um **Mapeamentos** linha por dispositivo a ser enriquecido. Para cada linha, selecione o **Dispositivo de origem**, limitada aos dispositivos já selecionados em Dispositivos, e insira a **Valor da chave** que identifica esse dispositivo em pushes de entrada. Este campo armazena até 255 caracteres, mas o próprio endpoint de push aceita apenas até 100 caracteres por campo, portanto mantenha o valor bem abaixo de 100 caracteres na prática.
{% hint style="warning" %}
Tanto Chave primária quanto Valor da chave aceitam apenas letras, dígitos e sublinhados, sem hífens ou qualquer outra pontuação. A validação geral de campos do endpoint de push é mais permissiva e aceita hífens em qualquer campo sem reclamação, mas um valor com hífen jamais poderá corresponder a um Valor da chave armazenado, então pushes que o utilizam são descartados silenciosamente exatamente como se o valor não correspondesse. Se os identificadores do seu sistema externo usam hífens (por exemplo `truck-12`), traduza-os, por exemplo, para `truck_12`, antes de enviar.
{% endhint %}
{% endstep %}
{% step %}
#### Aplicar e salvar
Clique **Aplicar alterações**, depois 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 parsers e decoders da Navixy, oferecendo compatibilidade com uma ampla variedade de dispositivos IoT. Quando os dados chegam a este Nó, eles passam pelo seguinte processo:
1. O fluxo de dados de entrada é recebido pelo protocolo de transporte especificado
2. Os dados são passados 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 passados para o próximo Nó em seu fluxo
Esse processo de padronização permite que você crie fluxos de processamento consistentes, independentemente do formato original dos dados de diferentes fabricantes de dispositivos.
### Como os dados enviados por push são tratados
Navixy corresponde cada push de entrada pelo valor de sua chave primária ao que foi configurado no Nó **Mapeamentos**, em seguida, mescla os campos restantes no fluxo de dados do dispositivo mapeado como atributos: novos, se o nome do campo for novo, ou gravados no histórico existente desse atributo se o nome corresponder a um que já exista, seja informado nativamente pelo dispositivo ou enviado pelo conector de outro fluxo. Eles não afetam a localização nem outra telemetria. O campo nomeado em **Chave primária**, juntamente com `fluxo_id` e `id do nó`, é usado para roteamento e nunca se torna um atributo em si. Uma solicitação pode terminar em um de 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, ou no 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 `Authorization` cabeçalho | erro 400 | Não. Rejeitado antes que a Navixy verifique a chave primária |
{% hint style="info" %}
Uma resposta 200 apenas confirma que a Navixy aceitou a solicitação, não que os dados tenham sido 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 push 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 os 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 push sobrescreve 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, então um nome em conflito pode gerar 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 conflitem com os atributos nativos de um dispositivo nem com os nomes enviados por outro fluxo, por exemplo `bms_battery_soc` value('temperature', 0, 'valid')\*1.8 + 32 `battery_soc`.
Campos de mensagem do sistema, como `velocidade`, `latitude`, `longitude`, `heading`, `satellites`, e `hdop` não podem ser sobrescritos dessa forma. Os pushes só criam ou atualizam atributos, nunca telemetria no nível da mensagem. Um campo enviado usando 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, não como um valor atual fixo. Se o dispositivo reportar sua própria telemetria com muito mais frequência do que o sistema externo envia atualizações, os pacotes do próprio dispositivo podem avançar o histórico do atributo além do valor enviado em questão de segundos, mesmo que a mesclagem tenha sido bem-sucedida.
{% hint style="info" %}
Essa é 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 usar apenas o nome dele. `'valid'` retrocede 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.
{% endhint %}
O endpoint de push aceita até 1 solicitação por segundo por chave de API, com tamanho de rajada de 1. Ajuste o ritmo das solicitações do sistema externo de acordo.
## Perguntas frequentes
#### Posso usar vários Nós Fonte de Dados em um fluxo?
Sim, você pode usar vários **nós de Fonte de Dados** em um 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á está em uso em outro fluxo, ambos os fluxos processam os dados simultaneamente e os resultados são mesclados para evitar perda de dados. Ser 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 problemas. O histórico de um envio sobrescreve o do outro. Consulte [Como os dados enviados por push são tratados](#how-pushed-data-is-handled) para evitar nomes em conflito.
#### Todos os meus dispositivos Navixy ficam automaticamente disponíveis no IoT Logic?
Sim, todos os dispositivos da sua conta de usuário Navixy podem ser usados no processamento do 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 por um sistema externo via HTTP, por meio do nó **aba Software** guia.
#### Como sei qual fabricante selecionar para os 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 fabricante (por exemplo, dispositivos Teltonika usam o protocolo Teltonika). Verifique a documentação do seu dispositivo ou consulte o fornecedor do 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** nó Fonte de Dados a vários nós de processamento para criar caminhos de processamento paralelos. Isso permite aplicar transformações diferentes ao mesmo fluxo de dados. Veja um exemplo:
#### Posso trazer dados de um sistema que não seja um dispositivo Navixy?
Sim, por meio da **aba Software** aba, mas apenas para enriquecer um dispositivo que você já adicionou na **lista de Dispositivos** aba. Isso não é uma maneira de criar um fluxo sem dispositivos nele.
#### O sistema do qual estou enviando dados gera leituras 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 rotativo. Referencie o atributo a jusante como `value('attribute_name', 0, 'valid')` em vez do nome simples dele para obter com confiabilidade a última leitura real, independentemente do momento. Isso é uma consequência esperada de dois fluxos executando em velocidades diferentes, não um defeito.
#### Enviei dados, mas eles não aparecem. O que há de errado?
Verifique estes itens em ordem:
1. Confirme se a solicitação incluiu um `Authorization: NVX ` cabeçalho. Um cabeçalho ausente ou inválido falha de forma explícita com um erro HTTP 400.
2. Confirme se o nome do campo enviado corresponde à configuração do Nó **Chave primária** exatamente, e se o valor corresponde a uma das opções configuradas **Mapeamentos** exatamente, usando apenas letras, dígitos e sublinhados. Um valor com hífen é a causa mais comum: ele passa pela validação própria do endpoint de envio sem erro, mas nunca pode corresponder a um valor de chave armazenado, então a solicitação ainda retorna sucesso enquanto nada é mesclado.
3. Verifique o histórico do atributo no Analisador de dados, não apenas o valor atual dele. Um dispositivo que relata sua própria telemetria muitas vezes pode fazer um valor mesclado sair do slot atual em 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á relata, ou a um enviado por outro conector de fluxo, e sobrescreveu seu histórico em vez de criar um atributo separado. Renomeie o campo enviado com um prefixo distinto e, então, 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 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/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 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.