Como o dado anda: itens, json e binário

Field Note

Terça, 10h. O fluxo busca os pedidos do dia numa API e manda um aviso no chat do time. No teste, chegou uma mensagem. Bonito. No dia seguinte, chegaram 47 mensagens iguais, uma por pedido, e o canal virou um mural de notificação. Ninguém mexeu no nó de aviso. O que mudou foi a resposta da API: no teste ela trouxe um pedido, em produção trouxe 47. O nó de aviso fez o que foi desenhado para fazer: rodou uma vez para cada item. O bug estava na cabeça de quem achou que “os pedidos” eram uma coisa só.

Conceito

Tudo que passa de um nó para o outro no n8n tem o mesmo formato. A doc oficial diz assim: os dados entre nós são um array de objetos. Cada objeto é um item. Dentro do item, os dados normais ficam na chave json. Arquivos ficam na chave binary.

Um item com um pedido fica mais ou menos assim:

[
  {
    "json": {
      "pedido": "A-1032",
      "cliente": "Ana",
      "total": 189.9
    }
  }
]

Quando tem arquivo, o item ganha a chave binary. Cada entrada traz o conteúdo em base64 no campo data, mais mimeType, fileExtension e fileName quando dá para preencher.

A regra que explica metade dos bugs: um nó que recebe vários itens executa a operação para cada um deles. A doc usa o exemplo de um nó do Trello: entraram dois itens, saíram dois cards. A exceção que você vai encontrar logo é o Code node, que por padrão roda no modo Run Once for All Items e recebe a lista inteira de uma vez.

Por isso a contagem importa. Se um HTTP Request devolve 1 item, tudo que vem depois roda uma vez. Se devolve 50, tudo que vem depois roda 50 vezes: 50 e-mails, 50 linhas na planilha, 50 chamadas para a próxima API. Às vezes você queria um resumo só. Três ferramentas mudam a contagem de propósito:

• Split Out pega um item que tem uma lista dentro e transforma cada entrada em um item próprio.
• Aggregate faz o caminho inverso: junta itens separados num item só, por campo (Individual Fields) ou com tudo (All Item Data).
• Execute Once, nas configurações do nó, faz o nó rodar uma única vez com o primeiro item que receber e ignorar o resto.

Ver o dado antes de usar o dado. No painel de entrada e saída de cada nó você escolhe entre as visões Schema, Table e JSON. A doc avisa a diferença que pega muita gente: o Schema mostra uma estrutura simplificada só do primeiro item. Table e JSON mostram o conjunto completo. Então o Schema serve para achar o nome do campo e arrastar para um parâmetro. Para saber quantos itens vieram e se todos têm o mesmo formato, olhe Table ou JSON.

Item linking: de onde veio cada item. O n8n guarda, em cada item de saída, a informação de qual item de entrada o gerou. As regras automáticas são simples: uma entrada e uma saída se ligam. Uma entrada que gera várias saídas liga todas a ela. Se a quantidade de itens bate, a ligação segue a ordem. É essa corrente que permite, lá na frente, pegar o campo de um nó anterior que corresponde ao item atual. Quando ela quebra, o erro aparece. Um exemplo clássico da doc: depois de um Aggregate ou Merge, um item de saída nasceu de vários itens de entrada, e o n8n não sabe qual deles você quer.

No meu laboratório, o nó open source que consulta CNPJ em seis APIs públicas faz uma coisa que parece detalhe e não é: devolve sempre a mesma estrutura dentro do json, não importa qual API respondeu. Razão social sempre no mesmo campo, endereço sempre no mesmo formato. Formato previsível do item é metade da confiabilidade do fluxo.

Quando usar

• Antes de ligar qualquer nó que tem efeito fora do n8n: mandar mensagem, gravar, cobrar, criar registro.
• Quando o fluxo funcionou no teste e se comportou diferente em produção.
• Quando um nó reclama de item que não existe ou de item ambíguo.
• Ao trocar a fonte de dados (outra API, outra planilha). A forma do item quase sempre muda.

Quando não usar

• Fluxo de um nó só que recebe e devolve um item fixo. Mapear itens ali é cerimônia.
• Para decidir regra de negócio. O mapa mostra a forma do dado, não se ele está certo.

Faça agora

O entregável é um Mapa dos itens de um fluxo. Use o workflow da lição anterior (Manual Trigger, HTTP Request, Edit Fields).

1. Troque a URL do HTTP Request por uma API pública que devolva uma lista. Execute o workflow com Execute workflow.
2. Abra o HTTP Request e olhe a saída nas três visões: Schema, Table e JSON. Anote quantos itens saíram e se a lista veio como vários itens ou como um item com uma lista dentro.
3. Se veio um item com uma lista dentro, adicione um Split Out depois dele, apontando Field to Split Out para o campo da lista. Execute de novo e anote a nova contagem.
4. Abra o Edit Fields. Confirme que ele rodou uma vez para cada item: a saída tem a mesma quantidade de itens que a entrada.
5. Adicione um Aggregate no fim, em All Item Data, e veja os itens virarem um item só.
6. Para cada nó, preencha uma linha do mapa: itens que entram, itens que saem, chaves principais do json, se tem binary.
7. Marque com um asterisco os nós que, em produção, teriam efeito fora do n8n. Esses são os que precisam saber exatamente quantos itens vão receber.

Armadilhas

• Confiar no Schema para contar itens. Ele mostra só o primeiro. Conte em Table ou JSON.
• Testar com um item só. O fluxo de um item esconde todos os bugs de “rodou N vezes”. Teste com pelo menos três.
• Lista dentro de um item achando que são vários itens. Os nós vão rodar uma vez, com a lista inteira num campo. Split Out resolve.
• Notificação no fim de um fluxo de 50 itens. Sem Aggregate ou Execute Once antes, são 50 notificações.
• Execute Once usado como atalho. Ele descarta os outros itens sem avisar. Use quando você quer mesmo só o primeiro.
• Juntar ramos e depois pedir o “item correspondente”. Depois de Merge ou Aggregate, o item linking pode ficar ambíguo. A lição de expressões mostra como contornar.

Material para levar

Mapa dos itens:

Workflow:
Data do teste:
Fonte de dados (URL ou serviço):

Nó 1:
  Itens que entram:
  Itens que saem:
  Chaves principais do json:
  Tem binary? (sim ou não, qual campo):
  Efeito fora do n8n? (*):

Nó 2:
  Itens que entram:
  Itens que saem:
  Chaves principais do json:
  Tem binary?:
  Efeito fora do n8n? (*):

Nó 3:
  (repita)

Onde a contagem muda e por quê:
Nós com * e quantos itens recebem no pior caso:
Precisa de Split Out, Aggregate ou Execute Once? Onde:

Regras de bolso:

Entre nós sempre passa um array de itens
Dado em json, arquivo em binary
Cada nó roda uma vez por item (o Code node é a exceção padrão)
Schema mostra o primeiro item, Table e JSON mostram todos
Split Out abre a lista, Aggregate fecha
Teste com três itens, nunca com um