Wiederholungsstrategie

Auf dieser Seite wird beschrieben, wie Cloud Storage-Tools fehlgeschlagene Anfragen wiederholen und wie Sie das Verhalten von Wiederholungsversuchen anpassen. Außerdem werden Überlegungen zur Wiederholung von Anfragen beschrieben.

Übersicht

Es gibt zwei Faktoren, die bestimmen, ob eine Anfrage sicher wiederholt werden kann:

1. Die Antwort, die Sie von der Anfrage erhalten.
2. Die Idempotenz der Anfrage.

Antwort

Die Antwort, die Sie von Ihrer Anfrage erhalten, gibt an, ob es sinnvoll ist, die Anfrage zu wiederholen. Antworten auf vorübergehende Probleme sind in der Regel wiederholbar. Andererseits zeigen Antworten auf permanente Fehler, dass Sie Änderungen wie Autorisierungs- oder Konfigurationsänderungen vornehmen müssen, bevor es sinnvoll ist, die Anfrage noch einmal zu senden. Die folgenden Antworten weisen auf vorübergehende Probleme hin, die wiederholt werden können:

• HTTP-Antwortcodes 408, 429 und 5xx.
• Socket-Zeitüberschreitungen und getrennte TCP-Verbindungen

Weitere Informationen finden Sie in den Status- und Fehlercodes für JSON und XML.

Idempotenz

Eine idempotente Anfrage bedeutet, dass sie wiederholt ausgeführt werden kann und die ausgewählte Ressource immer im selben Endzustand belässt. Zum Beispiel sind Auflistungsanfragen immer idempotent, weil solche Anfragen keine Ressourcen ändern. Andererseits ist das Erstellen einer neuen Pub/Sub-Benachrichtigung niemals idempotent, da bei jeder erfolgreichen Anfrage eine neue Benachrichtigungs-ID erstellt wird.

Die folgenden Beispiele zeigen Bedingungen, die einen Vorgang idempotent machen:

• Der Vorgang hat auch dann sichtbare Auswirkungen auf die Zielressource, wenn er kontinuierlich angefragt wird.

• Der Vorgang ist nur einmal erfolgreich.

• Der Vorgang hat keine sichtbaren Auswirkungen auf den Status der Zielressource.

Wenn Sie eine wiederholbare Antwort erhalten, sollten Sie die Idempotenz der Anfrage berücksichtigen, da Wiederholungsanfragen, die nicht idempotent sind, zu Race-Bedingungen und anderen Konflikten führen können.

Bedingte Idempotenz

Teilmengen von Anfragen sind bedingt idempotent. Das bedeutet, dass sie nur idempotent sind, wenn sie bestimmte optionale Argumente enthalten. Vorgänge, für die ein bedingter Versuch wiederholt werden muss, sollten nur dann wiederholt werden, wenn der Bedingungsfall erfolgreich ist. Cloud Storage akzeptiert Vorbedingungen und ETags als Bedingungsfälle für Anfragen.

Idempotenz von Vorgängen

In der folgenden Tabelle sind die Cloud Storage-Vorgänge aufgeführt, die unter die einzelnen Kategorien der Idempotenz fallen.

Idempotenz	Vorgänge
Immer idempotent	Alle get- und list-Anfragen Buckets einfügen oder löschen IAM-Richtlinien und -Berechtigungen für Test-Buckets Aufbewahrungsrichtlinien sperren HMAC-Schlüssel oder Pub/Sub-Benachrichtigungen löschen
Bedingt idempotent	Update-/Patch-Anfragen für Buckets mit IfMetagenerationMatch^1 oder etag^1 als HTTP-Vorbedingung Aktualisierungs-/Patchanfragen für Objekte mit IfMetagenerationMatch^1 oder etag^1 als HTTP-Vorbedingung Bucket-IAM-Richtlinie mit etag^1 als HTTP-Vorbedingung oder im Ressourcentext festlegen HMAC-Schlüssel mit etag^1 als HTTP-Vorbedingung oder im Ressourcentext aktualisieren Mit ifGenerationMatch^1 Objekte einfügen, kopieren, verfassen oder neu schreiben Objekt mit ifGenerationMatch^1 löschen (oder mit einer Generierungsnummer für Objektversionen)
Nie idempotent	HMAC-Schlüssel erstellen Pub/Sub-Benachrichtigung erstellen Patch-/Updateanfragen für Bucket- und Objekt-ACLs oder Standard-Objekt-ACLs erstellen, löschen oder senden

