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).

Fortsetzbare Uploads können auch die Bandbreitennutzung bei einem Netzwerkausfall reduzieren, da Sie Uploads großer Dateien nicht von Beginn 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 ein 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 Gesamtanzahl von Byte für die Dateidaten fest, die in nachfolgenden Anfragen übertragen werden.
    • X-Goog-Upload-Header-Content-Type: Auf den MIME-Typ der Dateidaten festgelegt.
    • 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 zum Hochladen einer neuen Datei starten. In diesem Fall ist die Datei ein Bild und die Gesamtzahl der Bytes in der Datei beträgt 4.200.000. Der Textbereich der Anfrage 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 URI der fortsetzbaren Sitzung speichern wird beschrieben, wie die Antwort auf die Anfrage zum Starten der fortsetzbaren Uploadsitzung 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 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 fortsetzbare Sitzung und eine Anforderung für die Größenabstufung 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 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 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 als Wert die Anzahl von 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 Teile

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 Chunk 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 insgesamt 4.200.000 Byte großen JPEG-Datei in einer einzigen Anfrage unter Verwendung der im vorherigen Schritt ermittelten Sitzungs-URL:

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 Teile

Das folgende Beispiel zeigt eine fortsetzbare Anfrage zum Hochladen einer 4.200.000 Byte großen JPEG-Datei in mehreren Chunks unter Verwendung der im vorherigen Schritt abgerufenen fortsetzbaren Sitzungs-URL und der Größenabstufung. In diesem Beispiel wird eine Blockgröße von 2.097.000 Byte verwendet, was einem Vielfachen von 2 MiB (Mebibyte) entspricht.

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 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: 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 HTTP-Statuscode erhalten, der nicht 200 ist, fragen Sie den Server ab, wie viel 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 den Upload an dem vom Server bereitgestellten Offset fortsetzen, es sei denn, Sie senden einen kombinierten Upload- und Finalisierungsbefehl. In diesem Fall können Sie den Upload auch an 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.