Strategie für Wiederholungen

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:

• Die Antwort, die Sie von der Anfrage erhalten.

• Die Idempotenz der Anfrage.

Antwort

Die Antwort, die Sie von Ihrer Anfrage erhalten, gibt an, ob es sinnvoll ist, die Anfrage zu wiederholen. Antworten in Bezug auf vorübergehende Probleme sind in der Regel wiederholbar. Andererseits weisen Antworten in Bezug auf dauerhafte Probleme darauf hin, dass Sie Änderungen vornehmen müssen, z. B. Autorisierungs- oder Konfigurationsänderungen, bevor es sinnvoll ist, die Anfrage noch einmal zu senden. Die folgenden Antworten weisen auf vorübergehende Probleme hin, bei denen eine Wiederholung sinnvoll ist:

• HTTP-Antwortcodes 408, 429 und 5xx
• Socket-Zeitlimits und getrennte TCP-Verbindungen

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

Idempotenz

Idempotente Anfragen können wiederholt ausgeführt werden, ohne den Endzustand der Zielressource zu ändern. Das Ergebnis ist jedes Mal derselbe Endzustand. Zum Beispiel sind list-Vorgänge 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 das Wiederholen von Anfragen, die nicht idempotent sind, zu Race-Bedingungen und anderen Konflikten führen kann.

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 eine Wiederholung bedingt sicher ist, 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-Benachrichtigung löschen
Bedingt idempotent	Aktualisierungs-/Patch-Anfragen für Buckets mit IfMetagenerationMatch^1 oder etag^1 als HTTP-Vorbedingung Aktualisierungs-/Patch-Anfragen 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 (oder mit einer Generationsnummer für Objektversionen) löschen
Nie idempotent	HMAC-Schlüssel erstellen Pub/Sub-Benachrichtigung erstellen Patch-/Aktualisierungsanfragen 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. Etwa bei den 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 mithilfe einer 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 exponentiellen Backoff 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	Wahr
Maximale Dauer, die eine Anfrage wiederholt wird	15 Minuten
Erste Wartezeit (Backoff)	1 Sekunde
Multiplikator für die Wartezeit pro Iteration	2
Maximale Wartezeit	5 Minuten

Standardmäßig wiederholt die C++-Bibliothek alle Vorgänge 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 exponentiellen Backoff 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
Verzögerungsmultiplikator der Wiederholung	2,0
Maximale Wiederholungsverzögerung	30 Sekunden
Gesamtzeitlimit (fortsetzbarer Uploadblock)	32 Sekunden
Gesamtzeitlimit (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 Kontextzeitlimits 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 wiederholbar). Diese Vorgänge werden nur dann wiederholt, wenn sie bestimmte Bedingungen erfüllen:

• GenerationMatch oder Generation

  • Sicher wiederholbar, wenn die Vorbedingung GenerationMatch auf den Aufruf angewendet wurde oder wenn ObjectHandle.Generation festgelegt wurde.

• MetagenerationMatch

  • Sicher wiederholbar, wenn die Vorbedingung MetagenerationMatch auf den Aufruf angewendet wurde.

• Etag

  • Sicher wiederholbar, wenn die Methode ein 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 exponentiellen Backoff 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
Verzögerungsmultiplikator der Wiederholung	2,0
Maximale Wiederholungsverzögerung	32 Sekunden
Zeitlimit insgesamt	50 Sekunden
Anfängliches RPC-Zeitlimit	50 Sekunden
RPC-Zeitlimit-Multiplikator	1,0
Maximales RPC-Zeitlimit	50 Sekunden
Zeitlimit beim Verbindungsaufbau	20 Sekunden
Lesezeitlimit	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 wiederholbar). Diese Vorgänge werden nur dann wiederholt, wenn sie bestimmte Argumente enthalten:

• ifGenerationMatch oder generation

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

• ifMetagenerationMatch

  • Sicher wiederholbar, 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 exponentiellen Backoff 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 Iteration	2
Maximale Wartezeit	64 Sekunden
Standardfrist	600 Sekunden

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

• ifGenerationMatch oder generation

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

• ifMetagenerationMatch

  • Sicher wiederholbar, 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.

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

• Verbindungsfehler:
  • connetion-refused: Dies kann aufgrund vorübergehender Netzwerkprobleme auftreten.
  • connection-reset: Dies bedeutet, dass Google Cloud die Verbindung zurückgesetzt hat.
