Wiederholungsstrategie

Auf dieser Seite werden Wiederholungsstrategien wie abgeschnittener exponentieller Backoff für fehlgeschlagene Anfragen an Cloud Storage beschrieben.

Übersicht

Um zu entscheiden, ob eine fehlgeschlagene Anfrage an Cloud Storage wiederholt werden soll, berücksichtigen Sie die Art der Anfrage und ihre Idempotenz. Diese bestimmt, ob der Vorgang sicher wiederholt werden kann. Im Allgemeinen sollten Sie den abgeschnittenen exponentiellen Backoff verwenden, um die folgenden Arten von Anfragen zu wiederholen:

Alle Anfragen an Cloud Storage, die die HTTP-Antwortcodes 5xx und 429 zurückgeben, einschließlich Uploads und Downloads von Daten oder Metadaten
Fortsetzbare Uploads, die die HTTP-Antwortcodes 408 zurückgeben
Socket-Zeitüberschreitungen und getrennte TCP-Verbindungen

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

Exponentieller Backoff-Algorithmus

Ein abgeschnittener exponentieller Backoff ist eine Standardstrategie zur Fehlerbehebung für Netzwerkanwendungen, bei der ein Client eine fehlgeschlagene Anfrage regelmäßig noch einmal sendet, wobei die Abstände zwischen den Anfragen immer länger werden.

Ein exponentieller Backoff-Algorithmus wiederholt Anfragen exponentiell und verlängert dabei die Wartezeit zwischen zwei Wiederholungen bis zur maximalen Backoff-Zeit. Ein Beispiel:

Senden Sie eine Anfrage an Cloud Storage.
Wenn die Anfrage fehlschlägt, wartet das System 1 + random_number_milliseconds Sekunden und wiederholt dann die Anfrage.
Wenn die Anfrage fehlschlägt, wartet das System 2 + random_number_milliseconds Sekunden und wiederholt dann die Anfrage.
Wenn die Anfrage fehlschlägt, wartet das System 4 + random_number_milliseconds Sekunden und wiederholt dann die Anfrage.
Und so weiter bis zur maximum_backoff-Zeit.
Setzen Sie die Wartezeit fort und wiederholen Sie den Vorgang bis zu einer maximalen Frist (deadline). Erhöhen Sie jedoch nicht die Wartezeit von maximum_backoff zwischen Wiederholungsversuchen.

wobei

Die Wartezeit beträgt min((2ⁿ +random_number_milliseconds), maximum_backoff), wobei n bei jeder Ausführung (Anfrage) um 1 erhöht wird.
random_number_milliseconds steht für eine zufällige Anzahl von Millisekunden, deren Wert größer oder gleich 1.000 ist. So lassen sich Situationen vermeiden, in denen viele Clients synchronisiert werden und alle gleichzeitig Anfragen wiederholen und diese in synchronisierten Wellen senden. Der Wert von random_number_milliseconds wird nach jeder Anfragewiederholung neu berechnet.
maximum_backoff ist normalerweise 32 oder 64 Sekunden lang. Der geeignete Wert hängt vom jeweiligen Anwendungsfall ab.

Sie können den Vorgang wiederholen, wenn die maximum_backoff-Zeit erreicht wurde. Wir empfehlen jedoch, dass die Anfrage nach einer bestimmten Zeit fehlschlägt, um zu verhindern, dass Ihre Anwendung nicht mehr reagiert. Wenn ein Client beispielsweise eine maximum_backoff-Zeit von 64 Sekunden verwendet, kann er den Vorgang nach Erreichen dieses Werts alle 64 Sekunden noch einmal versuchen. Der Client beendet dann den Vorgang nach einer deadline von 600 Sekunden.

Wie lange Clients zwischen Wiederholungen warten sollten und wie oft sie versuchen sollten, eine Anfrage ein weiteres Mal zu senden, hängt von Ihrem Anwendungsfall und den Netzwerkbedingungen ab. Mobile Clients einer Anwendung müssen unter Umständen mehr Wiederholungen mit längeren Intervallen ausführen als Desktopclients derselben Anwendung.

