Diese Seite wurde von der Cloud Translation API übersetzt.

Bilder mit der Play Game Services Publishing API hochladen

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

Uploadoptionen

Mit der Play Games Services Publishing API können Sie bestimmte Typen von Binärdaten oder Medien hochladen. Die besonderen Merkmale der Daten, die hochgeladen werden können, finden Sie auf den Referenzseiten der Methoden, die Medienuploads unterstützen:

Maximale Upload-Dateigröße: Die maximale Datenmenge, die mit dieser Methode gespeichert werden kann.
Zulässige Medien-MIME-Typen: Die Typen von Binärdaten, die mit dieser Methode gespeichert werden können.

Uploadanfragen können folgendermaßen gestellt werden. Geben Sie die Methode an, die Sie für den Anfrageparameter „uploadType“ verwenden.

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 eine schnelle Übermittlung kleinerer Dateien und Metadaten wird die Datei in einer einzelnen Anfrage zusammen mit beschreibenden Metadaten übertragen.
Fortsetzbarer Upload: uploadType=resumable. Für zuverlässige Übertragungen. Dies ist insbesondere bei größeren Dateien wichtig. Bei dieser Methode wird eine sitzungsinitiierende Anfrage verwendet, die optional Metadaten umfassen kann. Es ist eine gute Strategie für die meisten Anwendungen, da sie zum Preis von nur einer zusätzlichen HTTP-Anfrage auch für kleinere Dateien verwendet werden kann.

Für den Upload von Medien wird ein besonderer URI verwendet. Tatsächlich gibt es in Methoden, die Medienuploads unterstützen, zwei URI-Endpunkte:

Der /upload-URI (für die Medien). Das Format des Upload-Endpunkts ist der Standardressourcen-URI mit dem Präfix „/upload“. Verwenden Sie diesen URI beim Übertragen der eigentlichen Mediendaten.

Beispiel: POST /upload/games/v1configuration/images/resourceId/imageType/imageType
Der Standardressourcen-URI (für die Metadaten). Wenn die Ressource Datenfelder enthält, werden diese 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

Die einfachste Methode zum Hochladen einer Datei ist eine einfache Uploadanfrage. Diese Option ist eine gute Wahl, wenn eine der folgenden Aussagen zutrifft:

Die Datei ist klein genug, um sie bei einem Verbindungsausfall noch einmal komplett hochzuladen.
Es sind keine Metadaten zum Senden vorhanden. Das ist beispielsweise der Fall, wenn du Metadaten für diese Ressource in einer separaten Anfrage senden möchtest oder 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 Abfrageparameter „uploadType=media“ hinzu. Beispiel:

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

Zu den HTTP-Headern, die bei einer einfachen Uploadanfrage verwendet werden müssen, gehören:

Content-Type. Legen Sie einen der zulässigen Uploadmediendatentypen der Methode fest, die in der Referenz der Publishing API angegeben sind.
Content-Length. Legen Sie als Wert die Anzahl von Byte fest, die Sie hochladen möchten. Nicht erforderlich bei Verwendung der aufgeteilten Transferverschlüsselung.

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

Ist die Anfrage erfolgreich, gibt der Server den Statuscode „HTTP 200 OK“ zusammen mit vorhandenen Metadaten zurück. Beispiel:

HTTP/1.1 200
Content-Type: application/json

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

Mehrteiliger Upload

Wenn Metadaten zusammen mit den hochzuladenden Daten gesendet werden sollen, können Sie eine einzelne Anfrage (multipart/related) stellen. Das ist eine gute Wahl, wenn die gesendeten Daten klein genug sind, um sie noch einmal komplett hochzuladen, wenn die Verbindung fehlschlägt.

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

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

Zu den Top-Level-HTTP-Headern beim Stellen einer mehrteiligen Uploadanfrage gehören:

