Fortsetzbaren Upload durchführen

Auf dieser Seite wird beschrieben, wie Sie in der Street View Publish API eine Anfrage für einen fortsetzbaren Upload stellen. Mit diesem Protokoll können Sie einen Uploadvorgang fortsetzen, nachdem ein Kommunikationsfehler den Datenfluss unterbrochen hat. Verwenden Sie diese Option 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.

Wenn Sie kleine Dateien über eine zuverlässige Netzwerkverbindung senden, können Sie stattdessen einen einfachen Upload verwenden.

Fortsetzbare Uploadsitzung starten

Nachdem Sie eine uploadUrl erhalten haben, können Sie eine fortsetzbare Uploadsitzung initiieren:

  1. Erstellen Sie eine POST-Anfrage an die uploadUrl.

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

    • X-Goog-Upload-Protocol: Legen Sie resumable fest.
    • X-Goog-Upload-Header-Content-Length: Legen Sie als Wert die Gesamtzahl der Byte für die Dateidaten fest, die in nachfolgenden Anfragen übertragen werden.
    • X-Goog-Upload-Header-Content-Type: Legen Sie den MIME-Typ der Dateidaten fest.
    • X-Goog-Upload-Command: Legen Sie start fest.

  3. Senden Sie die Anfrage.

Beispiel: Fortsetzbare Uploadsitzung starten

Das folgende Beispiel zeigt, wie Sie eine fortsetzbare Sitzung starten, um eine neue Datei hochzuladen. In diesem Fall ist die Datei ein Bild und die Gesamtzahl der Byte in der Datei beträgt 4200000. Der Anfragetext ist leer. Daher ist der Content-Length-Header auf „0“ gesetzt.

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

Unter URL der fortsetzbaren Sitzung speichern wird beschrieben, wie die Antwort auf die Anfrage zum Initiieren der Sitzung für den fortsetzbaren Upload verarbeitet wird.

URL der fortsetzbaren Sitzung speichern

Auf die Anfrage zum Starten einer fortsetzbaren Uploadsitzung antwortet der Server mit dem HTTP-Statuscode 200 OK und dem folgenden Header:

  • X-Goog-Upload-URL: Eine eindeutige URL, die verwendet werden muss, um den Upload über alle verbleibenden Anfragen hinweg abzuschließen.

Kopieren Sie die URL der fortsetzbaren Sitzung und speichern Sie sie, damit Sie sie für nachfolgende Anfragen verwenden können.

Beispiel: URL der fortsetzbaren Sitzung speichern

Das folgende Beispiel zeigt eine Antwort, die eine URL für eine fortsetzbar Sitzung und eine Anforderung an die Größe enthält.

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

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 am besten geeignet, da er weniger Anfragen erfordert und somit eine bessere Leistung erzielt.
  2. In mehreren Teilen. Verwenden Sie diesen Ansatz in folgenden Fällen:
    • Sie müssen die Menge der bei einer einzelnen Anfrage übertragenen Daten reduzieren. Dies ist möglicherweise erforderlich, wenn für einzelne Anfragen eine feste Zeitbegrenzung vorliegt.
    • Sie müssen eine benutzerdefinierte Anzeige bereitstellen, 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:

  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 die Anzahl der Bytes in der Datei fest.
    • X-Goog-Upload-Command: Legen Sie upload, finalize fest.

  4. Senden Sie die Anfrage.

Wenn die Uploadanfrage unterbrochen wird oder Sie eine 5xx-Antwort erhalten, folgen Sie der Anleitung unter Unterbrochenen Upload fortsetzen.

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 Teile in Vielfachen von 2 MiB (Mebibyte), 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.

  3. 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 Sie upload fest. Legen Sie für den letzten Block upload, finalize fest.
    • X-Goog-Upload-Offset: Legen Sie den Offset fest, an dem die Bytes geschrieben werden sollen. Die Bytes müssen seriell hochgeladen werden.

  4. Senden Sie die Anfrage. Wenn die Uploadanfrage unterbrochen wird oder Sie eine 5xx-Antwort erhalten, folgen Sie der Anleitung unter Unterbrochenen Upload fortsetzen.

  5. Wiederholen Sie die Schritte 1 bis 4 für jeden verbleibenden Teil der Datei.

Beispiel: Datei hochladen

Einzelanfrage

Das folgende Beispiel zeigt eine fortsetzbare Anfrage zum Hochladen einer vollständigen 4.200.000 Byte großen JPEG-Datei in einer einzelnen Anfrage unter Verwendung der URL der fortsetzbaren Sitzung aus dem vorherigen Schritt:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

Wenn die Anfrage erfolgreich war, wird der HTTP-Statuscode 200 OK zurückgegeben.

Mehrere Chunks

Das folgende Beispiel zeigt eine fortsetzbare Anfrage zum Hochladen einer 4.200.000 Byte großen JPEG-Datei in mehreren Teilen unter Verwendung der URL der fortsetzbaren Sitzung und der im vorherigen Schritt ermittelten Größe. In diesem Beispiel wird eine Blockgröße von 2097000 Byte verwendet, was ein Vielfaches von 2 MiB (Mebibyte) ist.

Erster Block: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

Zweiter Block: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

Letzter Block: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-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:

  1. Erstellen Sie eine POST-Anfrage an die URL der fortsetzbaren Sitzung.
  2. Legen Sie den Wert X-Goog-Upload-Command auf query fest.
  3. Senden Sie die Anfrage.

Der Server antwortet mit dem HTTP-Statuscode 200 OK und der aktuellen 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 X-Goog-Upload-Status-Header in der HTTP-Antwort Ihres Abfragebefehls vorhanden ist und der Wert nicht active ist, wurde der Upload bereits beendet.