Conector S3

Descripción General

El conector S3 lee y escribe objetos JSON en AWS S3 y cualquier servicio compatible con S3 (MinIO, Ceph, Cloudflare R2, Backblaze B2).

Tipos de Conector:

• S3Reader - Sondea un prefijo de bucket y emite cada nuevo objeto como una carga
• S3Writer - Escribe cada carga como un objeto S3 con una clave basada en plantilla

Lector S3

Sondea un bucket y emite cada nuevo objeto:

{
  "type": "S3Reader",
  "config": {
    "region": "us-east-1",
    "bucket": "meddle-ingest",
    "prefix": "incoming/",
    "accessKey": "AKIAIOSFODNN7EXAMPLE",
    "secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "pollingRate": 5000
  }
}

Eliminar Después de Leer

Eliminar cada objeto una vez emitido, útil para ingesta de tipo buzón de entrada:

{
  "type": "S3Reader",
  "config": {
    "region": "eu-west-1",
    "bucket": "meddle-inbox",
    "prefix": "events/",
    "pollingRate": 10000,
    "deleteAfter": true
  }
}

Endpoint Compatible con S3 (MinIO, R2)

Define endpoint para apuntar a un servicio que no sea AWS. El direccionamiento por ruta (path-style) se habilita automáticamente cuando se define endpoint:

{
  "type": "S3Reader",
  "config": {
    "endpoint": "https://minio.example.com:9000",
    "region": "us-east-1",
    "bucket": "sensor-data",
    "prefix": "raw/",
    "accessKey": "minio_access_key",
    "secretKey": "minio_secret_key",
    "pollingRate": 5000
  }
}

Escritor S3

Escribe cada carga como un objeto nuevo usando una plantilla Go para la clave:

{
  "type": "S3Writer",
  "config": {
    "region": "us-east-1",
    "bucket": "meddle-archive",
    "keyTemplate": "events/{{.deviceId}}/{{.timestamp}}.json",
    "accessKey": "AKIAIOSFODNN7EXAMPLE",
    "secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}

Endpoint Compatible con S3

{
  "type": "S3Writer",
  "config": {
    "endpoint": "https://minio.example.com:9000",
    "region": "us-east-1",
    "bucket": "processed",
    "keyTemplate": "out/{{.line}}/{{.timestamp}}.json",
    "accessKey": "minio_access_key",
    "secretKey": "minio_secret_key",
    "contentType": "application/json"
  }
}

Parámetros de Configuración

• region: Región AWS (obligatorio tanto para lector como para escritor)
• bucket: Nombre del bucket S3 (obligatorio)
• endpoint: (Opcional) URL de endpoint personalizado para servicios compatibles con S3; habilita direccionamiento por ruta
• accessKey: (Opcional) ID de clave de acceso AWS; recurre a la cadena de credenciales por defecto de AWS cuando se omite
• secretKey: (Opcional) Clave secreta de acceso AWS
• prefix: (Lector) Prefijo de clave de objeto para filtrar listados
• pollingRate: (Lector, obligatorio) Intervalo de sondeo en milisegundos
• deleteAfter: (Lector) Eliminar cada objeto después de leerlo
• keyTemplate: (Escritor, obligatorio) Plantilla Go usada para construir la clave del objeto por cada carga
• contentType: (Escritor) Tipo MIME para los objetos escritos (por defecto: application/json)

Plantillas de Clave

El keyTemplate del escritor es una cadena de text/template de Go evaluada contra la carga. Los campos de nivel superior de la carga se referencian como {{.fieldName}}:

Plantilla	Clave resultante (carga de ejemplo)
events/{{.deviceId}}/{{.timestamp}}.json	events/sensor-42/1737036000.json
raw/{{.year}}/{{.month}}/{{.id}}.json	raw/2026/05/abc-123.json
flat-{{.id}}.json	flat-abc-123.json

Asegúrate de que cada campo referenciado en la plantilla exista en la carga, de lo contrario la plantilla generará una cadena vacía para las claves ausentes y podría provocar colisiones por sobreescritura.

Resolución de Credenciales

• Cuando tanto accessKey como secretKey están definidos, el conector usa credenciales estáticas.
• Cuando se omiten, se aplica la cadena por defecto del SDK de AWS: variables de entorno, rol de tarea EC2/ECS, perfil compartido ~/.aws/credentials, etc.

Deduplicación del Lector

El lector mantiene en memoria un conjunto de claves de objetos ya emitidos, por lo que cada objeto se procesa solo una vez por cada vida del proceso de Meddle. Combínalo con deleteAfter: true para una ingesta tipo buzón duradera entre reinicios.

Conectores Relacionados

• MongoDB - Alternativa de almacenamiento de documentos
• InfluxDB - Alternativa de almacenamiento de series temporales
• HTTP - Envía datos a APIs REST en su lugar