¹Dieses Feld kann in der JSON API verwendet werden. Informationen zu Feldern, die in den Clientbibliotheken verwendet werden können, finden Sie in der entsprechenden Dokumentation zur Clientbibliothek.

Wie Cloud Storage-Tools Wiederholungsstrategien implementieren

Console

Die Google Cloud Console sendet in Ihrem Namen Anfragen an Cloud Storage und sorgt für die Bearbeitung aller erforderlichen Backoffs.

Befehlszeile

gcloud storage-Befehle wiederholen die Fehler, die im Abschnitt Antwort aufgeführt sind, ohne dass Sie zusätzliche Maßnahmen ergreifen müssen. Bei folgenden Fehlern müssen Sie unter Umständen Maßnahmen ergreifen:

• Ungültige Anmeldedaten oder unzureichende Berechtigungen.

• Das Netzwerk ist nicht erreichbar, da Probleme mit der Proxykonfiguration aufgetreten sind.

Bei wiederholbaren Fehlern wiederholt die gcloud CLI Anfragen nach der Strategie eines abgeschnittenen binären exponentiellen Backoffs: Die Standardanzahl maximaler Wiederholungsversuche beträgt 32 für die gcloud CLI.

Clientbibliotheken

C++

Standardmäßig unterstützen die Vorgänge Wiederholungsversuche für die folgenden HTTP-Fehlercodes sowie für alle Socket-Fehler, die darauf hinweisen, dass die Verbindung verloren gegangen ist oder nie erfolgreich hergestellt wurde.

• 408 Request Timeout
• 429 Too Many Requests
• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout

Alle Einstellungen für exponentielle Backoffs und Wiederholungsversuche in der C++-Bibliothek sind konfigurierbar. Wenn die in der Bibliothek implementierten Algorithmen Ihre Anforderungen nicht unterstützen, können Sie benutzerdefinierten Code bereitstellen, um Ihre eigenen Strategien zu implementieren.

Einstellung	Standardwert
Automatische Wiederholung	True
Maximale Dauer, die eine Anfrage wiederholt wird	15 Minuten
Erste Wartezeit (Backoff)	1 Sekunde
Multiplikator für die Wartezeit pro Ausführung	2
Maximale Wartezeit	5 Minuten

Standardmäßig wiederholt die C++-Bibliothek alle Operationen mit wiederholbaren Fehlern, auch solche, die nie idempotent sind und bei erfolgreicher Wiederholung mehrere Ressourcen löschen oder erstellen können. Wenn Sie nur idempotente Vorgänge wiederholen möchten, verwenden Sie die google::cloud::storage::StrictIdempotencyPolicy-Klasse.

C#

In der C#-Clientbibliothek wird exponentieller Backoff standardmäßig verwendet.

Go

Standardmäßig unterstützen Vorgänge Wiederholungsversuche für die folgenden Fehler:

• Verbindungsfehler:
  • io.ErrUnexpectedEOF: Dies kann aufgrund vorübergehender Netzwerkprobleme auftreten.
  • url.Error mit connection refused: Dies kann aufgrund vorübergehender Netzwerkprobleme auftreten.
  • url.Error mit connection reset by peer: Dies bedeutet, dass Google Cloud die Verbindung zurückgesetzt hat.
  • net.ErrClosed: Dies bedeutet, dass Google Cloud die Verbindung beendet hat.
• HTTP-Codes:
  • 408 Request Timeout
  • 429 Too Many Requests
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout
• Fehler, die die Schnittstelle Temporary() implementieren und den Wert err.Temporary() == true angeben
• Alle oben genannten Fehler, die mit Go 1.13-Fehlerverpackung verpackt wurden

Alle Einstellungen für exponentielle Backoffs in der Go-Bibliothek können konfiguriert werden. Standardmäßig verwenden Vorgänge in Go die folgenden Einstellungen für den exponentiellen Backoff (Standardeinstellungen werden von gax übernommen):

Einstellung	Standardwert (in Sekunden)
Automatische Wiederholung	Wahr, wenn idempotent
Maximale Anzahl an Versuchen	Kein Limit
Verzögerung für erste Wiederholung:	1 Sekunde
Multiplikator für die Verzögerung der Wiederholung	2,0
Maximale Wiederholungsverzögerung	30 Sekunden
Gesamtzeitüberschreitung (fortsetzbarer Uploadblock)	32 Sekunden
Gesamtzeitüberschreitung (alle anderen Vorgänge)	Kein Limit

