Strategia di nuovo tentativo

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:

  1. La risposta che ricevi alla richiesta.
  2. 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 e 5xx.
  • 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
  • Tutte le richieste di tipo get ed elenco
  • Inserisci o elimina bucket
  • Testa criteri e autorizzazioni IAM dei bucket
  • Blocca criteri di conservazione
  • Elimina una chiave HMAC o una notifica Pub/Sub
idempotente condizionata
  • Richieste di aggiornamento/applicazione di patch per i bucket con IfMetagenerationMatch1 o etag1 come precondizione HTTP
  • Richieste di aggiornamento/applicazione di patch per gli oggetti con IfMetagenerationMatch1 o etag1 come precondizione HTTP
  • Imposta un criterio IAM del bucket con etag1 come precondizione HTTP o nel corpo della risorsa
  • Aggiorna una chiave HMAC con etag1 come precondizione HTTP o nel corpo della risorsa
  • Inserisci, copia, scrivi o riscrivi oggetti con ifGenerationMatch1
  • Elimina un oggetto con ifGenerationMatch1 (o con un numero di generazione per le versioni dell'oggetto)
Mai idempotente
  • Creazione di una chiave HMAC
  • Crea una notifica Pub/Sub
  • Creare, eliminare o inviare richieste di patch/aggiornamento per gli ACL di bucket e oggetti o ACL di oggetti predefiniti

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 contenente connection refused: ciò potrebbe essere dovuto a problemi di rete temporanei.
    • url.Error contenente connection 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 a err.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 o Generation

    • Riprova se è stata applicata una precondizione GenerationMatch alla chiamata o se è stato impostato ObjectHandle.Generation.

  • MetagenerationMatch

    • Riprova se è stata applicata una precondizione MetagenerationMatch alla chiamata.

  • Etag

    • Riprova se il metodo inserisce un etag nel corpo della richiesta JSON. Utilizzato in HMACKeyHandle.Update solo se è stato impostato HmacKeyMetadata.Etag.

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 o generation

    • Riprovare se è stato trasmesso ifGenerationMatch o generation come opzione al metodo.

  • ifMetagenerationMatch

    • Riprova se è stato trasmesso ifMetagenerationMatch come opzione.

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 di getaddrinfo.
    • 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 o generation

    • Riprovare se è stato trasmesso ifGenerationMatch o generation come opzione al metodo. Spesso, i metodi accettano solo uno di questi due parametri.

  • ifMetagenerationMatch

    • Riprova se è stato trasmesso ifMetagenerationMatch come opzione.

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 o if_generation_match è stato trasmesso come argomento al metodo. Spesso i metodi accettano solo uno di questi due parametri.

  • DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED

    • Riprova se if_metageneration_match è stato trasmesso come argomento al metodo.

  • DEFAULT_RETRY_IF_ETAG_IN_JSON

    • Riprova se il metodo inserisce un etag nel corpo della richiesta JSON. Per HMACKeyMetadata.update(), ciò significa che l'etag deve essere impostato sull'oggetto HMACKeyMetadata stesso. Per il metodo set_iam_policy() su altre classi, significa che l'etag deve essere impostato nell'argomento "policy" passato al metodo.

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 o generation

    • Riprova se il parametro generation o if_generation_match viene trasmesso come argomento al metodo. Spesso i metodi accettano solo uno di questi due parametri.

  • if_metageneration_match

    • Riprova se il parametro if_metageneration_match viene trasmesso come opzione.

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 corsi google::cloud::storage::LimitedErrorCountRetryPolicy e google::cloud::storage::LimitedTimeRetryPolicy. Puoi fornire la tua classe, che deve implementare l'interfaccia google::cloud::RetryPolicy.

  • google::cloud::storage::BackoffPolicyOption: la libreria fornisce il corso google::cloud::storage::ExponentialBackoffPolicy. Puoi fornire la tua classe, che deve implementare l'interfaccia google::cloud::storage::BackoffPolicy.

  • google::cloud::storage::IdempotencyPolicyOption: la libreria fornisce i corsi google::cloud::storage::StrictIdempotencyPolicy e google::cloud::storage::AlwaysRetryIdempotencyPolicy. Puoi fornire la tua classe, che deve implementare l'interfaccia google::cloud::storage::IdempotencyPolicy.

Per ulteriori informazioni, consulta la documentazione di riferimento sulla libreria client C++. 

namespace gcs = ::google::cloud::storage;
// Create the client configuration:
auto options = google::cloud::Options{};
// Retries only idempotent operations.
options.set<gcs::IdempotencyPolicyOption>(
    gcs::StrictIdempotencyPolicy().clone());
// On error, it backs off for a random delay between [1, 3] seconds, then [3,
// 9] seconds, then [9, 27] seconds, etc. The backoff time never grows larger
// than 1 minute.
options.set<gcs::BackoffPolicyOption>(
    gcs::ExponentialBackoffPolicy(
        /*initial_delay=*/std::chrono::seconds(1),
        /*maximum_delay=*/std::chrono::minutes(1),
        /*scaling=*/3.0)
        .clone());
// Retries all operations for up to 5 minutes, including any backoff time.
options.set<gcs::RetryPolicyOption>(
    gcs::LimitedTimeRetryPolicy(std::chrono::minutes(5)).clone());
return gcs::Client(std::move(options));

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.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
	"github.com/googleapis/gax-go/v2"
)

