Controlador File Storage

Esta documentación explica la implementación del controlador File Storage y cómo los parámetros de conexión se corresponden con los campos de la interfaz de usuario en la aplicación Gigantic. El controlador lee y escribe ficheros de datos (CSV, JSON, YAML, XML, Excel, Parquet y EDI) guardados en una carpeta. La carpeta puede estar en el disco local, en un servidor remoto por SSH/SFTP, en Google Drive o en SharePoint.

File Storage aparece en el grupo Archivos y almacenamiento del selector de drivers. Los proveedores Disco local y SSH / SFTP están disponibles en el plan de licencia open source; los proveedores Google Drive y SharePoint requieren el plan Cloud.

             ┌──────────────┐
             │ File Storage │   un tap o sink = una carpeta
             └──────┬───────┘
    ┌───────────────┼───────────────┬──────────────────┐
    v               v               v                  v
Disco local    SSH / SFTP     Google Drive        SharePoint
(ruta)         (ruta remota)  (ID de carpeta)     (ID del elemento carpeta)
    │               │               │                  │
    └───────────────┴───────┬───────┴──────────────────┘
                            v
      formato según la extensión: .csv .json .yaml/.yml .xml
                                  .xlsx/.xls .parquet .edi
                            v
               un fichero (u hoja) = una entidad

File Storage frente al controlador CSV

Parámetros de Conexión

Los campos de la sección Conexión dependen del Proveedor.

Google Drive

Con Cuenta de servicio los campos de OAuth2 se ocultan y no son obligatorios. La carpeta debe estar compartida con la cuenta de servicio.

SharePoint