Der Wiederholungsversuch wird in der Regel unbegrenzt fortgesetzt, es sei denn, der Steuerungskontext wird abgebrochen, der Client wird geschlossen oder ein nicht vorübergehender Fehler wird empfangen. Verwenden Sie Kontextzeitüberschreitungen oder einen Abbruch, um zu verhindern, dass Wiederholungsversuche fortgesetzt werden. Die einzige Ausnahme bei diesem Verhalten ist, wenn fortsetzbare Uploads mit Writer durchgeführt werden, wobei die Daten groß genug sind, dass mehrere Anfragen erforderlich sind. In diesem Szenario tritt bei jedem Block eine Zeitüberschreitung auf und beendet die Wiederholung standardmäßig nach 32 Sekunden. Sie können das Standardzeitlimit anpassen, indem Sie Writer.ChunkRetryDeadline ändern.

Es gibt eine Teilmenge von Go-Vorgängen, die bedingt idempotent sind (bedingt sicher bei erneuter Wiederholung). Diese Vorgänge werden nur dann wiederholt, wenn sie bestimmte Bedingungen erfüllen:

• GenerationMatch oder Generation

  • Wiederholen Sie den Vorgang, wenn die Vorbedingung GenerationMatch auf den Aufruf angewendet wurde oder wenn ObjectHandle.Generation festgelegt wurde.

• MetagenerationMatch

  • Wiederholen Sie den Vorgang, wenn die Vorbedingung MetagenerationMatch auf den Aufruf angewendet wurde.

• Etag

  • Es kann wiederholt werden, wenn die Methode etag in den JSON-Anfragetext einfügt. Wird nur in HMACKeyHandle.Update verwendet, wenn HmacKeyMetadata.Etag festgelegt wurde.

RetryPolicy ist standardmäßig auf RetryPolicy.RetryIdempotent festgelegt. Unter Wiederholungen anpassen finden Sie Beispiele zum Ändern des Standardverhaltens bei Wiederholungsversuchen.

Java

Standardmäßig unterstützen Vorgänge Wiederholungsversuche für die folgenden Fehler:

• Verbindungsfehler:
  • Connection reset by peer: Dies bedeutet, dass Google Cloud die Verbindung zurückgesetzt hat.
  • Unexpected connection closure: Dies bedeutet, dass Google Cloud die Verbindung beendet hat.
• HTTP-Codes:
  • 408 Request Timeout
  • 429 Too Many Requests
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

Alle Einstellungen für exponentielle Backoffs in der Java-Bibliothek können konfiguriert werden. Standardmäßig verwenden Vorgänge über Java für den exponentiellen Backoff die folgenden Einstellungen:

Einstellung	Standardwert (in Sekunden)
Automatische Wiederholung	Wahr, wenn idempotent
Maximale Anzahl an Versuchen	6
Verzögerung für erste Wiederholung:	1 Sekunde
Multiplikator für die Verzögerung der Wiederholung	2,0
Maximale Wiederholungsverzögerung	32 Sekunden
Zeitüberschreitung insgesamt	50 Sekunden
Anfängliche RPC-Zeitüberschreitung	50 Sekunden
RPC-Zeitüberschreitungsmultiplikator	1,0
Maximales RPC-Zeitlimit	50 Sekunden
Zeitüberschreitung beim Verbindungsaufbau	20 Sekunden
Lesezeitüberschreitung	20 Sekunden

Weitere Informationen zu den Einstellungen finden Sie in der Java-Referenzdokumentation für RetrySettings.Builder und HttpTransportOptions.Builder.

Es gibt eine Teilmenge von Java-Vorgängen, die bedingt idempotent sind (bedingt sicher bei erneutem Versuch). Diese Vorgänge werden nur dann wiederholt, wenn sie bestimmte Argumente enthalten:

• ifGenerationMatch oder generation

  • Sicher für Wiederholung, wenn ifGenerationMatch oder generation als Option an die Methode übergeben wurde.

• ifMetagenerationMatch

  • Wiederholen Sie den Vorgang, wenn ifMetagenerationMatch als Option übergeben wurde.

StorageOptions.setStorageRetryStrategy ist standardmäßig auf StorageRetryStrategy#getDefaultStorageRetryStrategy festgelegt. Unter Wiederholungen anpassen finden Sie Beispiele zum Ändern des Standardverhaltens bei Wiederholungsversuchen.

Node.js

