Gestione dei limiti delle risposte dell'API di esportazione dei dati

Quali sono i limiti

Alle richieste che includono un intervallo di date si applicano due tipi di limiti:

Intervallo di date massimo

Se l'intervallo di tempo tra startDateTime e endDateTime supera i sette giorni, l'API restituisce una risposta 400 con il codice di errore ERR_DATE_RANGE_EXCEEDED. Riduca l'intervallo di tempo richiesto e invii nuovamente la richiesta.

Dimensione massima della risposta

La dimensione massima supportata di un file di risposta è di 6 MB, che dovrebbe essere sufficiente a contenere i dati relativi a quasi 10.000 lavori. Qualora i dati corrispondenti a una richiesta superino la dimensione massima della risposta, l'API restituisce una risposta 413 con il codice di errore ERR_RESPONSE_LIMIT_EXCEEDED. Il corpo della risposta include un valore maxJobs che indica il limite in vigore. Per risolvere il problema, restringa l'intervallo di date, richieda un numero inferiore di stampanti, oppure faccia entrambe le cose, e invii nuovamente la richiesta.

Richieste di pianificazione volte a rimanere entro i limiti

Per progettare un'integrazione che rimanga in modo affidabile entro i limiti di risposta, si prega di tenere in considerazione i seguenti fattori:

• Volume di lavori per stampante. Una stampante ad alta produttività con alimentazione continua è in grado di produrre un numero di lavori all’ora molto superiore rispetto a una stampante a fogli singoli per piccoli volumi. Se nella vostra flotta sono presenti entrambe le tipologie, saranno le stampanti ad alto volume a determinare quanto brevi dovranno essere le vostre fasce orarie.
• Numero di stampanti per richiesta. Ogni richiesta può includere più valori di printerId. Raggruppare più stampanti in un’unica richiesta è pratico, ma ogni stampante aggiuntiva aumenta la dimensione della risposta e il rischio di superare il limite.
• Ora del giorno. Se la vostra attività opera a turni, i lavori e i cambiamenti di stato si concentrano in determinate ore. Un intervallo di 24 ore può restituire volumi molto diversi a seconda di quando iniziano e finiscono tali 24 ore.
• Tolleranza per i tentativi successivi. Se una richiesta fallisce con l'errore ERR_RESPONSE_LIMIT_EXCEEDED, la Sua integrazione deve suddividere la richiesta ed effettuare un nuovo tentativo. Progettare fin dall’inizio per finestre di dimensioni ridotte è solitamente meno complesso rispetto all’implementazione della suddivisione dinamica.

Modelli consigliati

I seguenti modelli si prestano bene agli scenari di integrazione più comuni:

Estrazione notturna per la reportistica

Esegua un lavoro pianificato una volta al giorno che richieda i dati relativi alle ultime 24 ore, una stampante alla volta. Questo modello è semplice da implementare, consente di ripetere facilmente il tentativo in caso di errore e garantisce che ogni risposta sia di dimensioni ridotte. Integri le risposte relative a ciascuna stampante nel Suo processo a valle.

Estrazione oraria per dashboard in tempo quasi reale

Eseguire un lavoro pianificato una volta all’ora che richieda, in un’unica richiesta, i dati relativi all’ora precedente per tutte le stampanti. Le finestre orarie consentono di mantenere ridotte le dimensioni delle risposte anche per le stampanti ad alto volume. Se la Sua flotta è di grandi dimensioni, richieda le stampanti in gruppi anziché tutte in una volta.

Inserimento retroattivo dei dati storici

Per alimentare un data warehouse con dati storici, proceda per iterazioni sull’intervallo di tempo in finestre di dimensioni fisse (ad esempio, sei ore per richiesta) e sulle stampanti in piccoli gruppi. Elabori una finestra alla volta e salvi i risultati prima di spostare in quella successiva. Se una finestra genera l'errore ERR_RESPONSE_LIMIT_EXCEEDED, la si dividerà in due parti e si riproverà con ciascuna delle due parti.

Stato attuale della stampante ai fini del monitoraggio

Per monitorare lo stato attuale di ogni stampante del Suo parco stampanti senza recuperare la cronologia, chiami /printer-states con currentState=true. La risposta comprende una riga per ciascun motore e non è influenzata dall'intervallo di date; pertanto, una singola richiesta può coprire l'intera flotta.

Gestione degli errori relativi al limite di risposta nella Sua integrazione

Quando riceve una risposta 413 con codice ERR_RESPONSE_LIMIT_EXCEEDED, adotti una o più delle seguenti misure prima di riprovare a inviare la richiesta:

• Riduca l'intervallo di tempo. Dividere la finestra a metà è una strategia affidabile; se la richiesta divisa a metà continua a fallire, la si divide nuovamente.
• Riduca il numero di valori di printerId presenti nella richiesta. Se una stampante è responsabile della maggior parte del volume di stampa, la richieda separatamente.
• Se la richiesta riguarda un'istantanea dello stato attuale anziché una cronologia, utilizzare currentState=true su /printer-states per evitare del tutto il volume determinato dall'intervallo di date.

Non riprovi a inviare la stessa richiesta senza modificare i parametri. L'API non restituisce risultati parziali, pertanto un nuovo tentativo senza modifiche fallirà nuovamente.