// configureRetries configures a custom retry strategy for a single API call.
func configureRetries(w io.Writer, bucket, object string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	// Configure retries for all operations using this ObjectHandle. Retries may
	// also be configured on the BucketHandle or Client types.
	o := client.Bucket(bucket).Object(object).Retryer(
		// Use WithBackoff to control the timing of the exponential backoff.
		storage.WithBackoff(gax.Backoff{
			// Set the initial retry delay to a maximum of 2 seconds. The length of
			// pauses between retries is subject to random jitter.
			Initial: 2 * time.Second,
			// Set the maximum retry delay to 60 seconds.
			Max: 60 * time.Second,
			// Set the backoff multiplier to 3.0.
			Multiplier: 3,
		}),
		// Use WithPolicy to customize retry so that all requests are retried even
		// if they are non-idempotent.
		storage.WithPolicy(storage.RetryAlways),
	)

	// Use context timeouts to set an overall deadline on the call, including all
	// potential retries.
	ctx, cancel := context.WithTimeout(ctx, 500*time.Second)
	defer cancel()

	// Delete an object using the specified retry policy.
	if err := o.Delete(ctx); err != nil {
		return fmt.Errorf("Object(%q).Delete: %w", object, err)
	}
	fmt.Fprintf(w, "Blob %v deleted with a customized retry strategy.\n", object)
	return nil
}

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:


import com.google.api.gax.retrying.RetrySettings;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import com.google.cloud.storage.StorageRetryStrategy;
import org.threeten.bp.Duration;

public final class ConfigureRetries {
  public static void main(String[] args) {
    String bucketName = "my-bucket";
    String blobName = "blob/to/delete";
    deleteBlob(bucketName, blobName);
  }

  static void deleteBlob(String bucketName, String blobName) {
    // Customize retry behavior
    RetrySettings retrySettings =
        StorageOptions.getDefaultRetrySettings()
            .toBuilder()
            // Set the max number of attempts to 10 (initial attempt plus 9 retries)
            .setMaxAttempts(10)
            // Set the backoff multiplier to 3.0
            .setRetryDelayMultiplier(3.0)
            // Set the max duration of all attempts to 5 minutes
            .setTotalTimeout(Duration.ofMinutes(5))
            .build();

    StorageOptions alwaysRetryStorageOptions =
        StorageOptions.newBuilder()
            // Customize retry so all requests are retried even if they are non-idempotent.
            .setStorageRetryStrategy(StorageRetryStrategy.getUniformStorageRetryStrategy())
            // provide the previously configured retrySettings
            .setRetrySettings(retrySettings)
            .build();

    // Instantiate a client
    Storage storage = alwaysRetryStorageOptions.getService();

    // Delete the blob
    BlobId blobId = BlobId.of(bucketName, blobName);
    boolean success = storage.delete(blobId);

    System.out.printf(
        "Deletion of Blob %s completed %s.%n", blobId, success ? "successfully" : "unsuccessfully");
  }
}

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.

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage({
  retryOptions: {
    // If this is false, requests will not retry and the parameters
    // below will not affect retry behavior.
    autoRetry: true,
    // The multiplier by which to increase the delay time between the
    // completion of failed requests, and the initiation of the subsequent
    // retrying request.
    retryDelayMultiplier: 3,
    // The total time between an initial request getting sent and its timeout.
    // After timeout, an error will be returned regardless of any retry attempts
    // made during this time period.
    totalTimeout: 500,
    // The maximum delay time between requests. When this value is reached,
    // retryDelayMultiplier will no longer be used to increase delay time.
    maxRetryDelay: 60,
    // The maximum number of automatic retries attempted before returning
    // the error.
    maxRetries: 5,
    // Will respect other retry settings and attempt to always retry
    // conditionally idempotent operations, regardless of precondition
    idempotencyStrategy: IdempotencyStrategy.RetryAlways,
  },
});
console.log(
  'Functions are customized to be retried according to the following parameters:'
);
console.log(`Auto Retry: ${storage.retryOptions.autoRetry}`);
console.log(
  `Retry delay multiplier: ${storage.retryOptions.retryDelayMultiplier}`
);
console.log(`Total timeout: ${storage.retryOptions.totalTimeout}`);
console.log(`Maximum retry delay: ${storage.retryOptions.maxRetryDelay}`);
console.log(`Maximum retries: ${storage.retryOptions.maxRetries}`);
console.log(
  `Idempotency strategy: ${storage.retryOptions.idempotencyStrategy}`
);

