Componentes de entrada y salida de Mapping

Del diseño a la ejecución

Un Mapping transforma registros mediante un grafo de componentes. Las fuentes producen registros; las transformaciones proyectan, enriquecen o validan; los destinos escriben resultados. Una Session asocia el diseño a parámetros, archivos y ejecución. Un Workflow coordina Sessions y decisiones. Esta separación permite cambiar un archivo de entrada o un Worker sin convertir cada variación operativa en otro diseño.

Los componentes incorporados para archivos se distinguen de los que requieren un Worker compatible. Database, API y Object storage se declaran con runtime compatible_worker; seleccionar el nodo no instala automáticamente controladores, concede permisos ni crea una conexión. Consulte conectores y autenticación antes de configurar estos componentes.

Esta referencia enumera todas las fuentes y destinos del catálogo de Mapping. Los nombres técnicos ayudan a reconocer configuraciones; la interfaz muestra las etiquetas de la primera columna. Las opciones enumeradas son las del componente genérico. La conexión y el Worker pueden imponer un subconjunto más limitado.

Catálogo de fuentes

Archivos delimitados y JSON

Flat File input interpreta CSV, TSV y texto delimitado. Configure el delimitador real y si la primera fila contiene nombres. Header row number es una posición física que comienza en uno; no confunda una cabecera desplazada con líneas de datos que deben conservarse. Si el archivo no trae cabecera, proporcione Field names. Header mapping relaciona posiciones o encabezados con campos lógicos y tipos. Encoding distingue UTF-8 y UTF-8 with BOM.

JSON input acepta un array JSON o JSON Lines. Record path permite ubicar el array dentro de un documento; Field mapping proyecta rutas anidadas a campos lógicos. Un JSON válido puede tener una estructura incompatible con la colección esperada. Prepare primero un documento pequeño cuyo número de registros conozca y confirme que la proyección obtiene los campos correctos.

Excel

Excel input contempla detección automática, XLSX, XLSM y XLS. Read sheets permite una hoja, lista, patrón, expresión regular o todas. Configure explícitamente hojas ocultas cuando deban incluirse. Header row number, Data starts at row, Start column y End column delimitan la región. Skip empty rows controla filas vacías; Include sheet name permite conservar procedencia en el campo configurado, inicialmente _sheet_name.

La opción Password protected indica que la contraseña se aporta en ejecución; no debe almacenarse dentro del Mapping. Leer un libro XLSM no constituye una autorización para ejecutar macros. Antes de incluir todas las hojas, revise que compartan estructura. Una hoja de notas o totales puede producir registros ajenos al conjunto esperado.

Fuentes remotas

Database input ofrece Table or view y SQL query de lectura. Seleccione conexión, esquema y objeto, o configure la consulta correspondiente. Fetch size y Query timeout delimitan aspectos operativos; no reemplazan filtros de negocio. Selected fields permite una proyección explícita. Diseñe consultas de lectura para un recurso autorizado y no utilice el nombre del campo SQL como promesa de soporte universal de dialectos.

API input declara GET, Resource path, Record path y Field mapping. La paginación puede ser None, Page number, Offset o Cursor. Page size, Retries y Timeout deben ser compatibles con el servicio. Una primera página correcta no demuestra que se haya leído la colección completa: el caso de prueba debe superar deliberadamente el tamaño de página.

Object storage input selecciona Connection y Object key. Sus formatos declarados son CSV y JSON Lines. Selected fields y CSV delimiter completan la lectura. La clave del objeto no es una ruta local del navegador. Compruebe el prefijo y el recurso final para evitar leer otro archivo con nombre semejante.

Catálogo de destinos

Representación y escritura

Flat File output define nombre, delimitador, cabecera, calificador, política de comillas, escape, fin de línea, codificación y representación de nulos. Estos parámetros forman parte del contrato de intercambio. Si el consumidor requiere CRLF o BOM, declare esa expectativa antes de comparar archivos. JSON output distingue array y JSON Lines, permite formato legible y decide si conserva campos nulos.

Database output declara Append, Replace y Upsert; las claves, creación de tabla, lotes, intervalo de commit y timeout completan la configuración. Confirme que la capacidad efectiva del conector admite el modo. Replace debe probarse sólo sobre una tabla de ensayo. Upsert requiere una definición correcta de claves; no es un mecanismo genérico para reparar duplicados históricos.

API output declara POST, PUT y PATCH, modos Append o Upsert, claves y una confirmación de unicidad impuesta por el proveedor. Success status codes parte de 200, 201, 202 y 204. Un código 202 puede representar aceptación asíncrona del servicio externo: no lo convierta por documentación en confirmación de procesamiento final. Los reintentos deben evaluarse junto con la semántica de idempotencia del destino.

Object storage output usa Conditional replace, exige Idempotency key y ofrece Create only when absent, Expected ETag y Expected generation. Esas condiciones protegen la intención de escritura frente a versiones del objeto. No retire una precondición sólo para convertir un conflicto en éxito: recupere el estado esperado y decida si la nueva escritura sigue siendo válida.

POC de contrato de archivo

Cree un CSV sintético con cabecera id,name y dos filas: 1,Ana y 2,Luis. Diseñe Flat File input → Flat File output, establezca delimitador coma y cabecera en ambos extremos, y guarde una Session con ese archivo de entrada. Ejecute en un entorno de pruebas autorizado. El resultado esperado conserva dos registros y los dos campos; puede diferir en comillas o fin de línea si cambia la configuración de salida.

Repita con un JSON Lines que contenga dos objetos equivalentes. Utilice JSON input y JSON output, seleccione JSON Lines y compruebe dos líneas de datos. Esta segunda variante separa errores de transporte de errores de representación. Los pasos describen una comprobación reproducible; el administrador debe registrar su resultado real antes de aceptar el contrato.

Validación, fallos y recuperación

Revise primero estructura del grafo, conexiones de nodos y campos obligatorios. Después compruebe nombres lógicos, tipos y parámetros. Si falla la lectura, conserve una muestra sintética equivalente y reduzca el problema a una fuente y un destino. Si falla la escritura, identifique si hubo efectos parciales antes de reintentar; no deduzca ausencia de cambios sólo porque el Workflow terminó con error.

Use Monitor para correlacionar ejecución y tareas, y Sessions para verificar archivos, perfil y Worker. Una ejecución pequeña valida forma y acceso, no capacidad para un volumen arbitrario. Amplíe gradualmente el conjunto y conserve un conteo esperado independiente.