Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Comportamento di ripetizione

Quando una richiesta a un Servizio AWS non riesce a causa di un errore temporaneo o di una limitazione, l'SDK può riprovare automaticamente la richiesta. Questa pagina spiega come configurare i nuovi tentativi e come funzionano internamente.

Configurazione dei tentativi

Sei tu a controllare la strategia di riprova utilizzata dall'SDK e quante volte riprova.

Scelta di una modalità di nuovo tentativo

La modalità di riprova determina il comportamento dell'SDK quando una richiesta fallisce. Sono disponibili tre modalità: standard, adattiva e legacy.

Modalità standard (impostazione predefinita)

La modalità standard ritenta le richieste non riuscite utilizzando un backoff esponenziale con jitter. Utilizza ritardi più brevi per errori transitori (come i timeout di rete) e ritardi più lunghi per errori di limitazione (come). ThrottlingException

La modalità standard include una quota di tentativi, un bucket di token che detrae i token per ogni nuovo tentativo e rifornisce i token quando le richieste hanno esito positivo. Quando i token disponibili sono esauriti, l'SDK restituisce l'errore senza riprovare, in modo che l'applicazione fallisca rapidamente anziché attendere i nuovi tentativi che difficilmente avranno successo. Ciò aiuta anche a risolvere più rapidamente le interruzioni del servizio riducendo il traffico di nuovi tentativi. Durante il normale funzionamento, la quota rimane piena e non ha alcun effetto. La quota di tentativi non ritarda né blocca mai la richiesta iniziale. Sono interessati solo i nuovi tentativi. Per informazioni dettagliate, vedi Riprova la quota (token bucket).

Utilizzate la modalità standard a meno che non abbiate un motivo specifico per scegliere un'altra modalità.

Modalità adattiva

La modalità adattiva include tutto ciò che è in modalità standard, oltre a un limitatore di velocità lato client. Il limitatore di velocità tiene traccia delle risposte di limitazione e regola la velocità con cui l'SDK invia le richieste. A differenza della modalità standard, la modalità adattiva può ritardare o bloccare la richiesta iniziale, non solo i nuovi tentativi, quando viene rilevata una limitazione.

Il limitatore di velocità funziona per istanza del client SDK. Tutte le richieste di un client condividono lo stesso limite di velocità, indipendentemente dall'operazione o dalla risorsa API a cui sono destinate.

Quando utilizzare la modalità adattiva:

Quando non utilizzare la modalità adattiva:

La modalità adattiva non è consigliata come impostazione generale.

modalità Legacy

La modalità Legacy è il comportamento di riprova utilizzato da ciascun SDK prima dell'introduzione della modalità standard. Non include una quota di tentativi standardizzata. Alcuni SDK (come Java) avevano implementazioni proprie per le quote di tentativi in modalità legacy, ma il comportamento non è coerente tra gli SDK. Senza una quota standardizzata, un cliente continua a riprovare a pieno ritmo durante le interruzioni del servizio. Ciò blocca i thread e le connessioni alle richieste che difficilmente avranno successo, aggiungendo al contempo un carico che può ritardare il ripristino del servizio.

La modalità Legacy varia a seconda degli SDK. Il numero di tentativi, la tempistica di backoff, i set di errori riutilizzabili e il comportamento di limitazione differiscono tra le lingue. Il codice che dipende dal comportamento dei tentativi precedenti può comportarsi in modo diverso quando viene spostato tra gli SDK.

Disponibile in: Java, Python, Ruby, PHP, C++, CLI

Non disponibile in: .NET, Go, Kotlin, Rust, Swift, JavaScript

La modalità Legacy esiste per la compatibilità con le versioni precedenti. Se attualmente utilizzi la modalità legacy, passa alla modalità standard.

Riprova le impostazioni

Le seguenti impostazioni controllano il comportamento dei nuovi tentativi. È possibile impostarle tramite variabili di ambiente, il file di configurazione condiviso (~/.aws/config) o la configurazione del client nel codice.

Un valore massimo di tentativi 3 indica che l'SDK effettua una richiesta iniziale e fino a due tentativi. Imposta il numero massimo di tentativi per 1 disabilitare completamente i tentativi.

Precedenza di configurazione

Quando specificate la stessa impostazione in più punti, l'SDK risolve il valore utilizzando la seguente precedenza, dalla più alta alla più bassa:

Ciò segue la precedenza di configurazione AWS SDK standard. Un valore impostato a un livello superiore ha sempre la precedenza su un valore impostato a un livello inferiore. Ad esempio, se si imposta AWS_RETRY_MODE=adaptive come variabile di ambiente e retry_mode=standard in~/.aws/config, l'SDK utilizza la modalità adattiva.

Language-specific configurazione