–Content-Type. Setzen Sie den Wert auf „multipart/related“ und fügen Sie den Grenzstring ein, den Sie zum Identifizieren der Teile der Anfrage verwenden.

–Content-Length: Legen Sie als Wert die Gesamtanzahl von Byte im Anfragetext fest. 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 Inhaltstyp multipart/related RFC 2387 formatiert und enthält genau zwei Teile. Die Teile werden durch einen Grenzstring identifiziert und auf den finalen Grenzstring folgen zwei Bindestriche.

Für jeden Teil der mehrteiligen Anfrage ist als zusätzlicher Header „Content-Type“ erforderlich:

Metadatenteil: Muss als Erstes angegeben werden und „Content-Type“ muss einem der zulässigen Metadatenformate entsprechen.
Medienteil: Muss als Zweites angegeben werden und „Content-Type“ muss einem der zulässigen Medien-MIME-Typen der Methode entsprechen.

Eine Liste der zulässigen Medien-MIME-Typen und der Größenbeschränkungen für hochgeladene Dateien finden Sie in der Publishing API-Referenz für die jeweilige Methode.

Beispiel: Mehrteiliger Upload

Das Beispiel unten zeigt eine mehrteilige Uploadanfrage an 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--

Ist die Anfrage erfolgreich, gibt der Server den Statuscode „HTTP 200 OK“ zusammen mit vorhandenen 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 dann nützlich, wenn große Dateien übertragen werden und die Wahrscheinlichkeit einer Netzwerkunterbrechung oder eines anderen Übertragungsfehlers hoch ist (z. B. beim Hochladen von einer mobilen Client-App). Es kann auch die Auslastung Ihrer Bandbreite bei einem Netzwerkausfall reduzieren, da Sie Uploads großer Dateien nicht von Beginn an neu starten müssen.

Die Verwendung eines fortsetzbaren Uploads umfasst die folgenden Schritte:

Starten Sie eine fortsetzbare Sitzung. Führen Sie eine erste Anfrage an den Upload-URI durch, in dem die Metadaten enthalten sind (sofern vorhanden).
Speichere den URI der fortsetzbaren Sitzung. Speichern Sie den Sitzungs-URI, der als Antwort auf die erste Anfrage zurückgegeben wurde. Er wird für die weiteren Anfragen in dieser Sitzung benötigt. Lade die Datei hoch.
Senden Sie die Mediendatei an den URI der fortsetzbaren Sitzung.

Außerdem müssen Anwendungen, die den fortsetzbaren Upload verwenden, Code zum Fortsetzen eines unterbrochenen Uploads enthalten. Wird ein Upload unterbrochen, prüfen Sie, wie viele Daten erfolgreich empfangen wurden, und setzen Sie dann den Upload ab diesem Punkt fort.

Fortsetzbare Sitzung starten

Zum Starten eines fortsetzbaren Uploads stellen Sie eine POST- oder PUT-Anfrage an den /upload-URI der Methode und fügen dabei den Abfrageparameter uploadType=resumable hinzu. Beispiel:

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

Für diese erste Anfrage ist der Text entweder leer oder enthält ausschließlich die Metadaten. Es werden die tatsächlichen Inhalte der Datei übertragen, die in den nachfolgenden Anfragen hochgeladen werden sollen.

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

X-Upload-Content-Type. Legen Sie als Wert den Medien-MIME-Typ der Uploaddaten fest, die in den folgenden Anfragen übertragen werden sollen.
X-Upload-Content-Length. Legen Sie als Wert die Anzahl von Byte für die Uploaddaten fest, die in den folgenden Anfragen übertragen werden sollen. Ist die Länge zu Beginn der Anfrage unbekannt, können Sie diesen Header weglassen.
Bei Bereitstellung von Metadaten: Content-Type. Legen Sie als Wert den entsprechenden Datentyp der Metadaten fest.
Content-Length. Legen Sie als Wert die Anzahl von Byte fest, die im Text dieser ersten Anfrage bereitgestellt werden. Nicht erforderlich bei Verwendung der aufgeteilten Transferverschlüsselung.

