Connettore S3

Panoramica

Il connettore S3 legge e scrive oggetti JSON su AWS S3 e qualsiasi servizio compatibile con S3 (MinIO, Ceph, Cloudflare R2, Backblaze B2).

Tipi Connettore:

• S3Reader - Effettua polling su un prefisso di bucket ed emette ogni nuovo oggetto come payload
• S3Writer - Scrive ogni payload come oggetto S3 con una chiave basata su template

S3 Reader

Effettua polling su un bucket ed emette ogni nuovo oggetto:

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

Elimina Dopo la Lettura

Rimuove ogni oggetto una volta emesso, utile per ingestione in stile inbox:

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

Endpoint Compatibile S3 (MinIO, R2)

Imposta endpoint per puntare a un servizio non AWS. L’indirizzamento path-style è abilitato automaticamente quando endpoint è impostato:

{
  "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
  }
}

S3 Writer

Scrive ogni payload come nuovo oggetto utilizzando un template Go per la chiave:

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

Endpoint Compatibile 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"
  }
}

Parametri di Configurazione

• region: Region AWS (richiesta sia per reader che writer)
• bucket: Nome del bucket S3 (richiesto)
• endpoint: (Opzionale) URL endpoint personalizzato per servizi compatibili S3; abilita indirizzamento path-style
• accessKey: (Opzionale) AWS access key ID; ricade sulla catena di credenziali AWS predefinita quando omesso
• secretKey: (Opzionale) AWS secret access key
• prefix: (Reader) Prefisso della chiave dell’oggetto per filtrare elencazioni
• pollingRate: (Reader, richiesto) Intervallo di polling in millisecondi
• deleteAfter: (Reader) Elimina ogni oggetto dopo la lettura
• keyTemplate: (Writer, richiesto) Template Go usato per costruire la chiave dell’oggetto per ogni payload
• contentType: (Writer) Tipo MIME per gli oggetti scritti (default: application/json)

Template di Chiave

Il keyTemplate del writer è una stringa Go text/template valutata contro il payload. I campi di primo livello del payload sono referenziati come {{.fieldName}}:

Template	Chiave risultante (payload di esempio)
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

Assicurati che ogni campo referenziato nel template esista nel payload, altrimenti il template renderizza una stringa vuota per le chiavi mancanti e può collidere sulla sovrascrittura.

Risoluzione delle Credenziali

• Quando sia accessKey che secretKey sono impostati, il connettore usa credenziali statiche.
• Quando omessi, si applica la catena predefinita AWS SDK: variabili d’ambiente, ruolo task EC2/ECS, profilo condiviso ~/.aws/credentials, ecc.

Deduplicazione Reader

Il reader mantiene un set in memoria delle chiavi di oggetto già emesse, in modo che ogni oggetto venga elaborato solo una volta per ciclo di vita del processo Meddle. Combina con deleteAfter: true per ingestione in stile inbox durevole attraverso riavvii.

Connettori Correlati

• MongoDB - Alternativa di archiviazione documenti
• InfluxDB - Alternativa di archiviazione time-series
• HTTP - Invia dati ad API REST invece