Le impostazioni Cross-SDK descritte in questa pagina (retry_modeemax_attempts) funzionano in tutti gli SDK. Tuttavia, l'API per la configurazione dei nuovi tentativi nel codice varia in base alla lingua. Consulta la guida per sviluppatori del tuo SDK per le opzioni di configurazione specifiche della lingua, come strategie di backoff personalizzate, errori riutilizzabili aggiuntivi e riprova a ottimizzare le quote.

Come funzionano i nuovi tentativi

Questa sezione descrive come gli AWS SDK gestiscono le richieste non riuscite: quali errori generano nuovi tentativi, per quanto tempo l'SDK attende tra un tentativo e l'altro e quando interrompe i tentativi.

Cosa succede quando una richiesta fallisce

Quando effettui una chiamata API tramite un AWS SDK, l'SDK segue questa sequenza:

L'SDK ripete questo ciclo finché la richiesta non ha esito positivo, non viene raggiunto il numero massimo di tentativi, non viene esaurita la quota di tentativi o si verifica un errore irreversibile. L'intero processo è automatico. L'applicazione visualizza una risposta corretta o un errore finale.

Quali errori vengono ritentati

L'SDK classifica ogni richiesta non riuscita in una delle tre categorie seguenti: transitoria, limitata o non riprovabile. Questa classificazione determina se l'SDK ritenta la richiesta e per quanto tempo attende prima di riprovare.

La classificazione si basa sul codice di errore e sul codice di stato HTTP nella risposta del servizio. Ad esempio, un HTTP 400 con il codice di errore RequestTimeout viene classificato come transitorio e riprovato. Un HTTP 400 con ValidationException viene classificato come non riutilizzabile e restituito immediatamente.

Classificazione degli errori

Gli errori transitori vengono ritentati con un breve ritardo di base (50 ms):

Gli errori di limitazione vengono ritentati con un ritardo di base più lungo (1.000 ms):

Non-retryable gli errori (comeAccessDeniedException,ValidationException,ResourceNotFoundException) vengono restituiti immediatamente al codice.

Gli errori di limitazione indicano che il servizio ha rifiutato attivamente la richiesta a causa dei limiti di velocità, quindi l'SDK attende più a lungo prima di riprovare a concedere al servizio il tempo necessario per ripristinare la capacità. Per i ritardi specifici, consulta la sezioneQuanto tempo aspetta l'SDK.

Quanto tempo aspetta l'SDK

L'SDK utilizza un backoff esponenziale con jitter completo. In media, ogni nuovo tentativo attende più a lungo dell'ultimo, con la randomizzazione per distribuire le richieste provenienti da più client.

Base dei ritardi per tipo di errore

Il ritardo di base dipende dal fatto che l'errore sia transitorio o limitato:

Formula di backoff

L'SDK calcola ogni ritardo tra tentativi utilizzando questa formula:

delay = random(0, 1) × min(20,000 ms, base_delay × 2^retry)

Dove:

Il limite massimo di backoff è di 20 secondi. Nessun ritardo individuale supera i 20 secondi indipendentemente dal numero di tentativi avvenuti.

Esempi funzionanti

Esempio 1: errore transitorio, massimo 3 tentativi

La latenza totale aggiunta è in media di circa 75 ms in entrambi i tentativi.

Esempio 2: errore di limitazione, massimo 3 tentativi

La latenza totale aggiunta è in media di circa 1.500 ms in entrambi i tentativi.

Esempio 3: errore transitorio, raggiungimento del limite massimo consentito

Con un ritardo base di 50 ms, il ritardo calcolato prima del limite sarebbe:

Il limite entra in vigore al decimo tentativo (undicesimo tentativo) per errori transitori. Per gli errori di limitazione con una base di 1.000 ms, il limite ha effetto al sesto tentativo.

Perché il jitter è importante

Il moltiplicatore casuale si chiama full jitter. In caso contrario, tutti i client che riscontrano un errore nello stesso momento riproverebbero contemporaneamente, generando un'ondata di traffico di tentativi (il cosiddetto problema del «Thundering Herd»). Full Jitter ripartisce i tentativi in modo uniforme su tutta la finestra di backoff, in modo che il servizio riceva un flusso costante di richieste anziché picchi sincronizzati.

Ad esempio, supponiamo che 1.000 clienti ricevano tutti un 503 nello stesso momento. Il full jitter distribuisce i primi tentativi in modo uniforme su una finestra di 50 ms invece di avere tutti i 1.000 tentativi esattamente a 50 ms.

Server-directed tempistica dei tentativi

Alcuni Servizi AWS includono un'x-amz-retry-afterintestazione nelle risposte di errore. Il valore dell'intestazione è un ritardo in millisecondi. Quando questa intestazione è presente, l'SDK utilizza il ritardo specificato dal server, limitato a un minimo del ritardo di backoff calcolato e a un massimo del ritardo di backoff calcolato più 5.000 ms. Poiché il backoff calcolato è a sua volta limitato a 20 secondi, il ritardo massimo effettivo diretto dal server è di 25 secondi. L'SDK non applica il jitter a questo valore, perché si prevede che il servizio lo modifichi. Ciò consente al servizio di comunicare esattamente quando prevede di disporre di capacità.

