Questa pagina descrive in che modo gli strumenti Cloud Storage riprovano le richieste non riuscite e come personalizzare il comportamento dei nuovi tentativi. Inoltre, descrive i fattori da prendere in considerazione per riprovare a inviare le richieste.
Panoramica
Esistono due fattori che determinano se è possibile o meno riprovare a inviare una richiesta:
- La risposta che ricevi dalla richiesta.
- L'idempotenza della richiesta.
Risposta
La risposta che ricevi dalla richiesta indica se è utile riprovare o meno. Le risposte relative a problemi temporanei sono generalmente ripetibili. D'altra parte, la risposta relativa agli errori permanenti indica che devi apportare modifiche, ad esempio di autorizzazione o configurazione, prima di riprovare a inviare la richiesta. Le seguenti risposte indicano problemi temporanei che sono utili per riprovare:
- Codici di risposta HTTP
408
,429
e5xx
. - Timeout della socket e disconnessioni TCP.
Per ulteriori informazioni, consulta i codici di stato e di errore per JSON e XML.
Identità
Una richiesta idempotente può essere eseguita ripetutamente e lascia sempre la risorsa di destinazione nello stesso stato finale. Ad esempio, le richieste di scheda sono sempre idempotenti, perché non modificano le risorse. La creazione di una nuova notifica Pub/Sub, invece, non è mai idempotente, perché viene creato un nuovo ID notifica ogni volta che la richiesta va a buon fine.
Di seguito sono riportati alcuni esempi di condizioni che rendono un'operazione idempotente:
L'operazione ha lo stesso effetto osservabile sulla risorsa di destinazione anche se viene richiesta continuamente.
L'operazione riesce una sola volta.
L'operazione non ha alcun effetto osservabile sullo stato della risorsa di destinazione.
Quando ricevi una risposta ripetibile, devi considerare l'idempotenza della richiesta, perché la ripetizione delle richieste non idempotenti può portare a condizioni di gara e altri conflitti.
Identità condizionale
Un sottoinsieme di richieste è condizionatamente idempotente, il che significa che sono idempotenti solo se includono argomenti facoltativi specifici. Per impostazione predefinita, le operazioni per le quali è possibile eseguire nuovamente il tentativo in modo condizionatamente sicuro devono essere ripetute solo se la condizione della casella viene soddisfatta. Cloud Storage accetta precondizioni ed ETag come condizioni per le richieste.
Identità delle operazioni
La tabella seguente elenca le operazioni di Cloud Storage che rientrano in ogni categoria di iridempicità.
Identità | Operazioni |
---|---|
Sempre idempotente |
|
Condizionalmente idempotente |
|
Mai idempotente |
|
1Questo campo è disponibile per l'utilizzo nell'API JSON. Per i campi disponibili per l'utilizzo nelle librerie client, consulta la documentazione della libreria client pertinente.
Come gli strumenti di Cloud Storage implementano le strategie di ripetizione
Console
La console Google Cloud invia richieste a Cloud Storage per tuo conto e gestisce eventuali ritardi necessari.
Riga di comando
I comandi gcloud storage
riprovano a correggere gli errori elencati nella sezione Risposta senza che tu debba intraprendere ulteriori azioni.
Potresti dover intervenire per altri errori, ad esempio:
Credenziali non valide o autorizzazioni insufficienti.
La rete non è raggiungibile a causa di un problema di configurazione del proxy.
Per gli errori ripetibili, l'interfaccia a riga della gcloud CLI riprova le richieste utilizzando una strategia di backoff esponenziale binario troncata. Il numero predefinito di nuovi tentativi massimi è 32 per gcloud CLI.
Librerie client
C++
Per impostazione predefinita, le operazioni supportano i tentativi di nuovo per i seguenti codici di errore HTTP, nonché eventuali errori di socket che indicano che la connessione è andata persa o non è mai stata stabilita correttamente.
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
Tutte le impostazioni di backoff esponenziale e di nuovo tentativo nella libreria C++ sono configurabili. Se gli algoritmi implementati nella libreria non supportano le tue esigenze, puoi fornire codice personalizzato per implementare le tue strategie.
Impostazione | Valore predefinito |
---|---|
Nuovo tentativo automatico | Vero |
Tempo massimo per il nuovo tentativo di invio di una richiesta | 15 minuti |
Tempo di attesa iniziale (backoff) | 1 secondo |
Moltiplicatore del tempo di attesa per iterazione | 2 |
Tempo di attesa massimo | 5 minuti |
Per impostazione predefinita, la libreria C++ riprova tutte le operazioni con errori ripetibili, anche quelle che non sono mai idempotenti e possono eliminare o creare più risorse se andate a buon fine ripetutamente. Per riprovare solo le operazioni idempotenti, utilizza la classe google::cloud::storage::StrictIdempotencyPolicy
.
C#
Per impostazione predefinita, la libreria client C# utilizza il backoff esponenziale.
Vai
Per impostazione predefinita, le operazioni supportano i tentativi di nuovo invio per i seguenti errori:
- Errori di connessione:
io.ErrUnexpectedEOF
: questo può verificarsi a causa di problemi temporanei della rete.url.Error
contenenteconnection refused
: questo potrebbe verificarsi a causa di problemi di rete temporanei.url.Error
contenenteconnection reset by peer
: significa che Google Cloud ha reimpostato la connessione.net.ErrClosed
: significa che Google Cloud ha chiuso la connessione.
- Codici HTTP:
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
- Errori che implementano l'interfaccia
Temporary()
e forniscono un valoreerr.Temporary() == true
- Eventuali errori sopra indicati che sono stati racchiusi utilizzando il contenimento degli errori di Go 1.13
Tutte le impostazioni di backoff esponenziale nella libreria Go sono configurabili. Per impostazione predefinita, le operazioni in Go utilizzano le seguenti impostazioni per il backoff esponenziale (quelle predefinite sono prese da gax):
Impostazione | Valore predefinito (in secondi) |
---|---|
Nuovo tentativo automatico | True se idempotente |
Numero massimo di tentativi | Nessun limite |
Ritardo nuovo tentativo iniziale | 1 secondo |
Moltiplicatore del ritardo del nuovo tentativo | 2.0 |
Ritardo massimo nuovo tentativo | 30 secondi |
Tempo di attesa totale (chunk di caricamento ripristinabile) | 32 secondi |
Timeout totale (tutte le altre operazioni) | Nessun limite |
In genere, i tentativi di nuovo avvengono indefinitamente, a meno che il contesto di controllo non venga annullato, il client non venga chiuso o non venga ricevuto un errore non transitorio. Per interrompere la continuazione dei tentativi, utilizza i timeout o l'annullamento del contesto. L'unica eccezione a questo comportamento si verifica quando esegui caricamenti riavviabili utilizzando Writer, se i dati sono sufficientemente grandi da richiedere più richieste. In questo scenario, per impostazione predefinita ogni frammento scade e smette di riprovare dopo 32 secondi. Puoi aggiustare il timeout predefinito modificando Writer.ChunkRetryDeadline
.
Esiste un sottoinsieme di operazioni Go che sono condizionatamente idempotenti (è possibile riprovare in sicurezza). Queste operazioni vengono riprovate solo sesoddisfano condizioni specifiche:
GenerationMatch
oGeneration
- È possibile riprovare se alla chiamata è stato applicato un prerequisito
GenerationMatch
o se è stato impostatoObjectHandle.Generation
.
- È possibile riprovare se alla chiamata è stato applicato un prerequisito
MetagenerationMatch
- È possibile riprovare se alla chiamata è stata applicata una precondizione
MetagenerationMatch
.
- È possibile riprovare se alla chiamata è stata applicata una precondizione
Etag
- È possibile riprovare se il metodo inserisce un
etag
nel corpo della richiesta JSON. Viene utilizzato solo inHMACKeyHandle.Update
se è stato impostatoHmacKeyMetadata.Etag
.
- È possibile riprovare se il metodo inserisce un
RetryPolicy
è impostato su RetryPolicy.RetryIdempotent
per impostazione predefinita. Consulta Personalizzare i tentativi di nuovo invio per esempi su come modificare il comportamento predefinito dei tentativi di nuovo invio.
Java
Per impostazione predefinita, le operazioni supportano i tentativi di nuovo invio per i seguenti errori:
- Errori di connessione:
Connection reset by peer
: significa che Google Cloud ha reimpostato la connessione.Unexpected connection closure
: significa che Google Cloud ha chiuso la connessione.
- Codici HTTP:
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
Tutte le impostazioni di backoff esponenziale nella libreria Java sono configurabili. Per impostazione predefinita, le operazioni tramite Java utilizzano le seguenti impostazioni per il backoff esponenziale:
Impostazione | Valore predefinito (in secondi) |
---|---|
Nuovo tentativo automatico | True se idempotente |
Numero massimo di tentativi | 6 |
Ritardo nuovo tentativo iniziale | 1 secondo |
Moltiplicatore del ritardo del nuovo tentativo | 2.0 |
Ritardo massimo nuovo tentativo | 32 secondi |
Timeout totale | 50 secondi |
Tempo di attesa RPC iniziale | 50 secondi |
Multiplicatore del tempo di attesa RPC | 1,0 |
Tempo di attesa RPC massimo | 50 secondi |
Timeout connessione | 20 secondi |
Timeout di lettura | 20 secondi |
Per ulteriori informazioni sulle impostazioni, consulta la documentazione di riferimento Java per RetrySettings.Builder
e HttpTransportOptions.Builder
.
Esiste un sottoinsieme di operazioni Java che sono condizionesamente idempotenti (condizionesamente sicure per i tentativi di nuovo invio). Queste operazioni ritentano solo se includono argomenti specifici:
ifGenerationMatch
ogeneration
- È possibile riprovare se
ifGenerationMatch
ogeneration
è stato passato come opzione al metodo.
- È possibile riprovare se
ifMetagenerationMatch
- È possibile riprovare se
ifMetagenerationMatch
è stato passato come opzione.
- È possibile riprovare se
StorageOptions.setStorageRetryStrategy
è impostato su
StorageRetryStrategy#getDefaultStorageRetryStrategy
per impostazione predefinita.
Consulta Personalizzare i tentativi ripetuti per esempi su come modificare il comportamento predefinito dei tentativi ripetuti.
Node.js
Per impostazione predefinita, le operazioni supportano i tentativi di nuovo invio per i seguenti codici di errore:
- Errori di connessione:
EAI_again
: si tratta di un errore di ricerca DNS. Per ulteriori informazioni, consulta la documentazione digetaddrinfo
.Connection reset by peer
: significa che Google Cloud ha reimpostato la connessione.Unexpected connection closure
: significa che Google Cloud ha chiuso la connessione.
- Codici HTTP:
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
Tutte le impostazioni di backoff esponenziale nella libreria Node.js sono configurabili. Per impostazione predefinita, le operazioni tramite Node.js utilizzano le seguenti impostazioni per il backoff esponenziale:
Impostazione | Valore predefinito (in secondi) |
---|---|
Nuovo tentativo automatico | True se idempotente |
Numero massimo di nuovi tentativi | 3 |
Tempo di attesa iniziale | 1 secondo |
Moltiplicatore del tempo di attesa per iterazione | 2 |
Tempo di attesa massimo | 64 secondi |
Scadenza predefinita | 600 secondi |
Esiste un sottoinsieme di operazioni Node.js che sono condizione simili (è possibile riprovare in sicurezza). Queste operazioni vengono riprovate solo se includono argomenti specifici:
ifGenerationMatch
ogeneration
- È possibile riprovare se
ifGenerationMatch
ogeneration
è stato passato come opzione al metodo. Spesso i metodi accettano solo uno di questi due parametri.
- È possibile riprovare se
ifMetagenerationMatch
- È possibile riprovare se
ifMetagenerationMatch
è stato passato come opzione.
- È possibile riprovare se
retryOptions.idempotencyStrategy
è impostato su
IdempotencyStrategy.RetryConditional
per impostazione predefinita. Consulta Personalizzare i tentativi di nuovo invio per esempi su come modificare il comportamento predefinito dei tentativi di nuovo invio.
PHP
Per impostazione predefinita, la libreria client PHP utilizza il backoff esponenziale.
Python
Per impostazione predefinita, le operazioni supportano i tentativi di nuovo invio per i seguenti codici di errore:
- Errori di connessione:
requests.exceptions.ConnectionError
requests.exceptions.ChunkedEncodingError
(solo per le operazioni che recuperano o inviano dati del payload agli oggetti, come caricamenti e download)ConnectionError
- Codici HTTP:
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
Le operazioni tramite Python utilizzano le seguenti impostazioni predefinite per il backoff esponenziale:
Impostazione | Valore predefinito (in secondi) |
---|---|
Nuovo tentativo automatico | True se idempotente |
Tempo di attesa iniziale | 1 |
Moltiplicatore del tempo di attesa per iterazione | 2 |
Tempo di attesa massimo | 60 |
Scadenza predefinita | 120 |
Esiste un sottoinsieme di operazioni Python che sono condizionatamente idempotenti (è possibile riprovare in sicurezza) quando includono argomenti specifici. Queste operazioni vengono riprovate solo se viene soddisfatta una condizione:
DEFAULT_RETRY_IF_GENERATION_SPECIFIED
- È possibile riprovare se
generation
oif_generation_match
è stato passato come argomento al metodo. Spesso i metodi accettano solo uno di questi due parametri.
- È possibile riprovare se
DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED
- È possibile riprovare se
if_metageneration_match
è stato passato come argomento al metodo.
- È possibile riprovare se
DEFAULT_RETRY_IF_ETAG_IN_JSON
- È possibile riprovare se il metodo inserisce un
etag
nel corpo della richiesta JSON. PerHMACKeyMetadata.update()
, significa che l'etag deve essere impostato sull'oggettoHMACKeyMetadata
stesso. Per il metodoset_iam_policy()
in altre classi, ciò significa che l'etag deve essere impostato nell'argomento "policy" passato al metodo.
- È possibile riprovare se il metodo inserisce un
Ruby
Per impostazione predefinita, le operazioni supportano i tentativi di nuovo invio per i seguenti codici di errore:
- Errori di connessione:
SocketError
HTTPClient::TimeoutError
Errno::ECONNREFUSED
HTTPClient::KeepAliveDisconnected
- Codici HTTP:
408 Request Timeout
429 Too Many Requests
5xx Server Error
Tutte le impostazioni di backoff esponenziale nella libreria client Ruby sono configurabili. Per impostazione predefinita, le operazioni tramite la libreria client Ruby utilizzano le seguenti impostazioni per il backoff esponenziale:
Impostazione | Valore predefinito |
---|---|
Nuovo tentativo automatico | Vero |
Numero massimo di nuovi tentativi | 3 |
Tempo di attesa iniziale | 1 secondo |
Moltiplicatore del tempo di attesa per iterazione | 2 |
Tempo di attesa massimo | 60 secondi |
Scadenza predefinita | 900 secondi |
Esiste un sottoinsieme di operazioni Ruby che sono condizionatamente idempotenti (è possibile riprovare in sicurezza) quando includono argomenti specifici:
if_generation_match
ogeneration
- È possibile riprovare se il parametro
generation
oif_generation_match
viene passato come argomento al metodo. Spesso i metodi accettano solo uno di questi due parametri.
- È possibile riprovare se il parametro
if_metageneration_match
- È possibile riprovare se il parametro
if_metageneration_match
viene passato come opzione.
- È possibile riprovare se il parametro
Per impostazione predefinita, viene eseguito un nuovo tentativo per tutte le operazioni idempotenti e per le operazioni idempotenti condizionali solo se la condizione è soddisfatta. Le operazioni non idempotenti non vengono ripetute. Consulta Personalizzare i tentativi di nuovo invio per esempi su come modificare il comportamento predefinito dei tentativi di nuovo invio.
API REST
Quando chiami direttamente l'API JSON o XML, devi utilizzare l'algoritmo di backoff esponenziale per implementare la tua strategia di nuovo tentativo.
Personalizzazione dei nuovi tentativi
Console
Non puoi personalizzare il comportamento dei tentativi di nuovo utilizzando la console Google Cloud.
Riga di comando
Per i comandi gcloud storage
, puoi controllare la strategia di ripetizione creando una configurazione denominata e impostando alcune o tutte le seguenti proprietà:
base_retry_delay
exponential_sleep_multiplier
max_retries
max_retry_delay
Poi applichi la configurazione definita su base per comando utilizzando il flag --configuration
a livello di progetto o per tutti i comandi gcloud utilizzando il comando gcloud config set
.
Librerie client
C++
Per personalizzare il comportamento di ripetizione dei tentativi, fornisci i valori per le seguenti opzioni quando inizializzi l'oggetto google::cloud::storage::Client
:
google::cloud::storage::RetryPolicyOption
: la libreria fornisce i corsigoogle::cloud::storage::LimitedErrorCountRetryPolicy
egoogle::cloud::storage::LimitedTimeRetryPolicy
. Puoi fornire la tua classe, che deve implementare l'interfacciagoogle::cloud::RetryPolicy
.google::cloud::storage::BackoffPolicyOption
: la libreria fornisce la classegoogle::cloud::storage::ExponentialBackoffPolicy
. Puoi fornire la tua classe, che deve implementare l'interfacciagoogle::cloud::storage::BackoffPolicy
.google::cloud::storage::IdempotencyPolicyOption
: la libreria fornisce i tipigoogle::cloud::storage::StrictIdempotencyPolicy
egoogle::cloud::storage::AlwaysRetryIdempotencyPolicy
. Puoi fornire la tua classe, che deve implementare l'interfacciagoogle::cloud::storage::IdempotencyPolicy
.
Per saperne di più, consulta la documentazione di riferimento della libreria client C++.
C#
Non puoi personalizzare la strategia di ripetizione predefinita utilizzata dalla libreria client C#.
Vai
Quando viene inizializzato un client di archiviazione, viene impostata una configurazione di ripetizione predefinita. A meno che non vengano sostituite, le opzioni nella configurazione sono impostate sui valori predefiniti. Gli utenti possono configurare il comportamento di ripetizione non predefinito per una singola chiamata alla libreria (utilizzando BucketHandle.Retryer e ObjectHandle.Retryer) o per tutte le chiamate effettuate da un client (utilizzando Client.SetRetry). Per modificare il comportamento di ripetizione, passa RetryOptions pertinente a uno di questi metodi.
Consulta il seguente esempio di codice per scoprire come personalizzare il comportamento di ripetizione.
Java
Quando viene inizializzato Storage
, viene inizializzata anche un'istanza di
RetrySettings
. A meno che non vengano superate, le opzioni in RetrySettings
sono impostate sui valori predefiniti. Per modificare il comportamento di ripetizione automatica predefinito, passa il StorageRetryStrategy
personalizzato al StorageOptions
utilizzato per creare l'istanza Storage
. Per modificare uno degli altri parametri scalari, passa un RetrySettings
personalizzato al StorageOptions
utilizzato per creare l'istanza Storage
.
Consulta l'esempio seguente per scoprire come personalizzare il comportamento di ripetizione:
Node.js
Quando inizializzazione Cloud Storage, viene inizializzato anche un file di configurazione retryOptions. A meno che non vengano sostituite, le opzioni
nella configurazione sono impostate sui valori predefiniti. Per modificare il comportamento di ripetizione predefinito, passa la configurazione di ripetizione personalizzata
retryOptions
al costruttore dello spazio di archiviazione all'inizializzazione.
La libreria client Node.js può utilizzare automaticamente le strategie di backoff per ritentare le richieste con il parametro autoRetry
.
Consulta il seguente esempio di codice per scoprire come personalizzare il comportamento di ripetizione.
PHP
Non puoi personalizzare la strategia di ripetizione predefinita utilizzata dalla libreria client PHP.
Python
Per modificare il comportamento di ripetizione predefinito, crea una copia dell'oggetto
google.cloud.storage.retry.DEFAULT_RETRY
chiamandolo con un metodo
with_XXX
. La libreria client Python utilizza automaticamente strategie di backoff per riprovare le richieste se includi il parametro DEFAULT_RETRY
.
Tieni presente che with_predicate
non è supportato per le operazioni che recuperano o inviano dati del payload agli oggetti, come caricamenti e download. Ti consigliamo di modificare gli attributi uno alla volta. Per ulteriori informazioni, consulta la documentazione di riferimento su Retry di google-api-core.
Per configurare il tuo nuovo tentativo condizionale, crea un oggetto
ConditionalRetryPolicy
e avvolgi l'oggetto Retry
personalizzato con DEFAULT_RETRY_IF_GENERATION_SPECIFIED
,
DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED
o
DEFAULT_RETRY_IF_ETAG_IN_JSON
.
Consulta il seguente esempio di codice per scoprire come personalizzare il comportamento di ripetizione.
Ruby
Quando viene inizializzato il client di archiviazione, tutte le configurazioni di ripetizione vengono impostate su i valori mostrati nella tabella sopra. Per modificare il comportamento di riprova predefinito, passa le configurazioni di riprova durante l'inizializzazione del client di archiviazione.
Per ignorare il numero di tentativi per una determinata operazione, passa
retries
nel parametro options
dell'operazione.
API REST
Utilizza l'algoritmo di backoff esponenziale per implementare la tua strategia di ripetizione.
Algoritmo di backoff esponenziale
Un algoritmo di backoff esponenziale riprova le richieste utilizzando tempi di attesa in aumento esponenziale tra le richieste, fino a un tempo di backoff massimo. In genere, dovresti utilizzare il backoff esponenziale con jitter per eseguire nuovamente le richieste che soddisfano sia i criteri di risposta sia quelli di iridempicità. Per le best practice sull'implementazione di tentativi automatici con backoff esponenziale, consulta Risolvere i guasti a cascata.
Passaggi successivi
- Scopri di più sui precondizioni della richiesta.