Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Bilder mit der Play Game Services Publishing API hochladen

Mit der Play Games Services Publishing API können Sie ein Bild für eine Spielressource hochladen.

Uploadoptionen

Mit der Play Games Services Publishing API können Sie bestimmte Arten von Binärdaten oder Medien hochladen. Die spezifischen Merkmale der Daten, die Sie hochladen können, sind auf der Referenzseite für jede Methode angegeben, die Media-Uploads unterstützt:

Maximale Dateigröße für den Upload: Die maximale Datenmenge, die Sie mit dieser Methode speichern können.
Akzeptierte Media-MIME-Typen: Die Typen von Binärdaten, die Sie mit dieser Methode speichern können.

Uploadanfragen können folgendermaßen gestellt werden. Geben Sie die Methode, die Sie verwenden, mit dem Anfrageparameter „uploadType“ an.

Einfacher Upload: uploadType=media. Für die schnelle Übertragung kleinerer Dateien, z. B. mit einer Größe von maximal 5 MB.
Mehrteiliger Upload: uploadType=multipart. Für die schnelle Übertragung kleinerer Dateien und Metadaten. Die Datei wird zusammen mit den Metadaten, die sie beschreiben, in einer einzigen Anfrage übertragen.
Fortsetzbarer Upload: uploadType=resumable. Für eine zuverlässige Übertragung, die besonders bei größeren Dateien wichtig ist. Bei dieser Methode verwenden Sie eine Anfrage zum Starten einer Sitzung, die optional Metadaten enthalten kann. Das ist für die meisten Anwendungen eine gute Strategie, da sie zum Preis von nur einer zusätzlichen HTTP-Anfrage pro Upload auch für kleinere Dateien verwendet werden kann.

Wenn Sie Medien hochladen, verwenden Sie einen speziellen URI. Tatsächlich haben Methoden, die Media-Uploads unterstützen, zwei URI-Endpunkte:

Der /upload-URI für die Media. Das Format des Upload-Endpunkts ist der Standard-Ressourcen-URI mit dem Präfix „/upload“. Verwenden Sie diesen URI, wenn Sie die Media-Daten selbst übertragen.

Beispiel: POST /upload/games/v1configuration/images/resourceId/imageType/imageType
Der Standard-Ressourcen-URI für die Metadaten. Wenn die Ressource Datenfelder enthält, werden diese Felder zum Speichern von Metadaten verwendet, die die hochgeladene Datei beschreiben. Sie können diesen URI zum Erstellen oder Aktualisieren von Metadatenwerten verwenden.

Beispiel: POST /games/v1configuration/images/resourceId/imageType/imageType

Einfacher Upload

Am einfachsten laden Sie eine Datei hoch, indem Sie eine einfache Uploadanfrage senden. Diese Option ist eine gute Wahl, wenn eine der folgenden Bedingungen zutrifft:

Die Datei ist klein genug, um sie vollständig hochzuladen, falls die Verbindung fehlschlägt.
Es sind keine Metadaten zum Senden vorhanden. Das kann der Fall sein, wenn Sie planen, Metadaten für diese Ressource in einer separaten Anfrage zu senden, oder wenn keine Metadaten unterstützt oder verfügbar sind. Wenn Sie den einfachen Upload verwenden möchten, senden Sie eine POST- oder PUT-Anfrage an den /upload-URI der Methode und fügen Sie den Suchparameter uploadType=media hinzu. Beispiel:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media

Die HTTP-Header, die beim Stellen einer einfachen Uploadanfrage verwendet werden, sind:

Content-Type. Muss auf einen der akzeptierten Media-Datentypen für den Upload der Methode festgelegt werden, die in der Publishing API-Referenz angegeben sind.
Content-Length: Die Anzahl der Bytes, die Sie hochladen. Nicht erforderlich, wenn Sie die Chunked-Transfer-Codierung verwenden.

Beispiel: Einfacher Upload

Im folgenden Beispiel wird die Verwendung einer einfachen Uploadanfrage für die Play Games Services Publishing API veranschaulicht.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/png
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

PNG data

Wenn die Anfrage erfolgreich ist, gibt der Server den HTTP-Statuscode 200 OK zusammen mit allen Metadaten zurück. Beispiel:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

Mehrteiliger Upload

