Monitorare il Progresso del Caricamento con le Sottoscrizioni

Dopo aver caricato un file nell'URL pre-firmato di S3, la piattaforma continua a processarlo in modalità asincrona.

Usa subscribeUserFeed per ricevere eventi di caricamento in tempo reale invece di fare polling.

Alternativa più semplice

Se non hai bisogno di eventi in tempo reale, puoi fare polling sul campo fileUploaded del template finché non restituisce true.

Per lo schema generale degli eventi, consulta Formato Evento Sottoscrizione.

Feed e Categoria

Gli eventi di caricamento vengono consegnati su:

• subscribeUserFeed

Usano:

• category: "upload"

Nomi degli Eventi

Il processo di caricamento emette una sequenza di eventi, ad esempio:

• uploadScanned
• uploadTypeChecked
• uploadConverting
• uploadFlattened
• uploadTagsParsed
• uploadPdfMetaExtracted
• uploadCompleted
• uploadFailed

Payload dell'Evento di Caricamento

I payload di caricamento usano questa forma base:

{
  "version": "1.0",
  "eventId": "evt...",
  "timestamp": "2026-04-24T10:38:36.822Z",
  "level": "INFO",
  "event": "uploadCompleted",
  "category": "upload",
  "groupId": null,
  "userId": "usr...",
  "requestId": null,
  "batchId": null,
  "error": null,
  "data": {
    "id": "tmp...",
    "key": "upload/usr.../tmp....pdf",
    "code": "UPLOADOK"
  }
}

data.code conserva il codice di processo a basso livello durante la migrazione e la compatibilità.

Operazione di Sottoscrizione

subscription SubscribeUserFeed {
  subscribeUserFeed {
    userId
    data
  }
}

Esempio JavaScript

const parseEnvelope = (payload) => {
  const raw = payload?.data;
  if (!raw) return null;
  return typeof raw === 'string' ? JSON.parse(raw) : raw;
};

const handleUserFeed = ({ data }) => {
  const wrapper = data?.subscribeUserFeed;
  const event = parseEnvelope(wrapper);

  if (event?.category !== 'upload') return;

  switch (event.event) {
    case 'uploadCompleted':
      console.log('upload complete', event.data.id, event.data.key);
      break;
    case 'uploadFailed':
      console.error('upload failed', event.data.code, event.data.key);
      break;
    default:
      console.log('upload progress', event.event, event.data.code);
  }
};

Quando Usare Questo

Questo è più utile quando vuoi:

• mostrare un pannello di avanzamento o una timeline dello stato di caricamento
• rilevare errori di validazione asincrona dopo che il PUT su S3 è riuscito
• reagire immediatamente quando un template o un asset caricato è pronto