Standardmäßig unterstützen Vorgänge Wiederholungsversuche für die folgenden Fehlercodes:

• Verbindungsfehler:
  • EAI_again: Dies ist ein DNS-Lookup-Fehler. Weitere Informationen finden Sie in der Dokumentation zu getaddrinfo.
  • Connection reset by peer: Dies bedeutet, dass Google Cloud die Verbindung zurückgesetzt hat.
  • Unexpected connection closure: Dies bedeutet, dass Google Cloud die Verbindung beendet hat.
• HTTP-Codes:
  • 408 Request Timeout
  • 429 Too Many Requests
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

Alle Einstellungen für exponentielle Backoffs in der Node.js-Bibliothek können konfiguriert werden. Standardmäßig verwenden Vorgänge über Node.js die folgenden Einstellungen für den exponentiellen Backoff:

Einstellung	Standardwert (in Sekunden)
Automatische Wiederholung	Wahr, wenn idempotent
Maximale Anzahl an Wiederholungen	3
Anfängliche Wartezeit	1 Sekunde
Multiplikator für die Wartezeit pro Ausführung	2
Maximale Wartezeit	64 Sekunden
Standardfrist	600 Sekunden

Es gibt eine Teilmenge von Node.js-Vorgängen, die bedingt idempotent sind und unter bestimmten Bedingungen wiederholt werden können. Diese Vorgänge werden nur dann wiederholt, wenn sie bestimmte Argumente enthalten:

• ifGenerationMatch oder generation

  • Sicher für Wiederholung, wenn ifGenerationMatch oder generation als Option an die Methode übergeben wurde. Häufig akzeptieren Methoden nur einen dieser beiden Parameter.

• ifMetagenerationMatch

  • Wiederholen Sie den Vorgang, wenn ifMetagenerationMatch als Option übergeben wurde.

retryOptions.idempotencyStrategy ist standardmäßig auf IdempotencyStrategy.RetryConditional festgelegt. Unter Wiederholungen anpassen finden Sie Beispiele zum Ändern des Standardverhaltens bei Wiederholungsversuchen.

PHP

In der PHP-Clientbibliothek wird exponentieller Backoff standardmäßig verwendet.

Python

Standardmäßig unterstützen Vorgänge Wiederholungsversuche für die folgenden Fehlercodes:

• Verbindungsfehler:
  • requests.exceptions.ConnectionError
  • requests.exceptions.ChunkedEncodingError (nur für Vorgänge, die Nutzlastdaten abrufen oder an Objekte senden, z. B. Uploads und Downloads)
  • ConnectionError
• HTTP-Codes:
  • 408 Request Timeout
  • 429 Too Many Requests
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

Für Vorgänge über Python werden die folgenden Standardeinstellungen für exponentielle Backoffs verwendet:

Einstellung	Standardwert (in Sekunden)
Automatische Wiederholung	Wahr, wenn idempotent
Anfängliche Wartezeit	1
Multiplikator für die Wartezeit pro Ausführung	2
Maximale Wartezeit	60
Standardfrist	120

Es gibt eine Teilmenge von Python-Vorgängen, die bedingt idempotent sind und unter bestimmten Bedingungen wiederholt werden können, wenn sie bestimmte Argumente enthalten. Diese Vorgänge werden nur dann wiederholt, wenn ein Bedingungsfall erfolgreich ist:

• DEFAULT_RETRY_IF_GENERATION_SPECIFIED

  • Sicher für Wiederholung, wenn generation oder if_generation_match als Argument an die Methode übergeben wurde. Häufig akzeptieren Methoden nur einen dieser beiden Parameter.

• DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED

  • Sicher für Wiederholung, wenn if_metageneration_match als Argument an die Methode übergeben wurde.

• DEFAULT_RETRY_IF_ETAG_IN_JSON

  • Es kann wiederholt werden, wenn die Methode etag in den JSON-Anfragetext einfügt. Für HMACKeyMetadata.update() bedeutet dies, dass das ETag für das HMACKeyMetadata-Objekt selbst festgelegt werden muss. Für die set_iam_policy()-Methode in anderen Klassen bedeutet dies, dass das ETag im Argument "policy" festgelegt werden muss, das an die Methode übergeben wird.

Ruby

Standardmäßig unterstützen Vorgänge Wiederholungsversuche für die folgenden Fehlercodes:

• Verbindungsfehler:
  • SocketError
  • HTTPClient::TimeoutError
  • Errno::ECONNREFUSED
  • HTTPClient::KeepAliveDisconnected