Eine Liste der zulässigen Medien-MIME-Typen und der Größenbeschränkungen für hochgeladene Dateien finden Sie in der Publishing API-Referenz für die jeweilige Methode.

Beispiel: Anfrage zum Start einer fortsetzbaren Sitzung

Das folgende Beispiel zeigt, wie Sie über die Play Games Services Publishing API eine fortsetzbare Sitzung starten.

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 stellt er einen Header vom Typ Location bereit, der den URI der fortsetzbaren Sitzung angibt. Der im Beispiel unten gezeigte Header Location umfasst einen Abschnitt mit dem Abfrageparameter upload_id, der die eindeutige Upload-ID für diese Sitzung liefert.

Beispiel: Antwort auf Anfrage zum Start 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 Beispielantwort oben gezeigt, ist der Sitzungs-URI, der als HTTP-Endpunkt für den tatsächlichen Dateiupload oder die Abfrage des Uploadstatus dient.

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

Datei hochladen

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

PUT session_uri

Einer der HTTP-Header, der bei Anfragen für fortsetzbare Datei-Uploads verwendet werden muss, ist Content-Length. Legen Sie als Wert die Anzahl von Byte fest, die Sie in dieser Anfrage hochladen möchten. Dies entspricht normalerweise der Upload-Dateigröße.

Beispiel: Anfrage für fortsetzbaren Datei-Upload

Hierbei handelt es sich um eine fortsetzbare Anfrage zum Hochladen der insgesamt 2.000.000 Byte großen PNG-Datei im aktuellen 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

Ist die Anfrage erfolgreich, gibt der Server den Statuscode HTTP 201 Created zusammen mit allen Metadaten zurück, die dieser Ressource zugeordnet sind. Wäre die erste Anfrage der fortsetzbaren Sitzung eine Anfrage vom Typ PUT zum Aktualisieren einer vorhandenen Ressource gewesen, hätte die Erfolgsmeldung 200 OK gelautet, zusammen mit allen Metadaten, die dieser Ressource möglicherweise zugeordnet sind.

Wenn die Uploadanfrage unterbrochen wird oder der Server eine Antwort vom Typ HTTP 503 Service Unavailable oder 5xx zurückgibt, gehen Sie wie im Abschnitt Unterbrochenen Upload fortsetzen beschrieben vor.

Datei in Teilen hochladen

Bei fortsetzbaren Uploads können Sie eine Datei in mehrere Teile aufteilen und eine Reihe von Anfragen senden, um jeden Teil der Reihe nach hochzuladen. Dies ist nicht der bevorzugte Ansatz, da die zusätzlichen Anfragen Leistungskosten verursachen und in der Regel nicht erforderlich sind. Unter bestimmten Umständen ist die Aufteilung jedoch erforderlich, um die Menge von Daten zu reduzieren, die bei einer einzelnen Anfrage übertragen werden. Dies ist hilfreich, wenn für einzelne Anfragen eine feste Zeitbegrenzung vorliegt (z. B. für bestimmte Arten von Google App Engine-Anfragen). Der Prozess ermöglicht außerdem, Aufgaben wie das Bereitstellen von Upload-Fortschrittsanzeigen für alte Browser durchzuführen, die dies standardmäßig nicht unterstützen.

Wenn Sie die Daten portionsweise hochladen, ist der Header „Content-Range“ zusammen mit dem für vollständige Dateiuploads erforderlichen 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 Bytes 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.

Für mehr Informationen maximieren

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 über den Range-Header zurückgegeben wird, um zu ermitteln, wo der nächste Teil beginnt. Führen Sie PUT für die einzelnen Teile so lange durch, bis die gesamte Datei hochgeladen wurde.