Wenn Sie Metadaten zusammen mit den hochzuladenden Daten senden möchten, können Sie eine einzelne multipart/related-Anfrage stellen. Diese Methode ist eine gute Wahl, wenn die gesendeten Daten klein genug sind, um sie vollständig hochzuladen, falls die Verbindung fehlschlägt.

Wenn Sie den mehrteiligen Upload verwenden möchten, senden Sie eine POST- oder PUT-Anfrage an den /upload-URI der Methode und fügen Sie den Abfrageparameter uploadType=multipart hinzu. Beispiel:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart

Die HTTP-Header der obersten Ebene, die beim Stellen einer Multipart-Upload-Anfrage verwendet werden sollen, sind:

–Content-Type: Auf „multipart/related“ festgelegt und enthält den Begrenzungsstring, den Sie zum Identifizieren der Teile der Anfrage verwenden.

– Content-Length: Die Gesamtzahl der Byte im Anfragetext. Der Medienteil der Anfrage muss kleiner als die maximale Dateigröße sein, die für diese Methode angegeben ist.

Der Text der Anfrage ist als „multipart/related“-Inhaltstyp RFC2387 formatiert und enthält genau zwei Teile. Die einzelnen Teile werden durch einen Grenzstring identifiziert. Der letzte Grenzstring wird von zwei Bindestrichen gefolgt.

Jeder Teil der Multipart-Anfrage benötigt einen zusätzlichen Content-Type-Header:

Metadatenteil: Muss zuerst kommen und der Content-Type muss einem der akzeptierten Metadatenformate entsprechen.
Medienteil: Muss an zweiter Stelle stehen und der Content-Type muss mit einem der akzeptierten Media-MIME-Typen der Methode übereinstimmen.

In der Referenz zur Publishing API finden Sie für jede Methode eine Liste der zulässigen Media-MIME-Typen und Größenbeschränkungen für hochgeladene Dateien.

Beispiel: Mehrteiliger Upload

Das folgende Beispiel zeigt eine Multipart-Uploadanfrage für die Play Games Services Publishing API.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

--foo_bar_baz
Content-Type: image/png

PNG data
--foo_bar_baz--

Wenn die Anfrage erfolgreich ist, gibt der Server den HTTP-Statuscode 200 OK zusammen mit allen Metadaten zurück:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

Fortsetzbarer Upload

Für einen zuverlässigeren Upload von Datendateien können Sie das Protokoll für fortsetzbare Uploads verwenden. Mit diesem Protokoll können Sie einen Uploadvorgang fortsetzen, nachdem ein Kommunikationsfehler den Datenfluss unterbrochen hat. Das ist besonders nützlich, wenn Sie große Dateien übertragen und die Wahrscheinlichkeit einer Netzwerkunterbrechung oder eines anderen Übertragungsfehlers hoch ist, z. B. beim Hochladen über eine mobile Client-App. Außerdem kann es bei Netzwerkfehlern Ihren Bandbreitenverbrauch reduzieren, da Sie das Hochladen großer Dateien nicht von Anfang an neu starten müssen.

Die Verwendung eines fortsetzbaren Uploads umfasst die folgenden Schritte:

Starten Sie eine fortsetzbare Sitzung. Senden Sie eine erste Anfrage an den Upload-URI, die gegebenenfalls die Metadaten enthält.
Speichern Sie den URI der fortsetzbaren Sitzung. Speichern Sie den Sitzungs-URI, der in der Antwort auf die erste Anfrage zurückgegeben wird. Sie verwenden ihn für die verbleibenden Anfragen in dieser Sitzung. Lade die Datei hoch.
Senden Sie die Mediendatei an den URI der fortsetzbaren Sitzung.

Außerdem müssen Apps, die den fortsetzbaren Upload verwenden, Code enthalten, mit dem ein unterbrochener Upload fortgesetzt werden kann. Wenn ein Upload unterbrochen wird, müssen Sie herausfinden, wie viele Daten erfolgreich empfangen wurden, und den Upload dann ab diesem Punkt fortsetzen.

Fortsetzbare Sitzung starten

Wenn Sie einen fortsetzbaren Upload starten möchten, senden Sie eine POST- oder PUT-Anfrage an den /upload-URI der Methode und fügen Sie den Suchparameter uploadType=resumable hinzu. Beispiel:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable

Bei dieser ersten Anfrage ist der Text entweder leer oder er enthält nur die Metadaten. Die eigentlichen Inhalte der Datei, die Sie hochladen möchten, werden in nachfolgenden Anfragen übertragen.