• HTTP-Codes:
  • 200: für Fälle mit teilweisem Download
  • 408 Request Timeout
  • 429 Too Many Requests
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

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

Einstellung	Standardwert (in Sekunden)
Automatische Wiederholung	Wahr, wenn idempotent
Verzögerung für erste Wiederholung:	1 Sekunde
Verzögerungsmultiplikator der Wiederholung	2,0
Maximale Wiederholungsverzögerung	60 Sekunden
Zeitlimit für Anfragen	0 mit REST, 60 mit gRPC
Standardanzahl der Wiederholungen	3

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

• ifGenerationMatch oder generation

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

• ifMetagenerationMatch

  • Sicher wiederholbar, wenn ifMetagenerationMatch als Option übergeben wurde.

Beim Erstellen von StorageClient wird standardmäßig die StorageClient::RETRY_IDEMPOTENT-Strategie verwendet. Unter Wiederholungen anpassen finden Sie Beispiele zum Ändern des Standardverhaltens bei Wiederholungsversuchen.

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.client.ResponseNotReady
  • urllib3.exceptions.TimeoutError
• 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 exponentiellen Backoff verwendet:

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

Zusätzlich zu Cloud Storage-Vorgängen, die immer idempotent sind, werden die Vorgänge Objects: insert, Objects: delete und Objects: patch in der Python-Clientbibliothek standardmäßig automatisch wiederholt.

Es gibt eine Teilmenge von Python-Vorgängen, die bedingt idempotent sind (bedingt sicher wiederholbar), wenn sie bestimmte Argumente enthalten. Diese Vorgänge werden nur dann wiederholt, wenn ein Bedingungsfall erfolgreich ist:

• DEFAULT_RETRY_IF_GENERATION_SPECIFIED

  • Sicher wiederholbar, 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 wiederholbar, wenn if_metageneration_match als Argument an die Methode übergeben wurde.

• DEFAULT_RETRY_IF_ETAG_IN_JSON

  • Sicher wiederholbar, wenn die Methode ein 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 exponentiellen Backoff 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	Wahr
Maximale Anzahl an Wiederholungen	3
Anfängliche Wartezeit	1 Sekunde
Multiplikator für die Wartezeit pro Iteration	2
Maximale Wartezeit	60 Sekunden
Standardfrist	900 Sekunden

Es gibt eine Teilmenge von Ruby-Vorgängen, die bedingt idempotent sind (bedingt sicher wiederholbar), wenn sie bestimmte Argumente enthalten:

• if_generation_match oder generation

  • Sicher wiederholbar, 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

  • Sicher wiederholbar, wenn der Parameter if_metageneration_match als Option übergeben wird.

Standardmäßig werden alle idempotenten Vorgänge wiederholt, bedingt 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-Algorithmus 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:

Einstellung	Standardwert (in Sekunden)
base_retry_delay	1
exponential_sleep_multiplier	2
max_retries	32
max_retry_delay	32

Anschließend wenden Sie die definierte Konfiguration entweder einzeln pro Befehl mit dem projektweiten Flag --configuration oder für alle Google Cloud CLI-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 stellt die Klassen google::cloud::storage::LimitedErrorCountRetryPolicy und google::cloud::storage::LimitedTimeRetryPolicy bereit. Sie können Ihre eigene Klasse angeben, die die Schnittstelle google::cloud::RetryPolicy implementieren muss.

• google::cloud::storage::BackoffPolicyOption: Die Bibliothek stellt die Klasse google::cloud::storage::ExponentialBackoffPolicy bereit. 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 zu wiederholen.

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

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 Client oder einen einzelnen Vorgangsaufruf konfigurieren, indem sie Überschreibungsoptionen in einem Array übergeben.

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

use Google\Cloud\Storage\StorageClient;