Wenn die PUT-Anfrage eines Teils unterbrochen wird oder der Server eine HTTP-Antwort vom Typ 503 Service Unavailable oder 5xx zurückgibt, gehen Sie vor, wie unter Unterbrochenen Upload fortsetzen beschrieben. Laden Sie jedoch nicht den Rest der Datei hoch, sondern setzen Sie einfach das Hochladen der Teile ab diesem Punkt fort.

Wichtige Hinweise:

Geben Sie unbedingt den Header Range in der Antwort an, um herauszufinden, wo der nächste Teil beginnt. Gehen Sie nicht davon aus, dass der Server alle Byte erhalten hat, die in der vorangegangenen Anfrage gesendet wurden.
Jeder Upload-URI hat eine begrenzte Lebensdauer und läuft bei Nichtverwendung etwa innerhalb eines Tages ab. Aus diesem Grund empfiehlt es sich, einen fortsetzbaren Upload zu starten, sobald Sie den Upload-URI erhalten haben, 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. Tritt in der Uploadsitzung ein nicht behebbarer Fehler auf, 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.

Nach Abschluss des gesamten Dateiuploads gibt der Server den Statuscode HTTP 201 Created zusammen mit allen Metadaten zurück, die dieser Ressource zugeordnet sind. Wenn mit der Anfrage keine neue Entität erstellt, sondern eine vorhandene Entität aktualisiert worden wäre, hätte der HTTP-Antwortcode für einen erfolgreichen Upload 200 OK gelautet.

Unterbrochenen Upload fortsetzen

Wird die Uploadanfrage vor dem Erhalten einer Antwort beendet oder erhalten Sie vom Server eine Antwort vom Typ HTTP 503 Service Unavailable, müssen Sie den unterbrochenen Upload fortsetzen. So setzen Sie einen unterbrochenen Upload fort:

