Fortsetzbare Uploads

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 für den fortsetzbaren Upload in folgenden Fällen:

  • Sie laden große Dateien hoch.
  • Die Wahrscheinlichkeit einer Netzwerkunterbrechung oder eines anderen Übertragungsfehlers ist hoch (z. B. wenn Sie eine Datei von einer mobilen App hochladen).

Fortsetzbare Uploads können auch die Bandbreitennutzung reduzieren, wenn ein Netzwerk vorhanden ist da Sie große Datei-Uploads nicht über die beginnen.

Schritt 1: Uploadsitzung starten

Initiieren Sie eine fortsetzbare Upload-Sitzung, indem Sie eine POST-Anfrage an https://photoslibrary.googleapis.com/v1/uploads Fortsetzbaren Upload verwenden Die in dieser Anfrage zurückgegebene URL. Laden Sie die Datei hoch.

Die POST-Anfrage muss die folgenden Header enthalten:

Headerfelder
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 dafür den MIME-Typ der Datei fest. Beispiel: image/jpeg
X-Goog-Upload-Protocol Setze diese Property auf resumable.
X-Goog-Upload-Raw-Size Legen Sie als Wert die Gesamtzahl der Byte der zu übertragenden Dateidaten fest.

Hier ist ein POST-Anfrage-Header:

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 erfolgreicher Ausführung gibt die POST-Anfrage den HTTP-Statuscode 200 OK zurück, einschließlich den folgenden Header.

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 Blöcken, alle Uploads mit Ausnahme des letzten muss als Vielfaches dieses Werts erfolgen. Das heißt, die Anzahl der Uploadbyte der Datei muss auf diesen Wert ausgerichtet sein. Im letzten Teil können Sie die restlichen Bytes.

Das Header-Feld X-Goog-Upload-URL enthält eine eindeutige URL, mit der den Upload mit allen anderen Anfragen abschließen. Kopieren und speichern 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:

  1. In einer einzelnen Anfrage. Dieser Ansatz ist in der Regel der beste, da weniger Anfragen benötigt werden und dadurch eine bessere Leistung erzielt wird.

  2. In mehreren Teilen. Bei diesem Ansatz werden Uploads in mehreren Anfragen, indem die Daten aufgeteilt werden. Die Daten sind in Blöcke unterteilt, Ein Vielfaches von x-goog-upload-chunk-granularity. Bei Bedarf können Sie können die aufgeteilten Anfragen wiederholt werden.

    Verwenden Sie diesen Ansatz in folgenden Fällen:

    • Sie müssen die Menge der übertragenen Daten auf einem Dies ist z. B. erforderlich, wenn es ein festes Zeitlimit für von individuellen Anträgen.
    • Sie müssen einen benutzerdefinierten Indikator angeben, der den Upload anzeigt Fortschritt.
    • Sie müssen wissen, wann es sicher ist, Daten zu verwerfen.

Einzelanfrage

So laden Sie die Datei in einer einzelnen Anfrage hoch:

  1. Erstellen Sie eine POST-Anfrage an die URL der fortsetzbaren Sitzung.
  2. Fügen Sie die Daten der Datei in den Anfragetext ein.

  3. Fügen Sie die folgenden HTTP-Header hinzu:

    • Content-Length: Legen Sie als Wert die Anzahl der Byte im -Datei.
    • X-Goog-Upload-Command: Legen Sie upload, finalize fest.

  4. Senden Sie die Anfrage.

Wenn die Uploadanfrage unterbrochen wird oder Sie die Fehlermeldung 5xx erhalten erhalten Sie unter Wiederaufnahme einer unterbrochener Upload.

Wenn die Anfrage erfolgreich ist, erhalten Sie den HTTP-Status 200 OK. und ein Upload-Token im Antworttext. Erstellen das Medienelement mit diesem Upload-Token.

Mehrere Chunks

So laden Sie die Datei in mehreren Teilen hoch:

  1. Erstellen Sie eine POST-Anfrage an die URL der fortsetzbaren Sitzung.

  2. 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. Behalten Sie die Chunk-Größe so groß wie möglich, damit der Upload effizient ist.

  3. Fügen Sie die folgenden HTTP-Header hinzu:

    • Content-Length: Legen Sie als Wert die Anzahl der Byte im Chunk.
    • X-Goog-Upload-Command: Legen Sie upload fest. Legen Sie für den letzten Block upload, finalize fest.
    • X-Goog-Upload-Offset: Auf den Versatz festlegen, mit dem der Bytes geschrieben werden. Die Bytes müssen hochgeladen werden, aufeinanderfolgen. Der erste Offset ist 0.
  4. Senden Sie die Anfrage.

    Wenn die Uploadanfrage unterbrochen wird oder Sie eine 5xx erhalten erhalten Sie unter Wiederaufnahme einer unterbrochener Upload.

  5. Wiederholen Sie diese Schritte für jeden verbleibenden Block in der Datei.

Wenn die Anfrage erfolgreich ist, erhalten Sie den HTTP-Status 200 OK. und ein Upload-Token im Antworttext. Erstelle das Medienelement mit diesem Upload-Token.

Beispiel

Einzelanfrage

Das folgende Beispiel zeigt eine fortsetzbare Anfrage zum Hochladen einer 3.039.417 Byte große 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 Chunks

Das folgende Beispiel zeigt eine fortsetzbare Anfrage zum Hochladen einer 3.039.417 Byte große JPEG-Datei in mehreren Blöcken, unter Verwendung der fortsetzbaren Sitzung URL und den zulässigen Detaillierungsgrad für die Blockgröße aus dem vorherigen Schritt. In diesem Beispiel wird eine Blockgröße von 262.144 Byte verwendet,die im Header-Feld, x-goog-upload-chunk-granularity, wenn der Parameter Uploadsitzung wurde initialisiert. Beachten Sie, dass jeder Upload Bytes enthält, sind ein Vielfaches von 262.144.

Initialisieren Sie die Uploadsitzung, um die Upload-URL und die Blockgröße zu erhalten 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 Teil:

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 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 Sie einen Nicht-200-HTTP-Status erhalten Code den Server abfragen, um herauszufinden, wie lange 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

Der Upload kann dann mit diesem Versatz fortgesetzt werden. 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 X-Goog-Upload-Status-Header in der HTTP-Antwort des Abfragebefehls ist vorhanden und der Wert ist nicht active. Dies bedeutet, dass der Upload wurde bereits gekündigt.