/**
 * Configures retries with customizations.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function configure_retries(string $bucketName): void
{
    $storage = new StorageClient([
        // The maximum number of automatic retries attempted before returning
        // the error.
        // Default: 3
        'retries' => 10,

        // Exponential backoff settings
        // Retry strategy to signify that we never want to retry an operation
        // even if the error is retryable.
        // Default: StorageClient::RETRY_IDEMPOTENT
        'retryStrategy' => StorageClient::RETRY_ALWAYS,

        // Executes a delay
        // Defaults to utilizing `usleep`.
        // Function signature should match: `function (int $delay) : void`.
        // This function is mostly used internally, so the tests don't wait
        // the time of the delay to run.
        'restDelayFunction' => function ($delay) {
            usleep($delay);
        },

        // Sets the conditions for determining how long to wait between attempts to retry.
        // Function signature should match: `function (int $attempt) : int`.
        // Allows to change the initial retry delay, retry delay multiplier and maximum retry delay.
        'restCalcDelayFunction' => fn ($attempt) => ($attempt + 1) * 100,

        // Sets the conditions for whether or not a request should attempt to retry.
        // Function signature should match: `function (\Exception $ex) : bool`.
        'restRetryFunction' => function (\Exception $e) {
            // Custom logic: ex. only retry if the error code is 404.
            return $e->getCode() === 404;
        },

        // Runs after the restRetryFunction. This might be used to simply consume the
        // exception and $arguments b/w retries. This returns the new $arguments thus allowing
        // modification on demand for $arguments. For ex: changing the headers in b/w retries.
        'restRetryListener' => function (\Exception $e, $retryAttempt, &$arguments) {
            // logic
        },
    ]);
    $bucket = $storage->bucket($bucketName);
    $operationRetriesOverrides = [
        // The maximum number of automatic retries attempted before returning
        // the error.
        // Default: 3
        'retries' => 10,

        // Exponential backoff settings
        // Retry strategy to signify that we never want to retry an operation
        // even if the error is retryable.
        // Default: StorageClient::RETRY_IDEMPOTENT
        'retryStrategy' => StorageClient::RETRY_ALWAYS,

        // Executes a delay
        // Defaults to utilizing `usleep`.
        // Function signature should match: `function (int $delay) : void`.
        // This function is mostly used internally, so the tests don't wait
        // the time of the delay to run.
        'restDelayFunction' => function ($delay) {
            usleep($delay);
        },

        // Sets the conditions for determining how long to wait between attempts to retry.
        // Function signature should match: `function (int $attempt) : int`.
        // Allows to change the initial retry delay, retry delay multiplier and maximum retry delay.
        'restCalcDelayFunction' => fn ($attempt) => ($attempt + 1) * 100,

        // Sets the conditions for whether or not a request should attempt to retry.
        // Function signature should match: `function (\Exception $ex) : bool`.
        'restRetryFunction' => function (\Exception $e) {
            // Custom logic: ex. only retry if the error code is 404.
            return $e->getCode() === 404;
        },

        // Runs after the restRetryFunction. This might be used to simply consume the
        // exception and $arguments b/w retries. This returns the new $arguments thus allowing
        // modification on demand for $arguments. For ex: changing the headers in b/w retries.
        'restRetryListener' => function (\Exception $e, $retryAttempt, &$arguments) {
            // logic
        },
    ];
    foreach ($bucket->objects($operationRetriesOverrides) as $object) {
        printf('Object: %s' . PHP_EOL, $object->name());
    }
}

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_BEHAVIOR 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 an Objekte 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 timeout of 500 seconds (default=120 seconds).
    modified_retry = DEFAULT_RETRY.with_timeout(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 by default.
    # Pass in modified_retry to override the default retry behavior.
    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 Speicherclients.

Ü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.

Antimuster für Wiederholungsversuche

Es wird empfohlen, die integrierten Wiederholungsmechanismen nach Möglichkeit zu verwenden oder anzupassen. Weitere Informationen finden Sie unter Wiederholungen anpassen. Unabhängig davon, ob Sie die standardmäßigen Wiederholungsmechanismen verwenden, sie anpassen oder eine eigene Wiederholungslogik implementieren, ist es wichtig, die folgenden häufigen Antimuster zu vermeiden, da sie Probleme eher verschlimmern als beheben können.

Wiederholung ohne Backoff

Wenn Sie Anfragen sofort oder mit sehr kurzen Verzögerungen wiederholen, kann dies zu kaskadierenden Fehlern führen, die andere Fehler auslösen können.

So vermeiden Sie das: Implementieren Sie exponentiellen Backoff mit Jitter. Bei dieser Strategie wird die Wartezeit zwischen den Wiederholungsversuchen schrittweise erhöht und ein Zufallselement hinzugefügt, um zu verhindern, dass der Dienst durch Wiederholungsversuche überlastet wird.

Nicht idempotente Vorgänge bedingungslos wiederholen

Wenn Sie Vorgänge, die nicht idempotent sind, wiederholt ausführen, kann dies zu unbeabsichtigten Nebeneffekten führen, z. B. zu unbeabsichtigten Überschreibungen oder Löschungen von Daten.

So vermeiden Sie das: Machen Sie sich mit den Idempotenzmerkmalen der einzelnen Vorgänge gründlich vertraut, wie im Abschnitt Idempotenz von Vorgängen beschrieben. Bei nicht idempotenten Vorgängen muss Ihre Wiederholungslogik potenzielle Duplikate verarbeiten können. Alternativ können Sie die Wiederholung ganz vermeiden. Seien Sie vorsichtig bei Wiederholungsversuchen, die zu Race-Bedingungen führen können.

Nicht wiederholbare Fehler wiederholen

Alle Fehler als wiederholbar zu behandeln, kann problematisch sein. Einige Fehler, z. B. Autorisierungsfehler oder ungültige Anfragen, sind persistent. Wenn Sie sie wiederholen, ohne die zugrunde liegende Ursache zu beheben, ist das nicht erfolgreich und kann dazu führen, dass Anwendungen in einer Endlosschleife hängen bleiben.

So vermeiden Sie das: Kategorisieren Sie Fehler in vorübergehende (wiederholbare) und dauerhafte (nicht wiederholbare) Fehler. Wiederholen Sie nur vorübergehende Fehler wie die HTTP-Codes 408, 429 und 5xx oder bestimmte Verbindungsprobleme. Bei dauerhaften Fehlern sollten Sie sie protokollieren und die zugrunde liegende Ursache entsprechend beheben.

Wiederholungslimits ignorieren

Unbegrenzte Wiederholungsversuche können dazu führen, dass die Ressourcen in Ihrer Anwendung erschöpft sind oder dass Anfragen kontinuierlich an einen Dienst gesendet werden, der sich ohne Eingriff nicht erholen kann.

So vermeiden Sie das: Passen Sie die Wiederholungslimits an die Art Ihrer Arbeitslast an. Bei latenzempfindlichen Arbeitslasten sollten Sie eine maximale Gesamtdauer für Wiederholungsversuche festlegen, um eine rechtzeitige Antwort oder einen rechtzeitigen Fehler zu gewährleisten. Bei Batcharbeitslasten, bei denen längere Wiederholungszeiträume für vorübergehende serverseitige Fehler toleriert werden können, sollten Sie ein höheres Gesamtwiederholungslimit festlegen.

Unnötig übereinandergelegte Wiederholungsversuche

Wenn Sie zusätzlich zu den vorhandenen Wiederholungsmechanismen eine benutzerdefinierte Wiederholungslogik auf Anwendungsebene hinzufügen, kann dies zu einer übermäßigen Anzahl von Wiederholungsversuchen führen. Wenn Ihre Anwendung beispielsweise einen Vorgang dreimal wiederholt und die zugrunde liegende Clientbibliothek ihn auch dreimal für jeden Versuch Ihrer Anwendung wiederholt, kann es am Ende zu neun Wiederholungsversuchen kommen. Wenn Sie eine große Anzahl von Wiederholungsversuchen für Fehler senden, die nicht wiederholt werden können, kann dies zu einer Anfragedrosselung führen, die den Durchsatz aller Arbeitslasten einschränkt. Eine hohe Anzahl von Wiederholungsversuchen kann auch die Latenz von Anfragen erhöhen, ohne die Erfolgsrate zu verbessern.

So vermeiden Sie das: Wir empfehlen, die integrierten Wiederholungsmechanismen zu verwenden und zu konfigurieren. Wenn Sie Wiederholungsversuche auf Anwendungsebene implementieren müssen, z. B. für eine bestimmte Geschäftslogik, die sich über mehrere Vorgänge erstreckt, sollten Sie das zugrunde liegende Wiederholungsverhalten genau kennen. Deaktivieren oder begrenzen Sie Wiederholungsversuche in einer der Ebenen stark, um multiplikative Effekte zu vermeiden.

Nächste Schritte

• Weitere Informationen zu Vorbedingungen für Anfragen