async function deleteFileWithCustomizedRetrySetting() {
  await storage.bucket(bucketName).file(fileName).delete();
  console.log(`File ${fileName} deleted with a customized retry strategy.`);
}

deleteFileWithCustomizedRetrySetting();

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.

from google.cloud import storage
from google.cloud.storage.retry import DEFAULT_RETRY

def configure_retries(bucket_name, blob_name):
    """Configures retries with customizations."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"
    # The ID of your GCS object
    # blob_name = "your-object-name"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    # Customize retry with a deadline of 500 seconds (default=120 seconds).
    modified_retry = DEFAULT_RETRY.with_deadline(500.0)
    # Customize retry with an initial wait time of 1.5 (default=1.0).
    # Customize retry with a wait time multiplier per iteration of 1.2 (default=2.0).
    # Customize retry with a maximum wait time of 45.0 (default=60.0).
    modified_retry = modified_retry.with_delay(initial=1.5, multiplier=1.2, maximum=45.0)

    # blob.delete() uses DEFAULT_RETRY_IF_GENERATION_SPECIFIED by default.
    # Override with modified_retry so the function retries even if the generation
    # number is not specified.
    print(
        f"The following library method is customized to be retried according to the following configurations: {modified_retry}"
    )

    blob.delete(retry=modified_retry)
    print(f"Blob {blob_name} deleted with a customized retry strategy.")

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.

def configure_retries bucket_name: nil, file_name: nil
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The ID of your GCS object
  # file_name = "your-file-name"

  require "google/cloud/storage"

  # Creates a client
  storage = Google::Cloud::Storage.new(

    # The maximum number of automatic retries attempted before returning
    # the error.
    #
    # Customize retry configuration with the maximum retry attempt of 5.
    retries: 5,

    # The total time in seconds that requests are allowed to keep being retried.
    # After max_elapsed_time, an error will be returned regardless of any
    # retry attempts made during this time period.
    #
    # Customize retry configuration with maximum elapsed time of 500 seconds.
    max_elapsed_time: 500,

    # The initial interval between the completion of failed requests, and the
    # initiation of the subsequent retrying request.
    #
    # Customize retry configuration with an initial interval of 1.5 seconds.
    base_interval: 1.5,

    # The maximum interval between requests. When this value is reached,
    # multiplier will no longer be used to increase the interval.
    #
    # Customize retry configuration with maximum interval of 45.0 seconds.
    max_interval: 45,

    # The multiplier by which to increase the interval between the completion
    # of failed requests, and the initiation of the subsequent retrying request.
    #
    # Customize retry configuration with an interval multiplier per iteration of 1.2.
    multiplier: 1.2
  )

  # Uses the retry configuration set during the client initialization above with 5 retries
  file = storage.service.get_file bucket_name, file_name

  # Maximum retry attempt can be overridden for each operation using options parameter.
  storage.service.delete_file bucket_name, file_name, options: { retries: 4 }
  puts "File #{file.name} deleted with a customized retry strategy."
end

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