Riprova la quota (token bucket)

L'SDK mantiene un budget interno per i token che tiene traccia del rapporto tra richieste riuscite e errori. Quando gli errori sono diffusi, il budget si esaurisce e l'SDK restituisce direttamente gli errori. L'applicazione fallisce rapidamente invece di attendere nuovi tentativi che difficilmente avranno successo. Ciò riduce anche il traffico di nuovi tentativi, aiutando a risolvere più rapidamente le interruzioni del servizio.

Come funziona la quota di tentativi

Il budget del token inizia pieno. A ogni nuovo tentativo vengono detratti i token. Quando un nuovo tentativo riesce, l'SDK ripristina i token consumati da quel nuovo tentativo. Quando una richiesta ha esito positivo al primo tentativo (non sono necessari nuovi tentativi), l'SDK ripristina 1 token. Quando il budget raggiunge lo zero, l'SDK interrompe i tentativi e restituisce gli errori direttamente nel codice.

Il costo più elevato dei nuovi tentativi temporanei riflette il diverso modello di fallimento. Errori transitori come 500 secondi e guasti di connessione spesso indicano un problema a livello di servizio. In queste situazioni, è improbabile che i tentativi continui abbiano successo. Aggiunge latenza alle chiamate, impegna le risorse dei clienti e può ritardare il ripristino per tutti. Gli errori di throttling indicano che il servizio necessita di più tempo prima che la richiesta possa avere successo. L'SDK attende più a lungo tra un tentativo e l'altro per aumentare le probabilità di successo.

Quando viene effettuato il blocco delle quote

La quota di nuovi tentativi tiene traccia dei token in ogni momento, ma blocca i nuovi tentativi solo quando il budget è esaurito. Durante il normale funzionamento, quasi tutte le richieste hanno esito positivo e il budget rimane pieno. La quota non ha effetti osservabili sui nuovi tentativi.

Un nuovo tentativo riuscito ripristina solo il costo del token corrispondente (14 o 5 token), non il costo dei precedenti tentativi falliti nella stessa richiesta. Ad esempio, se il primo tentativo fallisce e il secondo riesce, il budget perde 14 token netti. Il budget si esaurisce più rapidamente quando i nuovi tentativi esauriscono tutti i tentativi senza successo, ma si esaurisce anche gradualmente quando le richieste richiedono più tentativi prima di avere successo.

Con l'impostazione predefinita di un massimo di 3 tentativi, la quota inizia a diminuire quando più del 22% circa delle richieste comporta errori temporanei prolungati o più del 32% circa in caso di errori di limitazione. Al di sotto di queste percentuali, le richieste riuscite riforniscono il budget più rapidamente rispetto ai nuovi tentativi falliti che lo esauriscono.

Il saldo iniziale del budget di 500 token fornisce un buffer che assorbe brevi episodi di guasto. Un breve picco di errori, anche grave, non blocca i nuovi tentativi a meno che non persista abbastanza a lungo da svuotare il buffer.

Implicazioni pratiche

Service-specific comportamento

DynamoDB

I client DynamoDB utilizzano impostazioni predefinite ottimizzate per il profilo a bassa latenza di DynamoDB:

Queste impostazioni predefinite si applicano sia ad Amazon DynamoDB che a DynamoDB Streams.

Long-polling operazioni

Alcune AWS operazioni utilizzano sondaggi lunghi. Possono mantenere aperta una connessione in attesa che arrivi il lavoro. Queste operazioni ricevono un trattamento speciale per riprovare:

Comportamento speciale: quando la quota di tentativi è esaurita e i nuovi tentativi vengono bloccati (passaggio 7Cosa succede quando una richiesta fallisce), l'SDK applica comunque un ritardo di backoff prima di restituire l'errore al codice.

Questo è importante perché le operazioni di polling a lungo termine vengono in genere richiamate a ciclo chiuso. Il codice chiamaReceiveMessage, elabora tutti i messaggi, quindi richiama ReceiveMessage immediatamente. Senza il backoff forzato, un budget di token esaurito farebbe sì che l'SDK restituisca errori senza ritardi. Il ciclo di polling invierebbe quindi immediatamente la richiesta successiva, aumentando l'utilizzo della CPU del client e generando traffico aggiuntivo. Il ritardo forzato del backoff interrompe questo ciclo, mantenendo gestibili l'utilizzo delle risorse del cliente e la frequenza di polling in caso di guasto.

Support di AWS SDK e strumenti

La tabella seguente elenca la disponibilità del comportamento aggiornato dei tentativi in ogni SDK. Per SDK-specific dettagli tra cui la versione minima, le impostazioni predefinite precedenti e successive ed esempi di codice, consulta il problema di tracciamento. GitHub