Anfragestatus Fragen Sie den derzeitigen Status des Uploads ab, indem Sie eine leere PUT-Anfrage an den Upload-URI senden. Bei dieser Anfrage sollten die HTTP-Header einen Content-Range-Header enthalten, der anzeigt, dass die derzeitige Position in der Datei unbekannt ist. Setzen Sie beispielsweise Content-Range auf */2000000, wenn die Dateigröße insgesamt 2.000.000 ist. Wenn Sie die Gesamtgröße der Datei nicht kennen, legen Sie für „Content-Range“ den Wert */* fest.

Hinweis :Sie können den Status nicht nur bei einer Unterbrechung des Uploads, sondern auch zwischen den einzelnen Teilen anfordern. Dies ist beispielsweise dann nützlich, wenn die Upload-Fortschrittsanzeigen von alten Browsern dargestellt werden sollen.
Anzahl der hochgeladenen Byte abrufen Verarbeiten Sie die Antwort der Statusabfrage. Der Server verwendet den Header Range in der Antwort, um anzugeben, welche Byte bisher empfangen wurden. Der Header Range mit einem Wert von 0-299999 gibt beispielsweise an, dass die ersten 300.000 Byte der Datei empfangen wurden.
Verbleibende Daten hochladen Senden Sie nun, da Sie wissen, wo Sie die Anfrage fortsetzen müssen, die verbleibenden Daten bzw. den aktuellen Teil. Beachten Sie, dass Sie die verbleibenden Daten in jedem Fall als separaten Teil behandeln müssen. Es muss also der Header Content-Range gesendet werden, um den Upload fortzusetzen.

Beispiel: Unterbrochenen Upload fortsetzen

Fordern Sie den Uploadstatus an. 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 von Byte, die bisher hochgeladen wurden, aus der Antwort. Die Antwort des Servers enthält den Header Range, um anzugeben, dass er bisher die ersten 43 Byte der Datei erhalten hat. Sie können anhand des oberen Werts des Range-Headers ermitteln, von wo aus der fortgesetzte Upload gestartet werden soll.
```
HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42
```
Hinweis :Nach Abschluss des Uploads wird eventuell die Statusantwort 201Created oder 200 OK ausgegeben. Dies kann passieren, wenn die Verbindung unterbrochen wird, nachdem alle Byte hochgeladen worden sind, aber bevor der Client eine Antwort vom Server erhalten hat.
Setzen Sie den Upload von dem Punkt aus fort, an dem er unterbrochen wurde. Die folgende Anfrage setzt den Upload fort, indem die verbleibenden Byte 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 Medien ist es hilfreich, einige Best Practices zur Fehlerbehandlung zu kennen.

Fortsetzen oder Wiederholen von Uploads, 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 einen exponentiellen Backoff, wenn beim Fortsetzen oder Wiederholen von Uploadanfragen ein Serverfehler des Typs 5xx zurückgegeben wird. Diese Fehler können auftreten, wenn ein Server überlastet ist. Mit exponentiellen Backoffs können solche Probleme in Zeiten mit sehr vielen Anfragen oder bei hohem Netzwerktraffic reduziert werden.
Andere Arten von Anfragen sollten nicht mit exponentiellen Backoffs ausgeführt werden. Sie können aber eine bestimmte Anzahl dieser Anfragen wiederholen. Begrenzen Sie dabei die Anzahl der Wiederholungen. Beispielsweise kann durch den Code die Anzahl der Wiederholungen vor der Ausgabe eines Fehlers auf zehn oder weniger beschränkt werden.
Wenn bei fortsetzbaren Uploads Fehler des Typs 404 Not Found und 410 Gone auftreten, starten Sie den gesamten Upload von Beginn an neu.

Exponentieller Backoff

Exponentielle Backoffs bilden eine Standard-Fehlerbehandlungsstrategie für Netzwerkanwendungen, bei denen der Client eine fehlgeschlagene Anfrage über einen immer länger werdenden Zeitraum periodisch wiederholt. Wenn bei sehr vielen Anfragen oder bei hohem Netzwerktraffic der Server Fehler ausgibt, kann ein exponentieller Backoff eine hilfreiche Strategie zur Fehlerbehandlung sein. Dagegen ist ein exponentieller Backoff keine gute Strategie für die Handhabung von Fehlern, die nicht aufgrund des Netzwerkvolumens oder von Antwortzeiten auftreten, z. B. Fehler wegen ungültiger Autorisierungsdaten oder nicht gefundener Dateien.

Bei richtiger Anwendung erhöht der exponentielle Backoff die Effizienz der Bandbreitennutzung, verringert die Anzahl der Anfragen, die für den Erhalt einer erfolgreichen Antwort erforderlich sind, und maximiert den Durchsatz von Anfragen in Umgebungen mit Gleichzeitigkeit.

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 eine HTTP 503 response, die angibt, dass Sie die Anfrage wiederholen müssen.
Warten Sie 8 Sekunden + random_number_milliseconds und wiederholen Sie die Anfrage.
Sie erhalten eine HTTP 503 response, die angibt, dass Sie die Anfrage wiederholen müssen.
Warten Sie 16 Sekunden + random_number_milliseconds Millisekunden und wiederholen Sie die Anfrage.
Stopp Melden oder protokollieren Sie einen Fehler.

In der Liste oben steht „random_number_milliseconds“ für eine zufällige Anzahl von Millisekunden, deren Wert kleiner oder gleich 1.000 ist. Dies ist erforderlich, da eine kurze zufällige Verzögerung die Last gleichmäßiger verteilt und verhindert, dass der Server blockiert wird. 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 die Clients unendlich fortfahren, und führt zu einer Verzögerung von insgesamt 32 Sekunden, bevor eine Anfrage als „nicht zu behebender Fehler“ gilt. Sie können eine größere maximale Anzahl an Wiederholungen angeben, insbesondere wenn es sich um einen langen Upload handelt. Wichtig ist nur, dass die Wiederholungsverzögerung bei einem akzeptablen Wert liegt, zum Beispiel bei unter einer Minute.