Verwenden Sie in der ersten Anfrage die folgenden HTTP-Header:

X-Upload-Content-Type. Auf den Media-MIME-Typ der Upload-Daten festlegen, die in nachfolgenden Anfragen übertragen werden sollen.
X-Upload-Content-Length. Auf die Anzahl der Byte der Upload-Daten festlegen, die in nachfolgenden Anfragen übertragen werden sollen. Wenn die Länge zum Zeitpunkt dieser Anfrage nicht bekannt ist, können Sie diesen Header weglassen.
Bei Bereitstellung von Metadaten: Content-Type. Wird entsprechend dem Datentyp der Metadaten festgelegt.
Content-Length: Die Anzahl der Byte, die im Text dieser ursprünglichen Anfrage angegeben sind. Nicht erforderlich, wenn Sie die aufgeteilte Transferverschlüsselung verwenden.

In der Referenz zur Publishing API finden Sie für jede Methode eine Liste der akzeptierten Media-MIME-Typen und die Größenbeschränkungen für hochgeladene Dateien.

Beispiel: Anfrage zum Starten einer fortsetzbaren Sitzung

Im folgenden Beispiel wird gezeigt, wie eine fortsetzbare Sitzung für die Play Games Services Publishing API gestartet wird.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: image/png
X-Upload-Content-Length: 2000000

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

Im nächsten Abschnitt wird der Umgang mit der Antwort beschrieben.

URI der fortsetzbaren Sitzung speichern

Wenn die Anfrage zum Starten der Sitzung erfolgreich war, gibt der API-Server den HTTP-Statuscode 200 OK zurück. Außerdem wird ein Location-Header bereitgestellt, der den URI Ihrer fortsetzbaren Sitzung angibt. Der Location-Header im Beispiel unten enthält den Abfrageparameter upload_id, der die eindeutige Upload-ID für diese Sitzung angibt.

Beispiel: Antwort auf die Initiierung einer fortsetzbaren Sitzung

Dies ist die Antwort auf die Anfrage in Schritt 1:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

Der Wert des Location-Headers, wie in der obigen Beispielantwort gezeigt, ist der Sitzungs-URI, den Sie als HTTP-Endpunkt für den eigentlichen Dateiupload oder zum Abfragen des Uploadstatus verwenden.

Kopieren und speichern Sie den Sitzungs-URI, damit Sie ihn für nachfolgende Anfragen verwenden können.

Datei hochladen

Senden Sie eine PUT-Anfrage an den Upload-URI, den Sie im vorherigen Schritt erhalten haben, um die Datei hochzuladen. Das Format der Uploadanfrage lautet:

PUT session_uri

Die HTTP-Header, die beim Senden der Anfragen für fortsetzbare Dateiuploads verwendet werden, enthalten Content-Length. Legen Sie diesen Wert auf die Anzahl der Byte fest, die Sie in dieser Anfrage hochladen. Das ist in der Regel die Größe der hochgeladenen Datei.

Beispiel: Anfrage für fortsetzbaren Datei-Upload

Hier ist eine fortsetzbare Anfrage zum Hochladen der gesamten 2.000.000 Byte großen PNG-Datei für das aktuelle Beispiel.

PUT https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/png

bytes 0-1999999

Wenn die Anfrage erfolgreich ist, antwortet der Server mit einer HTTP 201 Created-Antwort sowie allen Metadaten, die dieser Ressource zugewiesen sind. Wenn die ursprüngliche Anfrage der fortsetzbaren Sitzung eine PUT war, um eine vorhandene Ressource zu aktualisieren, wäre die Erfolgsantwort 200 OK, zusammen mit allen Metadaten, die dieser Ressource zugeordnet sind.

Wenn die Uploadanfrage unterbrochen wird oder Sie eine HTTP 503 Service Unavailable- oder eine andere 5xx-Antwort vom Server erhalten, folgen Sie der Anleitung unter Unterbrochenen Upload fortsetzen.

Datei in Blöcken hochladen