Wenn die Anfragewiederholungen nach Überschreiten des Werts maximum_backoff plus einer zusätzlichen Frist für Wiederholungen fehlschlagen, melden oder protokollieren Sie einen Fehler mit einer der Methoden, die unter Support und Hilfe aufgeführt werden.

Idempotenz

Um zu bestimmen, ob eine fehlgeschlagene Anfrage an Cloud Storage sicher wiederholt werden kann, sollten Sie prüfen, ob die Anfrage idempotent ist. Das bedeutet, dass der gleiche Vorgang mehrere Male die gleichen Auswirkungen auf den Status der Zielressource hat. Idempotente Vorgänge sind in der Regel sicher für einen Wiederholungsversuch.

Im Folgenden finden Sie Beispiele für Bedingungen, die die Idempotenz erfüllen:

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.

So hat beispielsweise eine Anfrage zum Auflisten von Buckets die gleichen Auswirkungen, auch wenn die Anfrage mehrmals erfolgreich ausgeführt wird. Andererseits ist ein Vorgang wie das Erstellen einer neuen Pub/Sub-Benachrichtigung nicht idempotent, da bei jeder erfolgreichen Anfrage eine neue Benachrichtigungs-ID erstellt wird.

Bedingte Idempotenz

Teilmengen von Anfragen sind bedingt idempotent. Das bedeutet, dass sie nur idempotent sind, wenn sie bestimmte optionale Argumente enthalten. Vorgänge, die mit Bedingungen sicher wiederholt werden können, sollten nur dann standardmäßig wiederholt werden, wenn der Bedingungsfall erfolgreich ist. Cloud Storage akzeptiert Vorbedingungen und ETags als Bedingungsfälle für Anfragen.

Wiederholungsstrategie pro Cloud Storage-Tool

Klicken Sie auf die folgenden Tabs, um Empfehlungen zu Wiederholungsstrategien für jedes Cloud Storage-Tool aufzurufen.

Console

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

gsutil

Informationen zur Wiederholungsstrategie für gsutil finden Sie unter Strategie im Umgang mit Wiederholungen.

Clientbibliotheken

C++

Die C++-Clientbibliothek verwendet standardmäßig den exponentiellen Backoff.

C#

Die C#-Clientbibliothek verwendet standardmäßig den exponentiellen Backoff.

Go

Die Go-Clientbibliothek verwendet standardmäßig den exponentiellen Backoff.

Java

Die Java-Clientbibliothek verwendet standardmäßig den exponentiellen Backoff.

Node.js

Node.js kann Backoff-Strategien automatisch einsetzen, um Anfragen mit dem Parameter autoRetry zu wiederholen.

PHP

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

Python

Bei der Wiederholungsstrategie unterscheidet die Python-Clientbibliothek zwischen Medien- und Nicht-Medien-Vorgängen:

Medienvorgänge umfassen alle Aktionen, die Nutzlastdaten abrufen oder an Objekte senden. Dies umfasst beispielsweise alle Methoden eines Blob, die mit den Wörtern "upload" oder "download" sowie Client.download_blob_to_file beginnen.
Nicht-Medienvorgänge sind Aktionen, die nur Objektmetadaten verarbeiten.

Medienvorgänge und Nicht-Medienvorgänge unterstützen standardmäßig Wiederholungsversuche für die folgenden Fehlercodes:

Verbindungsfehler:
- requests.exceptions.ConnectionError
- requests.exceptions.ChunkedEncodingError (nur Media API-Aufrufe)
HTTP-Codes:
- 429 Too Many Requests
- 500 Internal Server Error
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
- 508 Resource Limit Exceeded

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

Standardeinstellung	Medienaufrufe	Nicht-Medienaufrufe
Anfängliche Wartezeit (Sekunden)	1	1
Multiplikator für die Wartezeit pro Iteration (Sekunden)	2	2
Maximale Wartezeit (Sekunden)	64	60
Standardfrist (Sekunden)	600	120
Jitter implementiert	Ja	Nein

