Fortsetzbaren Upload durchführen

Auf dieser Seite wird beschrieben, wie du eine Anfrage für einen fortsetzbaren Upload in der Street View Publish API sendest. 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. wenn Sie eine Datei von einer mobilen App hochladen).

Fortsetzbare Uploads können auch die Bandbreitennutzung bei einem Netzwerkausfall reduzieren, da Sie große Dateiuploads nicht von Anfang an neu starten 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 starten:

  1. Erstellen Sie eine POST-Anfrage an 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 von Byte der Dateidaten fest, die in nachfolgenden Anfragen übertragen werden.
    • X-Goog-Upload-Header-Content-Type: Legen Sie als Wert 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 Datei hat insgesamt 4.200.000 Byte. Beachten Sie, dass der Text der Anfrage leer ist. Daher ist der Header Content-Length 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 fortsetzbaren Uploadsitzung verarbeitet wird.

URL der fortsetzbaren Sitzung speichern

Für die Anfrage zum Starten einer Sitzung für einen fortsetzbaren Upload antwortet der Server mit dem HTTP-Statuscode 200 OK, der den folgenden Header enthält:

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

Kopieren und speichern Sie die fortsetzbare Wiederherstellungs-URL, damit Sie sie für nachfolgende Anfragen verwenden können.

Beispiel: URL der fortsetzbaren Sitzung speichern

Das folgende Beispiel zeigt eine Antwort, die eine fortsetzbare Sitzungs-URL und eine Anforderung an den Detaillierungsgrad der 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 bietet.
  2. In mehreren Teilen. Verwenden Sie diesen Ansatz in folgenden Fällen:
    • Bei einer einzelnen Anfrage müssen Sie die Menge der übertragenen Daten 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:

  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 von Byte 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 Blöcke

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 Blöcke in Vielfachen von 2 MiB (Mebibyte), mit Ausnahme des letzten Blocks, der den Upload abschließt. Halten 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 Block 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, mit dem die Byte geschrieben werden sollen. Die Byte müssen nacheinander 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 gesamten JPEG-Datei mit 4.200.000 Byte in einer einzelnen Anfrage. Dabei wird die URL der fortsetzbaren Sitzung aus dem vorherigen Schritt verwendet:

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 ist, erhalten Sie den HTTP-Statuscode 200 OK.

Mehrere Blöcke

Das folgende Beispiel zeigt eine fortsetzbare Anfrage zum Hochladen einer 4.200.000 Byte großen JPEG-Datei in mehreren Blöcken. Dabei werden die URL der fortsetzbaren Sitzung und der Detaillierungsgrad der Größe aus dem vorherigen Schritt verwendet. In diesem Beispiel wird eine Chunk-Größe von 2097.000 Byte verwendet, die ein Vielfaches von 2 MiB (Mebibyte) ist.

Erster Chunk: 

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 Chunk: 

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, welcher Anteil des Uploads 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 an dem vom Server angegebenen Offset fortfahren, es sei denn, Sie senden einen kombinierten Upload- und Abschlussbefehl. 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, wurde der Upload bereits beendet.