Bei fortsetzbaren Uploads können Sie eine Datei in Chunks aufteilen und eine Reihe von Anfragen senden, um jeden Chunk nacheinander hochzuladen. Dies ist nicht der bevorzugte Ansatz, da die zusätzlichen Anfragen mit Leistungseinbußen verbunden sind und in der Regel nicht erforderlich sind. Möglicherweise müssen Sie jedoch die Daten in Chunks aufteilen, um die Menge der Daten zu reduzieren, die in einer einzelnen Anfrage übertragen werden. Das ist hilfreich, wenn für einzelne Anfragen ein festes Zeitlimit gilt, wie es bei bestimmten Klassen von Google App Engine-Anfragen der Fall ist. Außerdem können Sie damit beispielsweise den Uploadfortschritt für ältere Browser anzeigen, die diese Funktion nicht standardmäßig unterstützen.

Wenn Sie die Daten in Teilen hochladen, ist neben dem für vollständige Dateiuploads erforderlichen Content-Length-Header auch der Content-Range-Header erforderlich:

Content-Length. Legen Sie als Wert die Größe der Teile oder einen kleineren Wert fest (wie es bei der letzten Anfrage der Fall sein kann).
Content-Range: Gibt an, welche Bytes in der Datei hochgeladen werden. Content-Range: bytes 0-524287/2000000 bedeutet beispielsweise, dass Sie die ersten 524.288 Byte (256 × 1.024 × 2) einer 2.000.000 Byte großen Datei bereitstellen.

Maximieren, um weitere Informationen zu erhalten

Wenn Sie die Daten portionsweise hochladen, ist der Header Content-Range zusammen mit dem für komplette Dateiuploads benötigten Header Content-Length erforderlich:

Content-Length. Legen Sie als Wert die Größe der Teile oder einen kleineren Wert fest (wie es bei der letzten Anfrage der Fall sein kann).
Content-Range: Legen Sie fest, dass angezeigt werden soll, welche Byte in der Datei hochgeladen werden. Beispielsweise zeigt Content-Range: bytes 0-524287/2000000 an, dass die ersten 524.288 Byte (256 x 1024 x 2) in einer 2.000.000 Byte großen Datei bereitgestellt werden.

Beschränkungen der Teilegröße: Die Größe muss bei allen Teilen ein Vielfaches von 256 KB (256 x 1024 Byte) sein, mit Ausnahme des letzten Teils, der den Upload vervollständigt. Wenn Sie Daten aufteilen, ist es wichtig, die Teile so groß wie möglich zu belassen, damit der Upload effizient bleibt.

Beispiel: Anfrage für fortsetzbaren aufgeteilten Datei-Upload

Eine Anfrage, die die ersten 524.288 Byte sendet, könnte so aussehen:

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: image/jpeg
Content-Range: bytes 0-524287/2000000

bytes 0-524288

Ist die Anfrage erfolgreich, gibt der Server 308 Resume Incomplete zusammen mit einem Range-Header zurück, der die Gesamtanzahl von Byte identifiziert, die bisher gespeichert wurden:

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-524287

Verwenden Sie den oberen Wert, der im Range-Header zurückgegeben wird, um zu bestimmen, wo der nächste Chunk beginnen soll. PUT Sie weiterhin jeden Chunk der Datei, bis die gesamte Datei hochgeladen wurde.

Wenn die PUT-Anfrage eines Blocks unterbrochen wird oder Sie eine HTTP-Antwort 503 Service Unavailable oder eine andere 5xx-Antwort vom Server erhalten, folgen Sie der Anleitung unter Unterbrochenen Upload fortsetzen. Anstatt den Rest der Datei hochzuladen, fahren Sie jedoch mit dem Hochladen von Blöcken ab diesem Punkt fort.

Wichtige Hinweise:

Verwenden Sie unbedingt den Range-Header in der Antwort, um zu bestimmen, wo der nächste Chunk beginnen soll. Gehen Sie nicht davon aus, dass der Server alle im vorherigen Request gesendeten Bytes empfangen hat.
Jeder Upload-URI hat eine begrenzte Lebensdauer und läuft schließlich ab (innerhalb eines Tages, wenn er nicht verwendet wird). Aus diesem Grund ist es am besten, einen fortsetzbaren Upload zu starten, sobald Sie den Upload-URI erhalten, und einen unterbrochenen Upload kurz nach der Unterbrechung fortzusetzen.
Wenn Sie eine Anfrage mit einer abgelaufenen Uploadsitzungs-ID senden, gibt der Server den Statuscode 404 Not Found zurück. Wenn in der Uploadsitzung ein nicht behebbarer Fehler auftritt, gibt der Server den Statuscode 410 Gone zurück. In diesen Fällen müssen Sie einen neuen fortsetzbaren Upload starten, einen neuen Upload-URI abrufen und den Upload unter Verwendung des neuen Endpunkts von vorn beginnen.

