Componentes de entrada e saída de Mapping

Do projeto à execução

Um Mapping transforma registros por meio de um grafo de componentes. As fontes produzem registros; as transformações projetam, enriquecem ou validam; os destinos gravam resultados. Uma Session associa o projeto a parâmetros, arquivos e execução. Um Workflow coordena Sessions e decisões. Essa separação permite trocar um arquivo de entrada ou um Worker sem criar outro projeto para cada variação operacional.

Os componentes de arquivo incorporados são diferentes daqueles que exigem um Worker compatível. Database, API e Object storage declaram o runtime compatible_worker; selecionar um nó não instala drivers, concede permissões nem cria uma conexão automaticamente. Consulte conectores e autenticação antes de configurar esses componentes.

Esta referência apresenta as fontes e os destinos do catálogo de Mapping. Os nomes técnicos ajudam a identificar configurações; a interface apresenta os rótulos da primeira coluna. As opções listadas pertencem ao componente genérico. A conexão e o Worker podem oferecer um subconjunto menor.

Catálogo de fontes

Arquivos delimitados e JSON

Flat File input interpreta CSV, TSV e texto delimitado. Configure o delimitador real e informe se há cabeçalho. Header row number é uma posição física contada a partir de um; não confunda um cabeçalho deslocado com linhas de dados que precisam ser preservadas. Se não houver cabeçalho, informe Field names. Header mapping relaciona posições ou cabeçalhos aos campos lógicos e seus tipos. Encoding distingue UTF-8 de UTF-8 with BOM.

JSON input aceita um array JSON ou JSON Lines. Record path localiza o array dentro de um documento; Field mapping projeta caminhos aninhados em campos lógicos. Um JSON válido pode ter uma estrutura incompatível com a coleção esperada. Comece com um documento pequeno, com quantidade conhecida de registros, e confirme que a projeção obtém os campos corretos.

Excel

Excel input oferece detecção automática, XLSX, XLSM e XLS. Read sheets permite selecionar uma planilha, uma lista, um padrão, uma expressão regular ou todas. Inclua planilhas ocultas explicitamente quando necessário. Header row number, Data starts at row, Start column e End column delimitam a região. Skip empty rows controla as linhas vazias; Include sheet name preserva a procedência no campo configurado, inicialmente _sheet_name.

A opção Password protected indica que a senha é fornecida na execução; ela não deve ser armazenada no Mapping. Ler um arquivo XLSM não autoriza a execução de macros. Antes de incluir todas as planilhas, confirme que elas têm a mesma estrutura. Uma planilha de observações ou totais pode gerar registros fora do conjunto esperado.

Fontes remotas

Database input oferece Table or view e SQL query para leitura. Selecione conexão, esquema e objeto, ou configure a consulta. Fetch size e Query timeout controlam aspectos operacionais; não substituem filtros de negócio. Selected fields permite uma projeção explícita. Use consultas de leitura sobre recursos autorizados; a existência do campo SQL não garante compatibilidade universal entre dialetos.

API input declara GET, Resource path, Record path e Field mapping. A paginação pode ser None, Page number, Offset ou Cursor. Page size, Retries e Timeout precisam ser compatíveis com o serviço. Uma primeira página correta não comprova a leitura da coleção inteira: o teste deve ultrapassar deliberadamente o tamanho de uma página.

Object storage input seleciona Connection e Object key. Os formatos declarados são CSV e JSON Lines. Selected fields e CSV delimiter completam a configuração. A chave do objeto não é um caminho local do navegador. Confira o prefixo e o recurso final para evitar a leitura de outro arquivo com nome semelhante.

Catálogo de destinos

Representação e gravação

Flat File output define nome, delimitador, cabeçalho, qualificador de texto, política de aspas, escape, fim de linha, codificação e representação de nulos. Esses parâmetros fazem parte do contrato de troca de dados. Se o consumidor exige CRLF ou BOM, registre isso antes de comparar os arquivos. JSON output distingue array de JSON Lines, oferece formatação legível e permite decidir se os campos nulos serão mantidos.

Database output declara Append, Replace e Upsert; chaves, criação de tabela, lotes, intervalo de commit e timeout completam a configuração. Confirme se o conector efetivamente oferece o modo escolhido. Teste Replace somente em uma tabela descartável. Upsert exige chaves bem definidas; não é um mecanismo genérico para corrigir duplicatas históricas.

API output declara POST, PUT e PATCH, modos Append ou Upsert, chaves e uma confirmação de unicidade imposta pelo provedor. Success status codes parte de 200, 201, 202 e 204. O código 202 pode indicar aceitação assíncrona pelo serviço externo, sem confirmar o processamento final. Avalie os reenvios em conjunto com a semântica de idempotência do destino.

Object storage output usa Conditional replace, exige Idempotency key e oferece Create only when absent, Expected ETag e Expected generation. Essas condições protegem a intenção de gravação em relação às versões do objeto. Não retire uma precondição apenas para transformar um conflito em sucesso: recupere o estado esperado e confirme se a nova gravação continua válida.

O catálogo atual de destinos de Mapping não contém um componente Excel output. Para entregar um arquivo que o Excel consiga abrir, use CSV com codificação, delimitador e fim de linha adequados. Um CSV com BOM continua sendo texto delimitado: não é um arquivo XLSX, não contém planilhas e não preserva fórmulas nem formatação de células.

Prova de conceito do contrato de arquivo

Crie um CSV sintético com o cabeçalho id,name e duas linhas: 1,Ana e 2,Luis. Projete Flat File input → Flat File output, selecione vírgula e cabeçalho nas duas pontas e associe o arquivo de entrada a uma Session. Execute em um ambiente de testes autorizado. A saída esperada mantém dois registros e dois campos; aspas e fim de linha podem variar conforme a configuração de saída.

Repita com um arquivo JSON Lines contendo dois objetos equivalentes. Use JSON input e JSON output, selecione JSON Lines e confira duas linhas de dados. Essa segunda variante separa falhas de transporte de falhas de representação. Os passos descrevem uma verificação reproduzível; registre o resultado real antes de aceitar o contrato.

Para um Mapping simples com um arquivo compatível, também é possível iniciar a execução manual em Mapping → Run e selecionar a entrada solicitada. Uma Session reutiliza bindings e configurações operacionais; ela não é um requisito universal para esse teste manual. Confira a tentativa e o arquivo real em Monitor.

Validação, falhas e recuperação

Primeiro revise a estrutura do grafo, as conexões entre nós e os campos obrigatórios. Depois verifique nomes lógicos, tipos e parâmetros. Se a leitura falhar, mantenha uma amostra sintética equivalente e reduza o problema a uma fonte e um destino. Se a gravação falhar, identifique possíveis efeitos parciais antes de tentar novamente; o erro do Workflow não comprova ausência de alterações no destino.

Use Monitor para correlacionar a execução e suas tarefas, e Sessions para conferir arquivos, perfil e Worker. Uma execução pequena valida estrutura e acesso, sem demonstrar capacidade para qualquer volume. Aumente o conjunto gradualmente e mantenha uma contagem esperada independente.