> 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 via protocolos TCP/UDP/HTTP nas interfaces de rede e por filas MQTT, e então decodificando os fluxos de dados recebidos de acordo com o protocolo selecionado. O nó transforma as mensagens dos dispositivos 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á adicionou a ele. Um sistema externo, como uma plataforma telemática separada que, por padrão, não envia dados para a Navixy, 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 **A aba Software** a mantém registrada como está. Ela enriquece continuamente o fluxo do dispositivo com dados dessa outra plataforma, de modo que ambos os fluxos rodem em paralelo. Veja [Como os dados enviados por push são tratados](#how-pushed-data-is-handled) para os detalhes de funcionamento, 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 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 as fontes de dados relevantes no seu fluxo
* Enriquecimento do fluxo para dispositivos já conectados, usando atributos enviados por um sistema externo via HTTP
### Recursos do nó
O **nó Fonte de Dados** por si só oferece:
* **Diversidade de protocolos**: Compatível com vários fabricantes de dispositivos, incluindo Teltonika, Queclink, Suntech, Jimi e outros, por meio dos analisadores e decodificadores herdados do Navixy
* **Flexibilidade de transporte**: Compatível com 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**: Trata os 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ó. Hoje, o HTTP é o único tipo de push suportado, com a arquitetura projetada para suportar outros tipos 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:
* **Dispositivos**: seleciona quais dispositivos enviam telemetria para o fluxo. Obrigatório e funciona exatamente como antes.
* **A aba Software**: configura o enriquecimento por 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 **A aba Software** depende da **Dispositivos** aba. Seu **Dispositivo de origem** seletor lista apenas os dispositivos já selecionados em **Dispositivos**, e não mostra dados disponíveis até você selecionar 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.
* Esse nome será exibido no diagrama de fluxo para fácil identificação.
{% endstep %}
{% step %}
#### Selecionar fontes
Da 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 **A aba Software** aba opcional, que só pode mapear os dispositivos selecionados aqui.
{% endstep %}
{% step %}
#### Salve a configuração do nó
Clique em **Aplicar alterações** para concluir a criação do nó.
{% endstep %}
{% step %}
#### Configurar o enriquecimento por push HTTP (opcional)
Mude para a **A aba Software** a aba para enriquecer os dispositivos que você selecionou em Devices 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 dispositivo selecionado não corresponder aos novos parâmetros, mas não o 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 **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á relata para um sistema separado que não envia dados para a Navixy por padrão, 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 do 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`, e `bms_battery_temp: 34.2` adiciona `bms_battery_soc` e `bms_battery_temp` como novos atributos no dispositivo mapeado, junto com sua telemetria nativa de GPS.
{% stepper %}
{% step %}
#### Definir o tipo de conector
Mude para a **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 o fluxo inteiro, não apenas este Nó. O **URL** campo só gera um valor depois que o fluxo for 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, que fica desativado apenas enquanto o campo estiver vazio.
{% endstep %}
{% step %}
#### Autentique o sistema externo
Forneça ao sistema externo uma [chave de API da Navixy](/docs/user/pt-br/guide/account/api-keys.md) válida e configure-o para enviar `Authorization: NVX ` com cada solicitação de push, junto 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 ser recebidos.
{% endstep %}
{% step %}
#### Definir chave primária e mapeamentos
Digite 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 a **Dispositivo de origem**, limitado 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, na prática, mantenha o valor bem abaixo de 100 caracteres.
{% 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 reclamar, mas um valor com hífens nunca pode corresponder a um Valor da chave armazenado, então pushes que o utilizem são descartados silenciosamente exatamente como se o valor não correspondesse. Se os identificadores do seu sistema externo usarem hífens (por exemplo `truck-12`), traduza-os, por exemplo, para `truck_12`, antes de fazer o push.
{% endhint %}
{% endstep %}
{% step %}
#### Aplicar e salvar
Clique em **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 analisadores e decodificadores da Navixy, proporcionando 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 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 passados para o próximo Nó no seu fluxo
Este processo de padronização permite que você crie fluxos de processamento consistentes, independentemente do formato original dos dados de diversos fabricantes de dispositivos.
### Como os dados enviados por push são tratados
Navixy faz a correspondência de cada push recebido pelo valor de sua chave primária com o configurado do Nó **Mapeamentos**, então 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 outros dados de telemetria. O campo nomeado em **Chave primária**, junto com `fluxo_id` e `id_do_nó`, é usado para roteamento e nunca se torna um atributo por si só. Uma requisição pode terminar em um dos três estados:
| Resultado | resposta HTTP | Os dados foram 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 `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 envio foi correspondido, verifique os atributos do dispositivo mapeado [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" %}
O nome de um campo enviado compartilha o mesmo 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 envio 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, portanto um nome conflitante 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 de abastecimento nos relatórios.
Para evitar isso, adicione um prefixo aos nomes dos campos enviados para que não entrem em conflito 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`, `atributos de latitude`, `e longitude`, `heading`, `satellites`, e `hdop` não podem ser sobrescritos dessa forma. Os envios apenas criam ou atualizam atributos, nunca telemetria no nível da 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, não como um valor atual fixo. Se o dispositivo reporta sua própria telemetria com muito mais frequência do que o sistema externo envia 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. Faça referência ao atributo a jusante como `value('attribute_name', 0, 'valid')` em vez de seu nome puro. `'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. Veja [Valores ausentes e encaminhamento nulo](/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 `'valid'` se compara a `'all'` em uma condição de um nó do IoT Logic.
{% endhint %}
O endpoint de envio 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 de 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á está 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. No entanto, se os conectores de dois fluxos enviarem o mesmo nome de atributo para esse dispositivo, eles não se mesclam sem conflito. O histórico de um envio sobrescreve o do outro. Veja [Como os dados enviados por push são tratados](#how-pushed-data-is-handled) para evitar nomes conflitantes.
#### Todos os meus dispositivos Navixy estão disponíveis automaticamente 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 de um sistema externo via HTTP, por meio do nó **A aba 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ó de 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 importar dados de um sistema que não seja um dispositivo Navixy?
Sim, por meio da **A aba Software** aba, mas apenas para enriquecer um dispositivo que você já adicionou na **Dispositivos** aba. Não é uma forma de criar um fluxo sem dispositivos nele.
#### O sistema do qual estou enviando dados relata com menos frequência do que meu dispositivo; os dados enviados serão perdidos?
Não, mas um atributo enviado pode deixar de ser o valor atual rapidamente se o dispositivo relatar com muito mais frequência, já que ambos os contribuintes compartilham o mesmo histórico deslizante. Faça referência ao atributo a jusante como `value('attribute_name', 0, 'valid')` em vez de seu nome simples para obter de forma confiável a última leitura real, independentemente do momento. Isso é uma consequência esperada de dois fluxos operando em velocidades diferentes, não um defeito. Veja [Como os dados enviados por push são tratados](#how-pushed-data-is-handled) e [Valores ausentes e encaminhamento nulo](/docs/user/pt-br/guide/account/iot-logic/nodes/logic-node/logic-node-expressions-and-syntax.md#missing-values-and-null-routing) para a `'valid'` vs `'all'` distinção em uma condição de nó de lógica.
#### Enviei um campo, mas ele não está aparecendo; o que há de errado?
Verifique estes itens na ordem:
1. Confirme se a solicitação incluiu um cabeçalho válido. `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 exatamente à configuração do nó **Chave primária** e se o valor dele corresponde exatamente a uma das configurações **Mapeamentos** exatamente, 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 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 o valor atual dele. Um dispositivo que relata sua própria telemetria com frequência pode deslocar um valor mesclado para fora do slot atual em segundos, mesmo que a mesclagem tenha sido bem-sucedida.
#### Enviei um campo e as leituras do próprio dispositivo parecem erradas
É provável que o nome do campo enviado correspondesse a um atributo nativo que o dispositivo já relata, ou a um enviado pelo conector de outro fluxo, e tenha sobrescrito seu histórico em vez de criar um atributo separado. Renomeie o campo enviado com um prefixo distinto e, em seguida, 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.