Auf dieser Seite wird beschrieben, wie Sie eine fortsetzbare Uploadanfrage über das REST-Protokoll an die Google Photos Library API senden. Mit diesem Protokoll können Sie einen Uploadvorgang fortsetzen, nachdem ein Kommunikationsfehler den Datenfluss unterbrochen hat.
Wenn Sie als Entwickler Clientbibliotheken verwenden, beachten Sie bitte, dass einige Clientbibliotheken native Unterstützung für fortsetzbare Uploads bieten.
Verwenden Sie die Option „Fortsetzbarer Upload“ in folgenden Fällen:
- Sie laden große Dateien hoch.
- Die Wahrscheinlichkeit von Netzwerkunterbrechungen oder anderen Übertragungsfehlern ist hoch (z. B. beim Hochladen einer Datei aus einer mobilen App).
Fortsetzbare Uploads können auch die Bandbreitennutzung bei einem Netzwerkfehler reduzieren, da Sie große Datei-Uploads nicht von vorn beginnen müssen.
Schritt 1: Uploadsitzung starten
Starten Sie eine fortsetzbare Uploadsitzung, indem Sie eine POST-Anfrage an https://photoslibrary.googleapis.com/v1/uploads senden. Laden Sie die Datei mit der URL für den fortsetzbaren Upload hoch, die in dieser Anfrage zurückgegeben wird.
Die POST-Anfrage muss die folgenden Header enthalten:
| Headerfelder | |
|---|---|
Content-Length |
Legen Sie dafür 0 fest, da der Anfragetext leer ist. |
X-Goog-Upload-Command |
Setze diese Property auf start. |
X-Goog-Upload-Content-Type |
Legen Sie den MIME-Typ der Datei fest, z. B. image/jpeg. |
X-Goog-Upload-Protocol |
Setze diese Property auf resumable. |
X-Goog-Upload-Raw-Size |
Legen Sie als Wert die Gesamtzahl von Byte der zu übertragenden Dateidaten fest. |
Hier ist ein POST-Anfrageheader:
POST https://photoslibrary.googleapis.com/v1/uploads Authorization: Bearer oauth2-token Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: mime-type X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: bytes-of-file
Schritt 2: Sitzungs-URL speichern
Bei Erfolg gibt die POST-Anfrage den HTTP-Statuscode 200 OK zurück, der den folgenden Header enthält.
X-Goog-Upload-URL: url-to-make-uploads-to X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes
Das Header-Feld x-goog-upload-chunk-granularity enthält die Byteausrichtung und den Detaillierungsgrad für alle vom Client gesendeten Datenblöcke. Wenn der Upload in mehreren Blöcken erfolgt, müssen alle Uploads, mit Ausnahme des letzten Uploads, in Vielfachen dieses Werts erfolgen. Das heißt, die Uploadbyte der Datei müssen auf diesen Wert ausgerichtet sein. Im letzten Teil können Sie die verbleibenden Byte hochladen.
Das Header-Feld X-Goog-Upload-URL enthält eine eindeutige URL, die verwendet werden muss, um den Upload über alle verbleibenden Anfragen abzuschließen. Kopieren und speichern Sie diese fortsetzbare Sitzungs-URL, damit Sie sie für nachfolgende Anfragen verwenden können.
Schritt 3: Datei hochladen
Es gibt zwei Möglichkeiten, eine Datei mit einer fortsetzbaren Sitzung hochzuladen:
- In einer einzelnen Anfrage. Diese Methode ist in der Regel am besten geeignet, da sie weniger Anfragen erfordert und damit eine bessere Leistung bietet.
-
In mehreren Teilen. Bei diesem Ansatz werden Uploads in mehreren Anfragen durch Aufteilung der Daten durchgeführt. Die Daten werden in Vielfaches von
x-goog-upload-chunk-granularityaufgeteilt. Bei Bedarf können die aufgeteilten Anfragen wiederholt werden.Verwenden Sie diesen Ansatz in folgenden Fällen:
- Sie müssen die bei einer einzelnen Anfrage übertragene Datenmenge reduzieren. Dies kann erforderlich sein, wenn für einzelne Anfragen ein festes Zeitlimit gilt.
- Sie müssen einen benutzerdefinierten Indikator angeben, der den Upload-Fortschritt anzeigt.
- Sie müssen wissen, wann es sicher ist, Daten zu verwerfen.
Einzelanfrage
So laden Sie die Datei in einer einzelnen Anfrage hoch:
- Erstellen Sie eine
POST-Anfrage an die URL der fortsetzbaren Sitzung. - Fügen Sie die Daten der Datei in den Anfragetext ein.
Fügen Sie die folgenden HTTP-Header hinzu:
Content-Length: Legen Sie als Wert die Anzahl von Byte in der Datei fest.X-Goog-Upload-Command: Legen Sieupload, finalizefest.
Senden Sie die Anfrage.
Wenn die Uploadanfrage unterbrochen wird oder Sie eine 5xx-Antwort erhalten, folgen Sie der Anleitung unter Unterbrochenen Upload fortsetzen.
Wenn die Anfrage erfolgreich ist, erhalten Sie den HTTP-Statuscode 200 OK und ein Uploadtoken im Antworttext.
Erstellen Sie das Medienelement mit diesem Uploadtoken.
Mehrere Blöcke
So laden Sie die Datei in mehreren Teilen hoch:
- Erstellen Sie eine
POST-Anfrage an die URL der fortsetzbaren Sitzung. -
Fügen Sie die Daten des Teils in den Anfragetext ein.
Erstellen Sie die anderen Blöcke mit Ausnahme des letzten Blocks, der den Upload abschließt, in Vielfachen der zulässigen Größe der Blöcke. Die Chunk-Größe sollte so groß wie möglich sein, damit der Upload effizient ist.
-
Fügen Sie die folgenden HTTP-Header hinzu:
Content-Length: Legen Sie als Wert die Anzahl von Byte im Block fest.X-Goog-Upload-Command: Legen Sieuploadfest. Legen Sie für den letzten Blockupload, finalizefest.X-Goog-Upload-Offset: Legen Sie den Wert auf den Offset fest, in dem die Byte geschrieben werden sollen. Die Bytes müssen nacheinander hochgeladen werden. Der erste Offset ist0.
- Senden Sie die Anfrage.
Wenn die Uploadanfrage unterbrochen wird oder Sie eine
5xx-Antwort erhalten, folgen Sie der Anleitung unter Unterbrochenen Upload fortsetzen. - Wiederholen Sie die obigen Schritte für jeden verbleibenden Block in der Datei.
Wenn die Anfrage erfolgreich ist, erhalten Sie den HTTP-Statuscode 200 OK und ein Uploadtoken im Antworttext.
Erstellen Sie das Medienelement mit diesem Uploadtoken.
Beispiel
Einzelanfrage
Das folgende Beispiel zeigt eine fortsetzbare Anfrage zum Hochladen einer 3.039.417 Byte großen JPEG-Datei in einer einzelnen Anfrage.
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
Die Antwort enthält die Upload-URL und die erwartete Chunk-Größe:
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
Die endgültige Uploadanfrage:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 3039417 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 0 [BYTES 0-4199999]
Mehrere Blöcke
Das folgende Beispiel zeigt eine fortsetzbare Anfrage zum Hochladen einer 3.039.417 Byte großen JPEG-Datei in mehreren Blöcken. Dabei werden die URL der fortsetzbaren Sitzung und der Detaillierungsgrad der zulässigen Chunk-Größe aus dem vorherigen Schritt verwendet.
In diesem Beispiel wird eine Chunk-Größe von 262.144 Byte verwendet, die bei der Initialisierung der Uploadsitzung im Header-Feld x-goog-upload-chunk-granularity zurückgegeben wurde. Jeder Upload enthält Byte,die ein Vielfaches von 262.144 sind.
Initialisieren Sie die Uploadsitzung, um die Upload-URL und die Chunkgröße wie im vorherigen Schritt beschrieben zu erhalten:
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
Die Antwort enthält die Upload-URL und die erwartete Chunk-Größe:
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
Erster Chunk:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 0 [BYTES 0-1048575]
Zweiter Chunk:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 1048576 [BYTES 1048576-2097151]
Letzter Teil:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 942265 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 2097152 [BYTES 2097152-4200000]
Unterbrochenen Upload fortsetzen
Wenn die Uploadanfrage unterbrochen wird oder ein Nicht-200-HTTP-Statuscode zurückgegeben wird, fragen Sie den Server ab, um herauszufinden, welcher Anteil des Uploads erfolgreich war.
Hier ist eine POST-Anfrage an die URL der fortsetzbaren Sitzung. X-Goog-Upload-Command sollte auf query festgelegt sein.
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: query
Die Antwort vom Server enthält den HTTP-Statuscode 200 OK und die aktuelle Größe des Uploads.
HTTP/1.1 200 OK X-Goog-Upload-Status: active X-Goog-Upload-Size-Received: 100
Du kannst den Upload dann an dieser Stelle fortsetzen. Sie müssen mit dem vom Server angegebenen Offset fortfahren, es sei denn, Sie senden einen kombinierten Upload- und Finalisierungsbefehl. In diesem Fall können Sie auch bei Offset 0 fortfahren.
Wenn der Header X-Goog-Upload-Status in der HTTP-Antwort Ihres Abfragebefehls vorhanden ist und der Wert nicht active ist, bedeutet das, dass der Upload bereits beendet wurde.