Auf dieser Seite wird beschrieben, wie Sie über das REST-Protokoll eine Anfrage für einen fortsetzbaren Upload an die Google Fotos-Mediathek API senden. Mit diesem Protokoll können Sie einen Uploadvorgang fortsetzen, nachdem ein Kommunikationsfehler den Datenfluss unterbrochen hat.
Verwenden Sie die Option „Fortsetzbarer Upload“ in folgenden Fällen:
- Sie laden große Dateien hoch.
- Die Wahrscheinlichkeit einer Netzwerkunterbrechung oder eines anderen Übertragungsfehlers ist hoch (z. B. beim Hochladen einer Datei über eine mobile App).
Mit fortsetzbaren Uploads lässt sich auch die Bandbreitennutzung bei einem Netzwerkausfall reduzieren, da Sie Uploads großer Dateien 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. Lade die Datei über die in dieser Anfrage zurückgegebene URL für den fortsetzbaren Upload hoch.
Die POST-Anfrage muss die folgenden Header enthalten:
| Header-Felder | |
|---|---|
Content-Length |
Legen Sie 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 der Byte für die 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 mit der folgenden Kopfzeile zurück.
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 Byte-Ausrichtung und die Größengranularität für alle vom Client gesendeten Datenblöcke. Wenn der Upload in mehreren Teilen erfolgt, müssen alle Uploads mit Ausnahme des letzten in Vielfachen dieses Werts erfolgen. Das bedeutet, dass die Upload-Byte der Datei auf diesen Wert ausgerichtet sein müssen. Im letzten Block können Sie die verbleibenden Bytes 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 URL für die fortsetzbare Sitzung, 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. Dieser Ansatz ist in der Regel am besten geeignet, da er weniger Anfragen erfordert und somit eine bessere Leistung erzielt.
-
In mehreren Teilen. Bei diesem Ansatz werden Uploads in mehreren Anfragen durchgeführt, indem die Daten in Blöcke aufgeteilt werden. Die Daten werden in Vielfache von
x-goog-upload-chunk-granularityaufgeteilt. Bei Bedarf können die gechunkten Anfragen noch einmal versucht werden.Verwenden Sie diesen Ansatz in folgenden Fällen:
- Sie müssen die Menge von Daten reduzieren, die bei einer einzelnen Anfrage übertragen werden. Dies ist möglicherweise erforderlich, wenn für einzelne Anfragen eine feste Zeitbegrenzung vorliegt.
- Sie müssen eine benutzerdefinierte Anzeige angeben, die den Uploadfortschritt 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 die Anzahl der 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 im Antworttext den HTTP-Statuscode 200 OK und ein Uploadtoken.
Erstelle das Medienelement mit diesem Upload-Token.
Mehrere Chunks
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 Teile in Vielfachen der zulässigen Größe von Teilen, mit Ausnahme des letzten Teils, der den Upload vervollständigt. Halten Sie die Blockgröße so groß wie möglich, damit der Upload effizient ist.
-
Fügen Sie die folgenden HTTP-Header hinzu:
Content-Length: Legen Sie als Wert die Anzahl von Bytes im Teil fest.X-Goog-Upload-Command: Legen Sieuploadfest. Für den letzten Blockupload, finalizefestlegen.X-Goog-Upload-Offset: Legen Sie den Offset fest, an dem die Bytes geschrieben werden sollen. Die Bytes müssen seriell hochgeladen werden. Der erste Offset ist0.
- Senden Sie die Anfrage.
Wenn die Uploadanfrage unterbrochen wird oder Sie die Antwort
5xxerhalten, folgen Sie der Anleitung unter Unterbrochenen Upload fortsetzen. - Wiederholen Sie diese Schritte für jeden verbleibenden Teil der Datei.
Wenn die Anfrage erfolgreich ist, erhalten Sie den HTTP-Statuscode 200 OK und ein Uploadtoken im Antworttext.
Erstelle das Medienelement mit diesem Upload-Token.
Beispiel
Einzelanfrage
Das folgende Beispiel zeigt eine fortsetzbare Anfrage zum Hochladen einer JPEG-Datei mit 3.039.417 Byte in einer einzigen 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 Größe des Chunks:
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 letzte 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 Chunks
Das folgende Beispiel zeigt eine fortsetzbare Anfrage zum Hochladen einer 3.039.417 Byte großen JPEG-Datei in mehreren Teilen unter Verwendung der URL der fortsetzbaren Sitzung und der im vorherigen Schritt ermittelten Granularität der zulässigen Größe der einzelnen Teile.
In diesem Beispiel wird eine Blockgröße von 262.144 Byte verwendet, die im Headerfeld x-goog-upload-chunk-granularity zurückgegeben wurde, als die Uploadsitzung initialisiert wurde. Beachten Sie, dass jeder Upload Byte enthält, die ein Vielfaches von 262.144 sind.
Initialisiere die Uploadsitzung, um die Upload-URL und die Größe des Chunks zu empfangen, wie im vorherigen Schritt beschrieben:
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 Block:
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 Block:
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 Block:
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 Sie einen Nicht-200-HTTP-Statuscode erhalten, fragen Sie den Server ab, um herauszufinden, wie groß der Upload 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
Sie können den Upload dann an dieser Stelle fortsetzen. Sie müssen den Upload am vom Server angegebenen Offset fortsetzen, es sei denn, Sie senden einen kombinierten Upload- und Abschlussbefehl. In diesem Fall können Sie den Upload auch bei Offset 0 fortsetzen.
Wenn der Header X-Goog-Upload-Status in der HTTP-Antwort Ihres Abfragebefehls vorhanden ist und der Wert nicht active ist, wurde der Upload bereits beendet.