El controlador obtiene un token de aplicación (client credentials, scope https://graph.microsoft.com/.default) y usa Microsoft Graph, así que la app necesita permisos de Graph para leer y escribir ficheros en el sitio.

Un siteId en Parámetros personalizados sustituye al campo ID del sitio.

SSH / SFTP

El Tipo de la sección Autenticación elige cómo entra el controlador:

Si no hay clave ni contraseña, la conexión falla con SSH authentication required. Se usan todos los ficheros de la ruta remota: para usar solo algunos, indica filePattern en Parámetros personalizados.

Nombre de los archivos (solo sinks)

Variables del patrón:

Ejemplos para la entidad Filiale leída de Filiale.csv:

Un Patrón personalizado vacío se comporta como Añadir marca de tiempo.

Detalles Técnicos

Ficheros y entidades

• Cada fichero de la carpeta es una entidad. El nombre de la entidad es el nombre del fichero sin la extensión (customers.csv pasa a ser customers)
• Si dos ficheros tienen el mismo nombre con distinta extensión (customers.csv y customers.json), las dos entidades conservan la extensión en el nombre
• Solo se lee el primer nivel de la carpeta. Las subcarpetas se ignoran: usa un tap por carpeta
• Se ignoran los ficheros con extensión no admitida, sin campos o que no se pueden leer
• La descripción de la entidad es <FORMATO> file: <nombre del fichero>
• Patrón de archivos admite * (cualquier carácter salvo /) y ** (cualquier carácter)
• Las condiciones where, el límite y el offset los aplica Gigantics al leer el fichero (ver Filtros aplicados por Gigantics)

Formatos

El formato se elige por la extensión del fichero.

Notas sobre Excel:

• Los ficheros .xls binarios antiguos de Excel 97-2003 no se admiten: se ignoran con el error old binary Excel 97-2003 (.xls) files are not supported, save the file as .xlsx. Un .xls que por dentro es un libro .xlsx sí se lee
• Un libro con varias hojas da una entidad por hoja, con el nombre <fichero>.<hoja>: las hojas Customers y Orders de Report.xlsx son las entidades Report.Customers y Report.Orders. Un libro con una sola hoja es la entidad <fichero>

Mapeo de tipos Parquet al leer. Primero cuenta el tipo lógico (convertido) de la columna, así que las columnas de texto son string:

Mapeo de tipos Parquet al escribir:

Una columna con un valor que no encaja en su tipo (por ejemplo una columna number con el valor n/a) se escribe como UTF8.

Proveedores

Formato de salida

Cada entidad se escribe en el formato de su fichero de origen, con la misma extensión (las entidades Excel se escriben siempre como .xlsx). Las entidades que no vienen de un fichero (por ejemplo las tablas de un tap de base de datos) se escriben como CSV.

El botón Probar comprueba que la Ruta existe, también en un sink: un sink cuya Ruta aún no está creada falla la prueba, pero crea la Ruta al ejecutarse.

Modos de escritura

El controlador File Storage escribe un fichero por entidad y ejecución. El modo de escritura decide qué pasa con los ficheros de ejecuciones anteriores:

Con Añadir marca de tiempo y Append, cada ejecución añade un fichero nuevo. Un fichero con el mismo nombre que el nuevo se sustituye siempre, en cualquier modo.

Los lotes de escritura son de 1000 registros salvo que el job o la regla indiquen otro tamaño. Reintentar al fallar no tiene efecto en este controlador.

Opciones de Autenticación

Al cambiar el Proveedor, la autenticación vuelve a la primera opción del proveedor.

Soporte de Túnel SSH

El formulario muestra la opción ¿Habilitar SSH?, pero el controlador File Storage no usa túneles SSH. Para acceder a ficheros de un servidor remoto, usa el proveedor SSH / SFTP.

Endpoints de API Utilizados

Las conexiones File Storage se utilizan en:

• Creación de taps (descubrimiento de la fuente de datos desde ficheros)
• Creación de sinks (destino de los datos anonimizados como ficheros)
• Ejecución de pipelines (extracción y carga de datos en ficheros)

Dependencias del Controlador Node.js

Parámetros Personalizados

Los Parámetros personalizados (YAML) se combinan con la configuración del controlador, así que pueden fijar o sobrescribir cualquiera de estas claves:

# Todos los proveedores
basePath: /data/input          # Sustituye Ruta / ID de carpeta
filePattern: "*.json"          # Sustituye Patrón de archivos
providerType: local            # local, ssh, gdrive o sharepoint

# Sinks
fileNaming: custom             # timestamp, original o custom
fileNamingPattern: "{entity}_{date}{ext}"

# SSH / SFTP
sshPassword: secret            # Entrada con contraseña (o la autenticación Contraseña)
sshKeyContent: |               # Contenido de la clave privada en lugar de un fichero
  -----BEGIN OPENSSH PRIVATE KEY-----
  ...
  -----END OPENSSH PRIVATE KEY-----
sshPassphrase: secret          # Frase de paso de la clave privada

# Google Drive
serviceAccountKey: |           # Clave JSON de cuenta de servicio (o la autenticación Cuenta de servicio)
  { "type": "service_account", "client_email": "...", "private_key": "..." }

# SharePoint
siteId: contoso.sharepoint.com,guid1,guid2   # Sustituye el campo ID del sitio

Ejemplos de Configuración

SFTP con una contraseña de una variable

Proveedor SSH / SFTP, Ruta /home/data/export, Host SSH sftp.example.com, Nombre de usuario gig, autenticación Archivo de clave. La contraseña sale de la variable de Gigantics SFTP_PASSWORD, así que se indica en Parámetros personalizados en lugar del campo Contraseña:

sshPassword: $SFTP_PASSWORD

SFTP, solo los ficheros CSV

Proveedor SSH / SFTP, cualquier autenticación:

filePattern: "*.csv"

Google Drive con cuenta de servicio

Proveedor Google Drive, ID de carpeta de una carpeta compartida con la cuenta de servicio, autenticación Cuenta de servicio y la clave JSON en Clave de la cuenta de servicio:

{ "type": "service_account", "client_email": "gig@project.iam.gserviceaccount.com", "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n" }