• HTTP-Codes:
  • 408 Request Timeout
  • 429 Too Many Requests
  • 5xx Server Error

Alle Einstellungen für exponentielle Backoffs in der Ruby-Clientbibliothek können konfiguriert werden. Standardmäßig verwenden Vorgänge über die Ruby-Clientbibliothek die folgenden Einstellungen für den exponentiellen Backoff:

Einstellung	Standardwert
Automatische Wiederholung	True
Maximale Anzahl an Wiederholungen	3
Anfängliche Wartezeit	1 Sekunde
Multiplikator für die Wartezeit pro Ausführung	2
Maximale Wartezeit	60 Sekunden
Standardfrist	900 Sekunden

Es gibt eine Teilmenge von Ruby-Vorgängen, die bedingt idempotent sind und unter bestimmten Bedingungen wiederholt werden können, wenn sie bestimmte Argumente enthalten:

• if_generation_match oder generation

  • Sicher für Wiederholung, wenn der Parameter generation oder if_generation_match als Argument an die Methode übergeben wird. Häufig akzeptieren Methoden nur einen dieser beiden Parameter.

• if_metageneration_match

  • Wiederholen Sie den Vorgang, wenn der Parameter if_metageneration_match als Option übergeben wird.

Standardmäßig werden alle idempotenten Vorgänge wiederholt, bedingte idempotente Vorgänge nur dann, wenn der Bedingungsfall erfolgreich ist. Nicht-idempotente Vorgänge werden nicht wiederholt. Unter Wiederholungen anpassen finden Sie Beispiele zum Ändern des Standardverhaltens bei Wiederholungsversuchen.

REST APIs

Wenn Sie die JSON- oder XML API direkt aufrufen, sollten Sie mit dem exponentiellen Backoff Ihre eigene Wiederholungsstrategie implementieren.

Wiederholungsversuche anpassen

Console

Über die Google Cloud Console können Sie das Verhalten von Wiederholungsversuchen nicht anpassen.

Befehlszeile

Bei gcloud storage-Befehlen können Sie die Wiederholungsstrategie steuern, indem Sie eine benannte Konfiguration erstellen und einige oder alle der folgenden Attribute festlegen:

• base_retry_delay
• exponential_sleep_multiplier
• max_retries
• max_retry_delay

Anschließend wenden Sie die definierte Konfiguration entweder einzeln pro Befehl mit dem projektweiten --configuration-Flag oder für alle gcloud-Befehle mit dem gcloud config set-Befehl an.

Clientbibliotheken

C++

Zum Anpassen des Wiederholungsverhaltens geben Sie Werte für die folgenden Optionen an, wenn Sie das Objekt google::cloud::storage::Client initialisieren:

• google::cloud::storage::RetryPolicyOption: Die Bibliothek bietet die Klassen google::cloud::storage::LimitedErrorCountRetryPolicy und google::cloud::storage::LimitedTimeRetryPolicy. Sie können Ihre eigene Klasse angeben, die die Schnittstelle google::cloud::RetryPolicy implementieren muss.

• google::cloud::storage::BackoffPolicyOption: Die Bibliothek bietet die Klasse google::cloud::storage::ExponentialBackoffPolicy. Sie können Ihre eigene Klasse angeben, die die Schnittstelle google::cloud::storage::BackoffPolicy implementieren muss.

• google::cloud::storage::IdempotencyPolicyOption: Die Bibliothek stellt die Klassen google::cloud::storage::StrictIdempotencyPolicy und google::cloud::storage::AlwaysRetryIdempotencyPolicy bereit. Sie können Ihre eigene Klasse angeben, die die Schnittstelle google::cloud::storage::IdempotencyPolicy implementieren muss.

Weitere Informationen finden Sie in der Referenzdokumentation zur C++-Clientbibliothek.

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#

Sie können die von der C#-Clientbibliothek verwendete Standard-Wiederholungsstrategie nicht anpassen.

Go

Wenn Sie einen Storage-Client initialisieren, wird eine Standardkonfiguration für Wiederholungsversuche festgelegt. Wenn die Optionen nicht überschrieben werden, werden sie in der Konfiguration auf die Standardwerte gesetzt. Nutzer können ein nicht standardmäßiges Wiederholungsverhalten für einen einzelnen Bibliotheksaufruf (mit BucketHandle.Retryer und ObjectHandle.Retryer) oder für alle Aufrufe konfigurieren, die von einem Client (mit Client.SetRetry) gemacht werden. Um das Wiederholungsverhalten zu ändern, übergeben Sie die relevanten RetryOptions an eine dieser Methoden.