Wenn der gesamte Dateiupload abgeschlossen ist, antwortet der Server mit einem HTTP 201 Created sowie allen Metadaten, die dieser Ressource zugewiesen sind. Wenn mit dieser Anfrage eine vorhandene Entität aktualisiert und nicht eine neue erstellt worden wäre, wäre der HTTP-Antwortcode für einen abgeschlossenen Upload 200 OK gewesen.

Unterbrochenen Upload fortsetzen

Wenn eine Uploadanfrage beendet wird, bevor eine Antwort empfangen wird, oder wenn Sie vom Server eine HTTP 503 Service Unavailable-Antwort erhalten, müssen Sie den unterbrochenen Upload fortsetzen. So setzen Sie einen unterbrochenen Upload fort:

Anfragestatus Fragen Sie den aktuellen Status des Uploads ab, indem Sie eine leere PUT-Anfrage an den Upload-URI senden. Die HTTP-Header für diese Anfrage sollten einen Content-Range-Header enthalten, der angibt, dass die aktuelle Position in der Datei unbekannt ist. Wenn die Gesamtlänge Ihrer Datei beispielsweise 2.000.000 Zeichen beträgt, setzen Sie Content-Range auf */2000000. Wenn Sie die Gesamtgröße der Datei nicht kennen, setzen Sie den Content-Range auf */*.

Hinweis :Sie können den Status zwischen den Chunks anfordern, nicht nur, wenn der Upload unterbrochen wird. Das ist beispielsweise nützlich, wenn Sie den Uploadfortschritt in älteren Browsern anzeigen möchten.
Anzahl der hochgeladenen Byte abrufen Verarbeiten Sie die Antwort der Statusabfrage. Der Server verwendet den Range-Header in seiner Antwort, um anzugeben, welche Byte er bisher empfangen hat. Ein Range-Header von 0-299999 bedeutet beispielsweise, dass die ersten 300.000 Byte der Datei empfangen wurden.
Verbleibende Daten hochladen: Senden Sie nun die verbleibenden Daten oder den aktuellen Chunk, da Sie wissen, wo die Anfrage fortgesetzt werden muss. Beachten Sie, dass Sie die verbleibenden Daten in jedem Fall als separaten Chunk behandeln müssen. Sie müssen also den Header Content-Range senden, wenn Sie den Upload fortsetzen.

Beispiel: Unterbrochenen Upload fortsetzen

Uploadstatus anfordern In der folgenden Anfrage wird der Header „Content-Range“ verwendet,um anzugeben,dass die aktuelle Position in der 2.000.000 Byte großen Datei unbekannt ist.
```
PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000
```
Extrahieren Sie die Anzahl der bisher hochgeladenen Byte aus der Antwort. In der Antwort des Servers wird mit dem Range-Header angegeben, dass er bisher die ersten 43 Byte der Datei empfangen hat. Verwenden Sie den oberen Wert des Range-Headers, um zu bestimmen, wo der fortgesetzte Upload beginnen soll.
```
HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42
```
Hinweis :Wenn der Upload abgeschlossen ist, kann die Statusantwort 201Created oder 200 OK lauten. Das kann passieren, wenn die Verbindung unterbrochen wurde, nachdem alle Byte hochgeladen wurden, aber bevor der Client eine Antwort vom Server erhalten hat.
Setzen Sie den Upload an der Stelle fort, an der er unterbrochen wurde. Mit der folgenden Anfrage wird der Upload fortgesetzt, indem die verbleibenden Bytes der Datei ab Byte 43 gesendet werden.
```
PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999
```

Fehlerbehandlung

Beim Hochladen von Media ist es hilfreich, einige Best Practices zur Fehlerbehandlung zu kennen.

Sie können Uploads fortsetzen oder wiederholen, die aufgrund von Verbindungsunterbrechungen oder 5xx-Fehlern fehlgeschlagen sind, darunter:
- 500 Internal Server Error
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Verwenden Sie eine exponentielle Backoff-Strategie, wenn beim Fortsetzen oder Wiederholen von Uploadanfragen ein 5xx-Serverfehler zurückgegeben wird. Diese Fehler können auftreten, wenn ein Server überlastet ist. Der exponentielle Backoff kann helfen, diese Art von Problemen bei einer hohen Anzahl von Anfragen oder starkem Netzwerkverkehr zu beheben.
Andere Arten von Anfragen sollten nicht mit exponentiellem Backoff behandelt werden, aber Sie können trotzdem eine Reihe von ihnen wiederholen. Begrenzen Sie die Anzahl der Wiederholungsversuche für diese Anfragen. Ihr Code könnte beispielsweise auf zehn Wiederholungsversuche oder weniger begrenzt sein, bevor ein Fehler gemeldet wird.
Behandeln Sie 404 Not Found- und 410 Gone-Fehler bei fortsetzbaren Uploads, indem Sie den gesamten Upload von Anfang an neu starten.

Exponentielle Backoffs

Der exponentielle Backoff ist eine Standardstrategie zur Fehlerbehandlung für Netzwerkanwendungen, bei der der Client eine fehlgeschlagene Anfrage in regelmäßigen Abständen über einen immer längeren Zeitraum wiederholt. Wenn der Server aufgrund einer großen Anzahl von Anfragen oder eines hohen Netzwerkverkehrs Fehler zurückgibt, kann die Strategie des exponentiellen Backoffs hilfreich sein. Umgekehrt ist sie keine geeignete Strategie für Fehler, die nicht mit dem Netzwerkvolumen oder den Reaktionszeiten zusammenhängen, z. B. ungültige Autorisierungsanmeldedaten oder Fehler vom Typ „Datei nicht gefunden“.

Bei richtiger Anwendung erhöht das exponentielle Backoff die Effizienz der Bandbreitennutzung, reduziert die Anzahl der Anfragen, die für eine erfolgreiche Antwort erforderlich sind, und maximiert den Durchsatz von Anfragen in parallelen Umgebungen.

Der Ablauf für das Implementieren eines einfachen exponentiellen Backoffs sieht so aus:

Stellen Sie eine Anfrage an die API.
Sie erhalten eine HTTP 503-Antwort, die angibt, dass Sie die Anfrage wiederholen müssen.
Warten Sie 1 Sekunde + random_number_milliseconds und wiederholen Sie die Anfrage.
Sie erhalten eine HTTP 503-Antwort, die angibt, dass Sie die Anfrage wiederholen müssen.
Warten Sie 2 Sekunden + random_number_milliseconds und wiederholen Sie die Anfrage.
Sie erhalten eine HTTP 503-Antwort, die angibt, dass Sie die Anfrage wiederholen müssen.
Warten Sie 4 Sekunden + random_number_milliseconds und wiederholen Sie die Anfrage.
Sie erhalten einen HTTP 503 response-Fehlercode, der angibt, dass Sie die Anfrage noch einmal senden sollten.
Warten Sie 8 Sekunden + random_number_milliseconds und wiederholen Sie die Anfrage.
Sie erhalten einen HTTP 503 response-Fehlercode, der angibt, dass Sie die Anfrage noch einmal senden sollten.
Warten Sie 16 Sekunden + random_number_milliseconds Millisekunden und wiederholen Sie die Anfrage.
Beenden Sie den Vorgang. Melden oder protokollieren Sie einen Fehler.

In der obigen Liste steht „random_number_milliseconds“ für eine zufällige Anzahl von Millisekunden, deren Wert kleiner oder gleich 1.000 ist. Das ist notwendig, da eine kleine zufällige Verzögerung dazu beiträgt, die Last gleichmäßiger zu verteilen und eine Überlastung des Servers zu vermeiden. Der Wert von „random_number_milliseconds“ muss nach jeder Wartezeit neu definiert werden.

Der Algorithmus ist so eingerichtet, dass er endet, wenn n = 5. Diese Obergrenze verhindert, dass Clients unendlich oft wiederholen, und führt zu einer Gesamtverzögerung von etwa 32 Sekunden, bevor eine Anfrage als „nicht behebbarer Fehler“ eingestuft wird. Eine höhere maximale Anzahl von Wiederholungsversuchen ist in Ordnung, insbesondere wenn ein langer Upload läuft. Achten Sie jedoch darauf, die Verzögerung bei Wiederholungsversuchen auf einen angemessenen Wert zu begrenzen, z. B. auf weniger als eine Minute.