Elaborazione in batch di file: gestire la concorrenza nelle API

Che cosa significa elaborazione in batch

Quando un’integrazione deve elaborare più file, «batch» può indicare modalità diverse a seconda del servizio. Non implica di per sé che tutte le richieste vengano eseguite contemporaneamente, né stabilisce come tracciare i risultati o recuperare un’attività interrotta. Conviene quindi distinguere le funzioni documentate dall’API dalle scelte progettuali dell’integrazione.

Le fonti disponibili descrivono casi specifici: la [FAQ dell’API Batch di OpenAI](https://help.openai.com/es-es/articles/9197833-batch-api-faq) indica che consente di inviare richieste per l’elaborazione asincrona; Microsoft documenta le [richieste batch per la REST/OData API di SharePoint Online](https://learn.microsoft.com/es-es/sharepoint/dev/sp-add-ins/make-batch-requests-with-the-rest-apis). Sono esempi riferiti a quelle API, non regole comuni a tutti i servizi.

• Verifica che cosa intenda per batch l’endpoint che userai.
• Distingui le modalità documentate dall’API dalle decisioni che prenderà la tua applicazione.
• Non dedurre dal termine batch un comportamento universale di concorrenza o recupero.

Progettare la concorrenza senza presumere i limiti

Le fonti qui citate non indicano un valore universale per il numero di richieste simultanee né una regola valida per scegliere un limite iniziale. Cerca nella documentazione dell’endpoint eventuali quote, limiti e indicazioni applicabili al tuo caso: le condizioni di un servizio non si trasferiscono automaticamente a un altro.

Come scelta dell’integrazione, puoi mantenere configurabile il numero di operazioni avviate contemporaneamente. Imposta tale valore in base ai vincoli documentati per l’API e rivedilo quando cambiano le condizioni del servizio o i requisiti del flusso. Questa è una scelta progettuale locale, non una capacità garantita dall’API. Verifica inoltre se dimensione del batch e numero di richieste simultanee sono concetti distinti per quell’endpoint.

• Cerca i limiti documentati per l’endpoint e per il tipo di operazione.
• Rendi la concorrenza una configurazione dell’integrazione, senza presentarla come limite o funzione dell’API.
• Non trasferire a un servizio valori o condizioni documentati per un altro.

Tracciare ogni file e il relativo esito

Per rendere gestibile un flusso con più file, l’integrazione può conservare un record locale per ciascun elemento. Come schema progettuale, associa a ogni file un riferimento riconoscibile nell’applicazione e registra le informazioni necessarie a distinguere le operazioni avviate, completate o ancora da verificare, insieme al risultato o all’errore disponibile.

Questi stati locali non sono stati dell’API, a meno che il fornitore non li documenti. Se il servizio restituisce un identificativo o offre una funzione per consultare lo stato, segui le istruzioni specifiche dell’endpoint e conserva il collegamento tra il record locale e le informazioni restituite. Le fonti citate non definiscono un modello di stato comune.

• Mantieni separati il tracciamento locale e gli identificativi o stati restituiti dall’API.
• Registra l’esito per singolo file per poter distinguere gli elementi completati da quelli da verificare.
• Non presentare gli stati scelti dall’applicazione come funzionalità del fornitore.

Gestire errori e nuovi tentativi

Le fonti disponibili non stabiliscono una politica generale per classificare gli errori o ripetere le richieste. Nell’integrazione, distingui gli esiti noti da quelli incerti e annota l’errore restituito, se disponibile. Prima di ritentare, verifica nella documentazione dell’endpoint se l’operazione può essere ripetuta e a quali condizioni: un timeout o una risposta tardiva, da soli, non dimostrano che la richiesta non sia stata elaborata.

Puoi definire una strategia locale per gestire gli errori, ma non descriverla come comportamento garantito dall’API. Se la documentazione non chiarisce come comportarsi in caso di esito incerto, non presumere che inviare di nuovo la richiesta sia sempre sicuro; individua una procedura di verifica compatibile con le funzioni effettivamente documentate.

• Verifica se la documentazione consente nuovi tentativi e specifica le relative condizioni.
• Distingui un errore con esito noto da un’operazione il cui completamento non è confermato.
• Non presumere che un timeout significhi che la richiesta non sia stata elaborata.

Riprendere il lavoro dopo un’interruzione

Le fonti disponibili non descrivono una procedura universale per riprendere un batch interrotto. Un tracciamento locale per file può aiutare l’integrazione a individuare le operazioni da verificare, ma non basta da solo a stabilire che cosa sia accaduto sul servizio remoto. Prima di riprendere, consulta le eventuali funzioni documentate per controllare lo stato o identificare le richieste già elaborate.

Se l’esito di una richiesta è incerto, non trattarla automaticamente come mai avviata: verifica il comportamento previsto dall’API prima di inviarla di nuovo. Apification consente di consultare la cronologia degli elementi in Cloud, scaricare versioni precedenti e ripristinare i contenuti. Queste funzioni riguardano la cronologia dei contenuti in Cloud e non sostituiscono il monitoraggio o il recupero di un batch su un’API esterna.

• Usa il tracciamento locale per individuare gli elementi che richiedono una verifica.
• Riprendi o ritenta solo secondo le indicazioni documentate dal servizio.
• Non confondere il recupero della cronologia dei contenuti con quello delle richieste API.

Checklist per l’integrazione

Prima di mettere in uso un flusso batch, documenta che cosa viene inviato, come si riceve il risultato e quali limiti, identificativi, stati o condizioni di ripetizione sono specificati per l’endpoint. Definisci poi le scelte locali: concorrenza configurabile, tracciamento per file e gestione degli esiti incerti. Mantieni chiara la distinzione tra queste decisioni e le capacità confermate dal fornitore.

Apification consente di integrare Cloud e i suoi servizi tramite REST API, OpenAPI e webhook. La disponibilità di questi strumenti non implica che tutti i servizi condividano le stesse operazioni, condizioni o modalità di recupero: consulta la documentazione pertinente per ciascun servizio.

• Conferma dalla documentazione le operazioni e le risposte dell’endpoint.
• Progetta separatamente concorrenza, tracciamento per file e gestione degli errori nell’integrazione.
• Segnala come non specificati i comportamenti che le fonti non chiariscono.

Domande frequenti