Im folgenden Codebeispiel erfahren Sie, wie Sie das Wiederholungsverhalten anpassen.

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

Beim Initialisieren von Storage wird auch eine Instanz von RetrySettings initialisiert. Wenn die Optionen nicht überschrieben werden, werden sie in RetrySettings auf die Standardwerte gesetzt. Um das Standardverhalten für die automatische Wiederholung zu ändern, übergeben Sie die benutzerdefinierte StorageRetryStrategy an die StorageOptions, die zum Erstellen der Storage-Instanz verwendet werden. Um einen der anderen skalaren Parameter zu ändern, übergeben Sie benutzerdefinierte RetrySettings an die StorageOptions, die zum Erstellen der Storage-Instanz verwendet werden.

Im folgenden Beispiel erfahren Sie, wie Sie das Wiederholungsverhalten anpassen:

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

Beim Initialisieren von Cloud Storage wird auch eine retryOptions-Konfigurationsdatei initialisiert. Wenn die Optionen nicht überschrieben werden, werden sie in der Konfiguration auf die Standardwerte gesetzt. Um das Standardverhalten für Wiederholungsversuche zu ändern, übergeben Sie bei der Initialisierung die benutzerdefinierte Wiederholungskonfiguration retryOptions an den Speicherkonstruktor. Die Node.js-Clientbibliothek kann automatisch Backoff-Strategien verwenden, um Anfragen mit dem Parameter autoRetry noch einmal zu senden.

Im folgenden Codebeispiel erfahren Sie, wie Sie das Wiederholungsverhalten anpassen.

/**
 * 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

Sie können die Standard-Wiederholungsstrategie, die von der PHP-Clientbibliothek verwendet wird, nicht anpassen.

Python

Zum Ändern des Standardverhaltens für Wiederholungsversuche erstellen Sie eine Kopie des google.cloud.storage.retry.DEFAULT_RETRY-Objekts. Dazu rufen Sie es mit der Methode with_XXX auf. Die Python-Clientbibliothek verwendet automatisch Backoff-Strategien, um Anfragen zu wiederholen, wenn Sie den Parameter DEFAULT_RETRY einfügen.

Beachten Sie, dass with_predicate nicht für Vorgänge unterstützt wird, die Nutzlastdaten abrufen oder senden, z. B. Uploads und Downloads. Es wird empfohlen, Attribute einzeln zu ändern. Weitere Informationen finden Sie in der google-api-core Retry-Referenz.

Zum Konfigurieren Ihrer eigenen bedingten Wiederholungsversuche erstellen Sie ein ConditionalRetryPolicy-Objekt und verpacken das benutzerdefinierte Retry-Objekt mit DEFAULT_RETRY_IF_GENERATION_SPECIFIED, DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED oder DEFAULT_RETRY_IF_ETAG_IN_JSON.

Im folgenden Codebeispiel erfahren Sie, wie Sie das Wiederholungsverhalten anpassen.

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

Beim Initialisieren des Speicherclients werden alle Wiederholungskonfigurationen auf die Werte in der obigen Tabelle festgelegt. Um das Standardverhalten für Wiederholungsversuche zu ändern, übergeben Sie die Wiederholungskonfigurationen während der Initialisierung des Storage-Clients.

Übergeben Sie retries im options-Parameter des Vorgangs, um die Anzahl der Wiederholungen für einen bestimmten Vorgang zu überschreiben.

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

REST APIs

Verwenden Sie den exponentiellen Backoff-Algorithmus, um Ihre eigene Wiederholungsstrategie zu implementieren.

Exponentieller Backoff-Algorithmus

Ein exponentieller Backoff-Algorithmus wiederholt Anfragen mit exponentiell zunehmenden Wartezeiten zwischen den Anfragen bis zur maximalen Backoff-Zeit. Im Allgemeinen sollten Sie den exponentiellen Backoff mit Jitter verwenden, um Anfragen zu wiederholen, die sowohl die Antwort- als auch die Idempotenzkriterien erfüllen. Best Practices für die Implementierung automatischer Wiederholungsversuche mit exponentiellem Backoff finden Sie unter Kaskadierende Fehler beheben.

Nächste Schritte

• Anfragen im Storage Transfer Service mit Java oder Python wiederholen
• Weitere Informationen zu Vorbedingungen für Anfragen