Saltearse al contenido
Nappai Documentation

Amazon S3

El componente Amazon S3 permite a los usuarios leer archivos y carpetas directamente desde un bucket de Amazon S3. Puedes usarlo para cargar documentos de texto, imágenes o cualquier otro tipo de archivo que esté almacenado en S3 y convertirlos en datos que el resto de tu flujo de trabajo pueda procesar.

¿Cómo funciona?

Cuando lo añades a tu dashboard, el componente se conecta a la API de Amazon S3 usando las credenciales que hayas configurado previamente en Nappai.

  • Si seleccionas un S3 Object (un archivo concreto), el componente descarga ese archivo y devuelve su contenido.
  • Si seleccionas un S3 Prefix (una carpeta), el componente recorre la carpeta y devuelve todos los archivos que coincidan con los filtros que hayas configurado (tipo de archivo, expresiones regulares, etc.).
  • Puedes decidir si quieres que el contenido de los archivos se descargue o solo la lista de archivos.
  • El componente también permite usar datos de entrada (por ejemplo, una lista de objetos que ya contienen claves de S3) para cargar múltiples archivos de forma dinámica.

Internamente, el componente utiliza las clases AsyncS3CustomDirectoryLoader, AsyncS3CustomFileLoader y AsyncS3Crawler para realizar las operaciones de lectura de forma asíncrona y con control de concurrencia, lo que garantiza que la carga sea rápida y no bloquee el resto del flujo.

Entradas

  • Data with file: Permite pasar una lista de objetos que ya contienen claves de S3. El componente leerá cada archivo indicado por la clave y lo añadirá al resultado.
  • S3 Object: Selecciona un archivo individual dentro del bucket.
  • S3 Prefix: Selecciona una carpeta dentro del bucket.
  • Always Include Regex: Expresión regular que indica archivos que siempre deben incluirse, aunque no cumplan con otros filtros.
  • S3 Session Token: Token de sesión opcional para autenticación.
  • Batch Size: Número de archivos que se procesan en cada lote cuando se recorre una carpeta.
  • Check Point Database: Nombre de la base de datos SQLite donde se guardan los archivos ya procesados, evitando volver a leerlos.
  • Check Point Database Directory: Directorio donde se almacena la base de datos de checkpoint.
  • Check Point Table: Tabla dentro de la base de datos donde se registran los archivos procesados.
  • S3 Object Key: Clave que identifica el archivo dentro del bucket cuando se usa la entrada Data with file.
  • S3 Prefix Key: Clave que identifica la carpeta dentro del bucket cuando se usa la entrada Data with file.
  • Download File content: Si está activado, el componente descargará el contenido de los archivos; si no, solo devolverá la lista de archivos.
  • File Type: Tipo de archivos que se cargarán. Puedes elegir entre all (todos) o documents (solo documentos de texto).
  • Ignore Files Regex: Expresión regular que indica archivos que deben ignorarse.
  • Max Concurrency: Máximo número de tareas concurrentes para recorrer el bucket.
  • Max Concurrency Download: Máximo número de tareas concurrentes para descargar archivos.
  • Max Depth: Profundidad máxima al recorrer carpetas dentro del bucket.
  • Crawl Only Folders: Si está activado, solo se recorrerán carpetas y no se leerán archivos.

Nota sobre credenciales
Este componente necesita una credencial de tipo AWS S3 bucket.

  1. Ve a la sección de credenciales de Nappai y crea una nueva credencial AWS S3 bucket con tu Access Key, Secret Access Key, Bucket y Region.
  2. En el componente, selecciona esa credencial en el campo Credential.
    Los campos de la credencial (Access Key, Secret Access Key, Bucket, Region) no aparecen en la lista de entradas.

Salidas

  • Data: Devuelve una lista de objetos Data que contienen el contenido de los archivos (texto, metadatos, etc.).
  • Files: Devuelve una lista de objetos Data que representan los archivos encontrados, con la opción de incluir su contenido si se activó la descarga.

Ejemplo de Uso

  1. Cargar un documento único

    • Selecciona la credencial AWS S3 bucket.
    • En S3 Object elige el archivo reports/2024/summary.pdf.
    • Deja Download File content activado.
    • Conecta la salida Data a un componente de procesamiento de texto (por ejemplo, un analizador de sentimientos).

  2. Recorrer una carpeta y obtener solo documentos de texto

    • En S3 Prefix selecciona la carpeta documents/.
    • En File Type elige documents.
    • Desactiva Download File content si solo necesitas la lista de archivos.
    • Conecta la salida Files a un componente que genere un índice o un mapa de archivos.

Componentes Relacionados

  • Text Extractor – Extrae texto de los archivos devueltos por Amazon S3.
  • File Organizer – Ordena los archivos por fecha o tipo después de haberlos cargado.
  • Data Enricher – Añade metadatos adicionales a los objetos Data obtenidos.

Consejos y Mejores Prácticas

  • Usa Checkpoint: Si trabajas con carpetas grandes, habilita los campos de checkpoint para evitar volver a procesar archivos ya leídos.
  • Controla la concurrencia: Ajusta Max Concurrency y Max Concurrency Download según la capacidad de tu entorno para evitar sobrecargar la red o el servidor.
  • Filtra con Regex: Aprovecha Always Include Regex y Ignore Files Regex para limitar la carga a los archivos realmente necesarios.
  • Evita descargar contenido innecesario: Si solo necesitas la lista de archivos, desactiva Download File content para ahorrar ancho de banda y tiempo de procesamiento.

Consideraciones de Seguridad

  • Credenciales seguras: Asegúrate de que la credencial AWS S3 bucket esté protegida y no se comparta públicamente.
  • Acceso mínimo: Otorga a la credencial solo los permisos necesarios (lectura de los buckets y objetos que realmente necesitas).
  • Registros: Si habilitas la descarga de contenido, revisa que los logs no expongan datos sensibles.