Eine Teilmenge der Medienvorgänge und Nicht-Medienvorgänge ist nur idempotent, wenn sie bestimmte optionale Argumente enthalten. Vorgänge, die bedingt sicher für Wiederholungsversuche sind, werden standardmäßig nur dann wiederholt, wenn der Bedingungsfall erfolgreich ist. Derzeit umfassen diese Bedingungen Folgendes:

DEFAULT_RETRY_IF_GENERATION_SPECIFIED
- Der Wiederholungsversuch von if generation oder if_generation_match wurde als Argument an die Methode übergeben. 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
- Sicher für Wiederholung, wenn die Methode ein etag in den JSON-Anfragetext einfügt. Bei HMACKeyMetadata.update() bedeutet dies, dass das ETag auf dem 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.

Wiederholungsrichtlinien für Medienvorgänge

Bei Medienvorgängen können Sie das Argument num_retries für Uploadmethoden konfigurieren, um die Anzahl der Uploadversuche anzugeben. Standardmäßig werden nur Uploads mit der Bedingung if_metageneration_match wiederholt, um die Idempotenz zu garantieren. Durch Festlegen des Arguments num_retries wird das Standardverhalten überschrieben und Wiederholungsversuche werden auch ohne die Bedingung if_metageneration_match garantiert.

Wiederholungsrichtlinien für Nicht-Medienvorgänge

Bei Nicht-Medien-Vorgängen, die entweder sicher oder bedingt sicher sind, wird der Methodensignatur ein retry-Parameter hinzugefügt. Die Standardeinstellung für diese Parameter ist eine der folgenden:

DEFAULT_RETRY
DEFAULT_RETRY_IF_GENERATION_SPECIFIED
DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED
DEFAULT_RETRY_IF_ETAG_IN_JSON

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. Wenn Sie beispielsweise die Standardfrist auf 30 Sekunden ändern möchten, übergeben Sie retry=DEFAULT_RETRY.with_deadline(30). Wir empfehlen, Attribute einzeln zu ändern. Weitere Informationen finden Sie in der Referenz zu google-api-core-Wiederholungsversuche.

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 finden Sie Beispiele für benutzerdefinierte bedingte Wiederholungsversuche:

blob.reload() verwendet standardmäßig DEFAULT_RETRY. Wenn Sie dies überschreiben möchten, sodass die Funktion überhaupt nicht wiederholt wird, rufen Sie sie als blob.reload(retry=None) auf.
bucket.update() verwendet standardmäßig DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED. Wenn Sie diese Einstellung überschreiben möchten, damit die Funktion auch dann ausgeführt wird, wenn die Meta-Generierungsnummer nicht angegeben ist, rufen Sie sie so auf:
```
from google.cloud.storage.retry import DEFAULT_RETRY
bucket.update(retry=DEFAULT_RETRY)
```
bucket.list_blobs() verwendet standardmäßig DEFAULT_RETRY. Um dies zu überschreiben, damit der API-Aufruf mit einer Frist von 20 Sekunden anstelle der standardmäßigen 120 Sekunden wiederholt wird, rufen Sie sie so auf:
```
from google.cloud.storage.retry import DEFAULT_RETRY
modified_retry = DEFAULT_RETRY.with_deadline(20)
bucket.list_blobs(retry=modified_retry)
```

Ruby

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

REST APIs

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

Idempotenz von Vorgängen

In der folgenden Tabelle sind die Cloud Storage-Vorgänge aufgeführt, die unter die einzelnen Kategorien 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-/Patchanfragen für Buckets mit `IfMetagenerationMatch` oder ETag als HTTP-Vorbedingung Aktualisierungs-/Patchanfragen für Objekte mit `IfMetagenerationMatch` oder ETag als HTTP-Vorbedingung Bucket-IAM-Richtlinie mit ETag als HTTP-Vorbedingung oder im Ressourcentext festlegen HMAC-Schlüssel mit ETag als HTTP-Vorbedingung oder im Ressourcentext aktualisieren Mit `ifGenerationMatch` Objekte einfügen, kopieren, verfassen oder neu schreiben Objekt mit `ifGenerationMatch` löschen (oder mit einer Generierungsnummer für Objektversionen)
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