Questa pagina descrive in che modo gli strumenti di Cloud Storage riprovano le richieste non riuscite e come personalizzare il comportamento dei nuovi tentativi. Descrive anche le considerazioni per i nuovi tentativi delle richieste.
Panoramica
Esistono due fattori che determinano se è possibile riprovare una richiesta o meno:
- La risposta che ricevi alla richiesta.
- L'idempotenza della richiesta.
Risposta
La risposta che ricevi dalla richiesta indica se è utile ripetere la richiesta. Le risposte relative a problemi temporanei in genere non sono possibili. Invece, la risposta relativa a errori permanenti indica che devi apportare modifiche, ad esempio modifiche all'autorizzazione o alla configurazione, prima che sia utile provare a ripetere la richiesta. Le seguenti risposte indicano problemi temporanei che possono essere utili per un nuovo tentativo:
- Codici di risposta HTTP
408
,429
e5xx
. - Timeout del socket e disconnessioni TCP.
Per saperne di più, consulta i codici di stato e di errore per JSON e XML.
IDempotenza
Una richiesta idempotente significa che può essere eseguita ripetutamente e lascia sempre la risorsa scelta come target nello stesso stato finale. Ad esempio, le richieste di creazione di elenchi sono sempre idempotenti, perché non modificano le risorse. D'altra parte, la creazione di una nuova notifica Pub/Sub non è mai idempotente, perché crea un nuovo ID notifica ogni volta che la richiesta ha esito positivo.
Di seguito sono riportati alcuni esempi di condizioni che rendono idempotente un'operazione:
L'operazione ha lo stesso effetto osservabile sulla risorsa scelta come target anche quando viene richiesta continuamente.
L'operazione ha esito positivo una sola volta.
L'operazione non ha un effetto osservabile sullo stato della risorsa scelta come target.
Quando ricevi una risposta con tentativi, dovresti considerare l'idempotenza della richiesta, perché un nuovo tentativo di richieste non idempotenti può causare condizioni di gara e altri conflitti.
IDempotenza condizionale
Un sottoinsieme di richieste è idempotente con condizione, il che significa che sono idempotenti solo se includono argomenti facoltativi specifici. Per impostazione predefinita, le operazioni che è sicuro eseguire un nuovo tentativo in modo condizionale devono essere tentate per impostazione predefinita solo se la condizione ha esito positivo. Cloud Storage accetta precondizioni ed ETag come casi di condizione per le richieste.
IDempotenza delle operazioni
Nella tabella seguente sono elencate le operazioni di Cloud Storage che rientrano in ogni categoria di idempotenza.
IDempotenza | Suite operativa |
---|---|
Sempre idempotente |
|
idempotente condizionata |
|
Mai idempotente |
|
1 Questo campo è disponibile per l'utilizzo nell'API JSON. Per i campi disponibili per l'utilizzo nelle librerie client, consulta la relativa documentazione sulle librerie client.
In che modo gli strumenti di Cloud Storage implementano le strategie per i nuovi tentativi
Console
La console Google Cloud invia le richieste a Cloud Storage per tuo conto e gestisce eventuali backoff necessari.
Riga di comando
I comandi gcloud storage
ripetono gli errori elencati nella
sezione Risposta senza richiedere ulteriori azioni.
Potresti dover intervenire per altri errori, ad esempio:
Credenziali non valide o autorizzazioni insufficienti.
Rete non raggiungibile a causa di un problema di configurazione del proxy.
In caso di errori non irreversibili, l'interfaccia a riga della gcloud CLI esegue un nuovo tentativo di richiesta utilizzando una strategia di backoff esponenziale binario troncato. Il numero predefinito di nuovi tentativi massimi per gcloud CLI è 32.
Librerie client
C++
Per impostazione predefinita, le operazioni supportano i nuovi tentativi per i seguenti codici di errore HTTP, nonché gli eventuali errori socket che indicano che la connessione è stata 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 dei tentativi nella libreria C++ sono configurabili. Se gli algoritmi implementati nella libreria non supportano le tue esigenze, puoi fornire un codice personalizzato per implementare le tue strategie.
Impostazione | Valore predefinito |
---|---|
Nuovo tentativo automatico | True |
Tempo massimo per riprovare una richiesta | 15 minuti |
Tempo di attesa iniziale (backoff) | 1 secondo |
Moltiplicatore del tempo di attesa per iterazione | 2 |
Tempo massimo di attesa | 5 minuti |
Per impostazione predefinita, la libreria C++ riprova tutte le operazioni con errori non irreversibili, anche quelli che non sono mai idempotenti e possono eliminare o creare più risorse se l'esito è ripetuto. Per riprovare solo le operazioni idempotenti, utilizza la classe google::cloud::storage::StrictIdempotencyPolicy
.
C#
La libreria client C# utilizza il backoff esponenziale per impostazione predefinita.
Go
Per impostazione predefinita, le operazioni supportano i nuovi tentativi per i seguenti errori:
- Errori di connessione:
io.ErrUnexpectedEOF
: questo problema potrebbe essere dovuto a problemi di rete temporanei.url.Error
contenenteconnection refused
: ciò potrebbe essere dovuto a 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 assegnano un valore pari aerr.Temporary() == true
- Tutti gli errori riportati sopra sono stati sottoposti a wrapping utilizzando il wrapping di errori 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 (i valori predefiniti vengono ricavati da gax):
Impostazione | Valore predefinito (in secondi) |
---|---|
Nuovo tentativo automatico | True se idempotente |
Numero massimo di tentativi | Nessun limite |
Ritardo tra tentativi iniziale | 1 secondo |
Moltiplicatore di tentativi per il ritardo | 2.0 |
Ritardo massimo tra tentativi | 30 secondi |
Timeout totale (blocco di caricamento ripristinabile) | 32 secondi |
Timeout totale (tutte le altre operazioni) | Nessun limite |
In generale, i nuovi tentativi continuano a tempo indeterminato, a meno che il contesto di controllo non venga annullato, il client non venga chiuso o non venga ricevuto un errore non temporaneo. Per interrompere i nuovi tentativi, utilizza il timeout del contesto o l'annullamento. L'unica eccezione a questo comportamento è l'esecuzione di caricamenti ripristinabili utilizzando Writer, in cui i dati sono sufficientemente grandi da richiedere più richieste. In questo scenario, ogni blocco scade e smette di riprovare dopo 32 secondi per impostazione predefinita. Puoi
modificare il timeout predefinito modificando Writer.ChunkRetryDeadline
.
Esiste un sottoinsieme di operazioni Go che sono idempotenti in base alle condizioni (è possibile riprovare a seconda della condizione). Queste operazioni riprovano solo se soddisfano condizioni specifiche:
GenerationMatch
oGeneration
- Riprova se è stata applicata una precondizione
GenerationMatch
alla chiamata o se è stato impostatoObjectHandle.Generation
.
- Riprova se è stata applicata una precondizione
MetagenerationMatch
- Riprova se è stata applicata una precondizione
MetagenerationMatch
alla chiamata.
- Riprova se è stata applicata una precondizione
Etag
- Riprova se il metodo inserisce un
etag
nel corpo della richiesta JSON. Utilizzato inHMACKeyHandle.Update
solo se è stato impostatoHmacKeyMetadata.Etag
.
- Riprova se il metodo inserisce un
L'opzione RetryPolicy
è impostata su RetryPolicy.RetryIdempotent
per impostazione predefinita. Consulta Personalizza i nuovi tentativi per alcuni esempi su come modificare il comportamento predefinito dei nuovi tentativi.
Java
Per impostazione predefinita, le operazioni supportano i nuovi tentativi per i seguenti errori:
- Errori di connessione:
Connection reset by peer
: questo 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 tra tentativi iniziale | 1 secondo |
Moltiplicatore di tentativi per il ritardo | 2.0 |
Ritardo massimo tra tentativi | 32 secondi |
Timeout totale | 50 secondi |
Timeout RPC iniziale | 50 secondi |
Moltiplicatore di timeout RPC | 1,0 |
Timeout RPC massimo | 50 secondi |
Timeout connessione | 20 secondi |
Timeout lettura | 20 secondi |
Per ulteriori informazioni sulle impostazioni, consulta la documentazione di riferimento di Java per RetrySettings.Builder
e HttpTransportOptions.Builder
.
Esiste un sottoinsieme di operazioni Java idempotenti condizionalmente (riprovare in modo sicuro). Queste operazioni ripetono l'operazione solo se includono argomenti specifici:
ifGenerationMatch
ogeneration
- Riprovare se è stato trasmesso
ifGenerationMatch
ogeneration
come opzione al metodo.
- Riprovare se è stato trasmesso
ifMetagenerationMatch
- Riprova se è stato trasmesso
ifMetagenerationMatch
come opzione.
- Riprova se è stato trasmesso
L'opzione StorageOptions.setStorageRetryStrategy
è impostata su
StorageRetryStrategy#getDefaultStorageRetryStrategy
per impostazione predefinita.
Consulta Personalizzare i nuovi tentativi per alcuni esempi su come modificare il comportamento predefinito dei nuovi tentativi.
Node.js
Per impostazione predefinita, le operazioni supportano i nuovi tentativi per i seguenti codici di errore:
- Errori di connessione:
EAI_again
: questo è un errore di ricerca DNS. Per ulteriori informazioni, consulta la documentazione digetaddrinfo
.Connection reset by peer
: questo 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 massimo di attesa | 64 secondi |
Scadenza predefinita | 600 secondi |
Esiste un sottoinsieme di operazioni Node.js che sono idempotenti in base alle condizioni (puoi riprovare a seconda della condizione). Queste operazioni riprovano solo se include argomenti specifici:
ifGenerationMatch
ogeneration
- Riprovare se è stato trasmesso
ifGenerationMatch
ogeneration
come opzione al metodo. Spesso, i metodi accettano solo uno di questi due parametri.
- Riprovare se è stato trasmesso
ifMetagenerationMatch
- Riprova se è stato trasmesso
ifMetagenerationMatch
come opzione.
- Riprova se è stato trasmesso
L'opzione retryOptions.idempotencyStrategy
è impostata su
IdempotencyStrategy.RetryConditional
per impostazione predefinita. Consulta Personalizza i nuovi tentativi per alcuni esempi su come modificare il comportamento predefinito dei nuovi tentativi.
PHP
Per impostazione predefinita, la libreria client PHP utilizza il backoff esponenziale.
Python
Per impostazione predefinita, le operazioni supportano i nuovi tentativi per i seguenti codici di errore:
- Errori di connessione:
requests.exceptions.ConnectionError
requests.exceptions.ChunkedEncodingError
(solo per le operazioni che recuperano o inviano dati payload a 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 massimo di attesa | 60 |
Scadenza predefinita | 120 |
Esiste un sottoinsieme di operazioni Python che sono idempotenti in modo condizionale (ovvero con la sicurezza dei nuovi tentativi) quando includono argomenti specifici. Queste operazioni riprovano solo se viene superato un caso di condizione:
DEFAULT_RETRY_IF_GENERATION_SPECIFIED
- Riprova se
generation
oif_generation_match
è stato trasmesso come argomento al metodo. Spesso i metodi accettano solo uno di questi due parametri.
- Riprova se
DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED
- Riprova se
if_metageneration_match
è stato trasmesso come argomento al metodo.
- Riprova se
DEFAULT_RETRY_IF_ETAG_IN_JSON
- Riprova se il metodo inserisce un
etag
nel corpo della richiesta JSON. PerHMACKeyMetadata.update()
, ciò significa che l'etag deve essere impostato sull'oggettoHMACKeyMetadata
stesso. Per il metodoset_iam_policy()
su altre classi, significa che l'etag deve essere impostato nell'argomento "policy" passato al metodo.
- Riprova se il metodo inserisce un
Ruby
Per impostazione predefinita, le operazioni supportano i nuovi tentativi 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 | True |
Numero massimo di nuovi tentativi | 3 |
Tempo di attesa iniziale | 1 secondo |
Moltiplicatore del tempo di attesa per iterazione | 2 |
Tempo massimo di attesa | 60 secondi |
Scadenza predefinita | 900 secondi |
Un sottoinsieme di operazioni Ruby è idempotente in modo condizionale (è possibile riprovare a livello condizionale) quando includono argomenti specifici:
if_generation_match
ogeneration
- Riprova se il parametro
generation
oif_generation_match
viene trasmesso come argomento al metodo. Spesso i metodi accettano solo uno di questi due parametri.
- Riprova se il parametro
if_metageneration_match
- Riprova se il parametro
if_metageneration_match
viene trasmesso come opzione.
- Riprova se il parametro
Per impostazione predefinita, vengono tentati tutti i tentativi di tutte le operazioni idempotenti e le operazioni idempotenti in modo condizionale vengono riprovate solo se il caso della condizione viene superato. Le operazioni non idempotenti non vengono tentate di nuovo. Consulta la sezione Personalizzare i nuovi tentativi per vedere degli esempi su come modificare il comportamento predefinito per i nuovi tentativi.
API REST
Quando chiami direttamente l'API JSON o XML, devi utilizzare l'algoritmo di backoff esponenziale per implementare la tua strategia per i nuovi tentativi.
Nuovi tentativi di personalizzazione
Console
Non puoi personalizzare il comportamento dei nuovi tentativi utilizzando la console Google Cloud.
Riga di comando
Per i comandi gcloud storage
, puoi controllare la strategia per i nuovi tentativi creando una configurazione con nome e impostando alcune o tutte le seguenti proprietà:
base_retry_delay
exponential_sleep_multiplier
max_retries
max_retry_delay
Successivamente applicherai la configurazione definita in base al comando utilizzando il flag a livello di progetto --configuration
o per tutti i comandi gcloud utilizzando il comando gcloud config set
.
Librerie client
C++
Per personalizzare il comportamento dei nuovi tentativi, fornisci valori per le opzioni seguenti quando inizializzi l'oggetto google::cloud::storage::Client
:
google::cloud::storage::RetryPolicyOption
: la libreria offre 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 il corsogoogle::cloud::storage::ExponentialBackoffPolicy
. Puoi fornire la tua classe, che deve implementare l'interfacciagoogle::cloud::storage::BackoffPolicy
.google::cloud::storage::IdempotencyPolicyOption
: la libreria fornisce i corsigoogle::cloud::storage::StrictIdempotencyPolicy
egoogle::cloud::storage::AlwaysRetryIdempotencyPolicy
. Puoi fornire la tua classe, che deve implementare l'interfacciagoogle::cloud::storage::IdempotencyPolicy
.
Per ulteriori informazioni, consulta la documentazione di riferimento sulla libreria client C++.
C#
Non puoi personalizzare la strategia predefinita per i nuovi tentativi utilizzata dalla libreria client C#.
Go
Quando inizializza un client di archiviazione, viene impostata una configurazione predefinita dei nuovi tentativi. A meno che non vengano sostituite, le opzioni nella configurazione sono impostate sui valori predefiniti. Gli utenti possono configurare un comportamento non predefinito per i nuovi tentativi 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 dei nuovi tentativi, passa il metodo RetryOptions pertinente a uno di questi metodi.
Per scoprire come personalizzare il comportamento dei nuovi tentativi, consulta il seguente esempio di codice.
Java
Quando inizializza Storage
, viene inizializzata anche un'istanza di
RetrySettings
. A meno che non vengano sostituite, le opzioni in RetrySettings
sono impostate sui valori predefiniti. Per modificare il comportamento predefinito dei nuovi tentativi automatici, trasmetti il valore StorageRetryStrategy
personalizzato alla sessione StorageOptions
utilizzata per creare l'istanza Storage
. Per modificare uno qualsiasi degli altri parametri scalari, passa un valore RetrySettings
personalizzato alla StorageOptions
utilizzata per creare l'istanza Storage
.
Consulta l'esempio seguente per scoprire come personalizzare il comportamento dei nuovi tentativi:
Node.js
Quando inizializzi Cloud Storage, viene inizializzato anche
un file di configurazione RiprovaOptions. A meno che non vengano sostituite, le opzioni
nella configurazione sono impostate sui valori predefiniti. Per modificare il comportamento predefinito per i nuovi tentativi, passa la configurazione personalizzata dei nuovi tentativi retryOptions
nel costruttore di archiviazione al momento dell'inizializzazione.
La libreria client Node.js può utilizzare automaticamente le strategie di backoff per riprovare le richieste con il parametro autoRetry
.
Per scoprire come personalizzare il comportamento dei nuovi tentativi, consulta il seguente esempio di codice.
PHP
Non puoi personalizzare la strategia predefinita per i nuovi tentativi utilizzata dalla libreria client PHP.
Python
Per modificare il comportamento predefinito per i nuovi tentativi, crea una copia dell'oggetto google.cloud.storage.retry.DEFAULT_RETRY
chiamandolo con un metodo with_XXX
. Se includi il parametro DEFAULT_RETRY
, la libreria client Python utilizza automaticamente le strategie di backoff per riprovare le richieste.
Tieni presente che with_predicate
non è supportato per le operazioni che recuperano o inviano dati di payload a oggetti, come caricamenti e download. Ti consigliamo di
modificare gli attributi uno alla volta. Per ulteriori informazioni, consulta questo articolo di riferimento sui tentativi di google-api-core.
Per configurare un nuovo tentativo condizionale, crea un
oggetto ConditionalRetryPolicy
e aggrega l'oggetto Retry
personalizzato con DEFAULT_RETRY_IF_GENERATION_SPECIFIED
,
DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED
o
DEFAULT_RETRY_IF_ETAG_IN_JSON
.
Per scoprire come personalizzare il comportamento dei nuovi tentativi, consulta il seguente esempio di codice.
Ruby
Quando inizializza il client di archiviazione, tutte le configurazioni dei nuovi tentativi sono impostate sui valori mostrati nella tabella precedente. Per modificare il comportamento predefinito per i nuovi tentativi, supera le configurazioni dei nuovi tentativi durante l'inizializzazione del client di archiviazione.
Per eseguire l'override del numero di nuovi tentativi per una determinata operazione, trasmetti retries
nel parametro options
dell'operazione.
API REST
Utilizza l'algoritmo di backoff esponenziale per implementare la tua strategia per nuovi tentativi.
Algoritmo di backoff esponenziale
Un algoritmo di backoff esponenziale riprova le richieste utilizzando l'aumento esponenziale dei tempi di attesa tra le richieste, fino a un tempo di backoff massimo. In genere dovresti usare il backoff esponenziale con tremolio per riprovare le richieste che soddisfano sia i criteri di risposta che quelli di idempotenza. Per le best practice per l'implementazione di nuovi tentativi automatici con backoff esponenziale, consulta la sezione Gestione degli errori a cascata.
Passaggi successivi
- Scopri come ritentare le richieste in Storage Transfer Service con Java o Python.
- Scopri di più sulle precondizioni della richiesta.