Fortsetzbare Uploads durchführen

Zu den Konzepten

Auf dieser Seite wird beschrieben, wie Sie in der Cloud Storage JSON API und der Cloud Storage XML 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.

Fortsetzbare Uploadsitzung starten

So starten Sie eine fortsetzbare Uploadsitzung:

JSON API

  1. Rufen Sie ein Zugriffstoken für die Autorisierung aus dem OAuth 2.0 Playground ab. Konfigurieren Sie den Playground so, dass Ihre eigenen OAuth-Anmeldedaten verwendet werden.
  2. Erstellen Sie optional eine .json-Datei, die die Metadaten für das Objekt enthält, das Sie hochladen möchten.

  3. Verwenden Sie cURL, um die JSON API mit einer POST-Objektanfrage aufzurufen:

    curl -i -X POST --data-binary @METADATA_LOCATION \
        -H "Authorization: Bearer OAUTH2_TOKEN" \
        -H "Content-Type: application/json" \
        -H "Content-Length: INITIAL_REQUEST_LENGTH" \
        "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=resumable&name=OBJECT_NAME"

    Hierbei gilt:

    • METADATA_LOCATION ist der lokale Pfad zur JSON-Datei, die die optionalen Metadaten enthält, die Sie im vorherigen Schritt angegeben haben. Wenn Sie keine Metadatendatei hinzufügen, nehmen sie dies nicht mit auf, ebenso wie --data-binary @ und den Content-Type-Header.
    • OAUTH2_TOKEN ist das Zugriffstoken, das Sie in Schritt 1 generiert haben.
    • INITIAL_REQUEST_LENGTH ist die Anzahl der Byte im Text dieser ersten Anfrage, z. B. 79. Dies ist bei Verwendung der aufgeteilten Transferverschlüsselung nicht erforderlich.
    • BUCKET_NAME ist der Name des Buckets, in den Sie das Objekt hochladen. Beispiel: my-bucket
    • OBJECT_NAME ist der Name, den Sie dem Objekt geben möchten. Beispiel: pets/dog.png Dies ist nicht erforderlich, wenn Sie in der Objektmetadatendatei in Schritt 2 einen name eingefügt haben.

    Wenn Sie Cross-Origin Resource Sharing aktiviert haben, sollten Sie auch in diesen und nachfolgenden Uploadanfragen einen Origin-Header einfügen.

    Optionale Header, die Sie der Anfrage hinzufügen können, sind z. B. X-Upload-Content-Type und X-Upload-Content-Length.

    Wenn der Vorgang erfolgreich war, enthält die Antwort den Statuscode 200.

  4. Speichern Sie den URI der fortsetzbaren Sitzung im Location-Header der Antwort auf Ihre POST-Objektanfrage.

    Dieser URI wird in nachfolgenden Anfragen verwendet, um die Objektdaten hochzuladen.

XML API

  1. Rufen Sie ein Zugriffstoken für die Autorisierung aus dem OAuth 2.0 Playground ab. Konfigurieren Sie den Playground so, dass Ihre eigenen OAuth-Anmeldedaten verwendet werden.
  2. Verwenden Sie cURL, um die XML API mit einer POST-Objektanfrage aufzurufen, die einen leeren Textkörper enthält:

    curl -i -X POST -H "Authorization: Bearer OAUTH2_TOKEN" \
        -H "Content-Length: 0" \
        -H "Content-Type: OBJECT_CONTENT_TYPE" \
        -H "x-goog-resumable: start" \
        "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    Hierbei gilt:

    • OAUTH2_TOKEN ist das Zugriffstoken, das Sie in Schritt 1 generiert haben.
    • OBJECT_CONTENT_TYPE ist der Inhaltstyp des Objekts. Beispiel: image/png Wenn Sie keinen Inhaltstyp angeben, legt das Cloud Storage-System die Content-Type-Metadaten für das Objekt auf application/octet-stream fest.
    • BUCKET_NAME ist der Name des Buckets, in den Sie das Objekt hochladen. Beispiel: my-bucket
    • OBJECT_NAME ist der Name, den Sie dem Objekt geben möchten. Beispiel: pets/dog.png

    Wenn Sie Cross-Origin Resource Sharing aktiviert haben, sollten Sie auch in diesen und nachfolgenden Uploadanfragen einen Origin-Header einfügen.

    Wenn der Vorgang erfolgreich war, enthält die Antwort die Statusmeldung 201.

  3. Speichern Sie den URI der fortsetzbaren Sitzung im Location-Header der Antwort auf Ihre POST-Objektanfrage.

    Dieser URI wird in nachfolgenden Anfragen verwendet, um die Objektdaten hochzuladen.

Datei hochladen

Nachdem Sie einen fortsetzbaren Upload gestartet haben, gibt es zwei Möglichkeiten, die Daten des Objekts hochzuladen:

  • In einer Einzelanfrage: Dieser Ansatz ist in der Regel am besten geeignet, da er weniger Anfragen erfordert und somit eine bessere Leistung erzielt.
  • In mehreren Blöcken: Verwenden Sie diesen Ansatz, wenn Sie die Datenmenge reduzieren müssen, die bei einer einzelnen Anfrage übertragen wird, z. B. wenn für einzelne Anfragen ein festes Zeitlimit vorgegeben ist oder wenn Sie die Gesamtgröße des Uploads bei Beginn des Uploads nicht kennen.

Einzelanfrageupload

So laden Sie die Datei in einer einzelnen Anfrage hoch:

JSON API

  1. Verwenden Sie cURL, um die JSON API mit einer PUT-Objektanfrage aufzurufen:

    curl -i -X PUT --data-binary @OBJECT_LOCATION \
        -H "Content-Length: OBJECT_SIZE" \
        "SESSION_URI"

    Hierbei gilt:

    • OBJECT_LOCATION ist der lokale Pfad zu Ihrem Objekt. Beispiel: Desktop/dog.png
    • OBJECT_SIZE ist die Anzahl der Byte in Ihrem Objekt. Beispiel: 20000000
    • SESSION_URI ist der Wert, der im Location-Header zurückgegeben wird, wenn Sie den fortsetzbaren Upload gestartet haben.

XML API

  1. Verwenden Sie cURL, um die XML API mit einer PUT-Objektanfrage aufzurufen:

    curl -i -X PUT --data-binary @OBJECT_LOCATION \
        -H "Content-Length: OBJECT_SIZE" \
        "SESSION_URI"

    Hierbei gilt:

    • OBJECT_LOCATION ist der lokale Pfad zu Ihrem Objekt. Beispiel: Desktop/dog.png
    • OBJECT_SIZE ist die Anzahl der Byte in Ihrem Objekt. Beispiel: 20000000
    • SESSION_URI ist der Wert, der im Location-Header zurückgegeben wird, wenn Sie den fortsetzbaren Upload gestartet haben.

Wenn der Upload abgeschlossen ist, erhalten Sie eine 200 OK- oder 201 Created-Antwort sowie alle Metadaten, die der Ressource zugewiesen sind.

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

Mehrere Blockuploads

So laden Sie die Datei in mehreren Teilen hoch:

JSON API

  1. Erstellen Sie einen Datenblock aus der Datei, die Sie hochladen möchten.

    Die Größe des Blocks sollte ein Vielfaches von 256 KiB (256 x 1.024 Byte) sein, es sei denn, dies ist der letzte Teil des Uploads. Durch größere Blocks werden Uploads in der Regel effizienter. Wir empfehlen, als Blockgröße 8 MiB zu verwenden.

  2. Verwenden Sie cURL, um die JSON API mit einer PUT-Objektanfrage aufzurufen:

    curl -i -X PUT --data-binary @CHUNK_LOCATION \
        -H "Content-Length: CHUNK_SIZE" \
        -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    Hierbei gilt:

    • CHUNK_LOCATION ist der lokale Pfad zum Block, den Sie gerade hochladen.
    • CHUNK_SIZE ist die Anzahl der Byte, die Sie in der aktuellen Anfrage hochladen. Beispiel: 524288
    • CHUNK_FIRST_BYTE ist das Startbyte im gesamten Objekt, das der hochgeladene Block enthält.
    • CHUNK_LAST_BYTE ist das Endbyte im gesamten Objekt, das der hochgeladene Block enthält.
    • TOTAL_OBJECT_SIZE ist die Gesamtgröße des Objekts, das Sie hochladen.
    • SESSION_URI ist der Wert, der im Location-Header zurückgegeben wird, wenn Sie den fortsetzbaren Upload gestartet haben.

    Ein Beispiel für Content-Range ist Content-Range: bytes 0-524287/2000000. Weitere Informationen zu diesem Header finden Sie unter Content-Range.

    Wenn die Anfrage erfolgreich ist, antwortet der Server mit 308 Resume Incomplete. Die Antwort enthält einen Range-Header. Verwenden Sie den höchsten Wert in diesem Header, um zu bestimmen, wo der nächste Block beginnt. Sie sollten nicht davon ausgehen, dass der Server alle Byte erhalten hat, die in der Anfrage gesendet wurden.

  3. Wiederholen Sie die oben genannten Schritte für jeden verbleibenden Datenblock, den Sie hochladen möchten.

XML API

  1. Erstellen Sie einen Datenblock aus der Datei, die Sie hochladen möchten.

    Die Größe des Blocks sollte ein Vielfaches von 256 KiB (256 x 1.024 Byte) sein, es sei denn, dies ist der letzte Teil des Uploads. Durch größere Blocks werden Uploads in der Regel effizienter. Wir empfehlen, als Blockgröße 8 MiB zu verwenden.

  2. Verwenden Sie cURL, um die XML API mit einer PUT-Objektanfrage aufzurufen:

    curl -i -X PUT --data-binary @CHUNK_LOCATION \
        -H "Content-Length: CHUNK_SIZE" \
        -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    Dabei gilt:

    • CHUNK_LOCATION ist der lokale Pfad zum Block, den Sie gerade hochladen.
    • CHUNK_SIZE ist die Anzahl der Byte, die Sie in der aktuellen Anfrage hochladen. Beispiel: 524288
    • CHUNK_FIRST_BYTE ist das Startbyte im gesamten Objekt, das der hochgeladene Block enthält.
    • CHUNK_LAST_BYTE ist das Endbyte im gesamten Objekt, das der hochgeladene Block enthält.
    • TOTAL_OBJECT_SIZE ist die Gesamtgröße des Objekts, das Sie hochladen.
    • SESSION_URI ist der Wert, der im Location-Header zurückgegeben wird, wenn Sie den fortsetzbaren Upload gestartet haben.

    Ein Beispiel für Content-Range ist Content-Range: bytes 0-524287/2000000. Weitere Informationen zu diesem Header finden Sie unter Content-Range.

    Wenn die Anfrage erfolgreich ist, antwortet der Server mit 308 Resume Incomplete. Die Antwort enthält einen Range-Header. Verwenden Sie den höchsten Wert in diesem Header, um zu bestimmen, wo der nächste Block beginnt. Sie sollten nicht davon ausgehen, dass der Server alle Byte erhalten hat, die in der Anfrage gesendet wurden.

  3. Wiederholen Sie die oben genannten Schritte für jeden verbleibenden Datenblock, den Sie hochladen möchten.

Sobald der Upload abgeschlossen ist, erhalten Sie eine 200 OK- oder 201 Created-Antwort sowie alle Metadaten, die der Ressource zugewiesen sind.

Wenn einer der Blockuploads unterbrochen wird oder Sie die Antwort 5xx erhalten, folgen Sie der Anleitung unter Unterbrochenen Upload fortsetzen.

Status eines fortsetzbaren Uploads prüfen

Wenn ein fortsetzbarer Upload unterbrochen wird oder Sie nicht sicher sind, ob der Upload abgeschlossen wurde, können Sie den Uploadstatus prüfen:

JSON API

  1. Verwenden Sie cURL, um die XML API mit einer PUT-Objektanfrage aufzurufen:

    curl -i -X PUT \
        -H "Content-Length: 0" \
        -H "Content-Range: bytes */OBJECT_SIZE" \
        "SESSION_URI"

    Hierbei gilt:

    • OBEJCT_SIZE ist die Gesamtzahl der Byte in Ihrem Objekt. Wenn Sie die Gesamtgröße Ihres Objekts nicht kennen, verwenden Sie für diesen Wert *.
    • SESSION_URI ist der Wert, der im Location-Header zurückgegeben wird, wenn Sie den fortsetzbaren Upload gestartet haben.

XML API

  1. Verwenden Sie cURL, um die XML API mit einer PUT-Objektanfrage aufzurufen:

    curl -i -X PUT \
        -H "Content-Length: 0" \
        -H "Content-Range: bytes */OBJECT_SIZE" \
        "SESSION_URI"

    Hierbei gilt:

    • OBEJCT_SIZE ist die Gesamtzahl der Byte in Ihrem Objekt. Wenn Sie die Gesamtgröße Ihres Objekts nicht kennen, verwenden Sie für diesen Wert *.
    • SESSION_URI ist der Wert, der im Location-Header zurückgegeben wird, wenn Sie den fortsetzbaren Upload gestartet haben.

Eine 200 OK- oder 201 Created-Antwort gibt an, dass der Upload abgeschlossen wurde und keine weiteren Maßnahmen erforderlich sind.

Die 308 Resume Incomplete-Antwort gibt an, dass Sie das Hochladen der Datei fortsetzen müssen.

  • Wenn Cloud Storage noch keine Byte erhalten hat, enthält die Antwort 308 keinen Range-Header. In diesem Fall sollten Sie den Upload von Anfang an starten.
  • Andernfalls hat die Antwort 308 einen Range-Header. Dieser gibt an, welche Byte Cloud Storage bisher empfangen hat. Verwenden Sie diesen Wert, wenn Sie einen unterbrochenen Upload fortsetzen möchten.

Unterbrochenen Upload fortsetzen

Wenn die Uploadanfrage vor dem Erhalten einer Antwort beendet wird oder wenn Sie die Antwort 503 oder 500 erhalten, müssen Sie den unterbrochenen Upload an der Stelle fortsetzen, an der er unterbrochen wurde. So setzen Sie einen unterbrochenen Upload fort:

JSON API

  1. Prüfen Sie den Status des fortsetzbaren Uploads.

  2. Speichern Sie den höchsten Wert des Range-Headers, der in der Antwort auf Ihre Statusprüfung enthalten ist. Wenn die Antwort keinen Range-Header hat, hat Cloud Storage noch kein Byte empfangen und Sie sollten den Upload von vorne beginnen.

  3. Achten Sie darauf, dass die Objektdaten, die Sie hochladen möchten, mit dem Byte nach dem höchsten Wert im Range-Header beginnen.

  4. Verwenden Sie cURL, um die JSON API mit einer PUT-Objektanfrage aufzurufen, die das Byte nach dem Wert im Range-Header abruft:

    curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
        -H "Content-Length: UPLOAD_SIZE_REMAINING" \
        -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    Hierbei gilt:

    • PARTIAL_OBJECT_LOCATION ist der lokale Pfad zum verbleibenden Teil der Daten, die Sie hochladen möchten.
    • UPLOAD_SIZE_REMAINING ist die Anzahl der Byte, die Sie in der aktuellen Anfrage hochladen. Wenn Sie beispielsweise den Rest eines Objekts mit einer Gesamtgröße von 20.000.000 hochladen und der Upload wurde nach den Byte 0–42 unterbrochen, dann hat UPLOAD_SIZE_REMAINING den Wert 1999957.
    • NEXT_BYTE ist die nächste Ganzzahl nach dem in Schritt 2 gespeicherten Wert. Ist 42 beispielsweise der höchste Wert in Schritt 2, dann ist 43 der Wert für NEXT_BYTE.
    • LAST_BYTE ist das Endbyte, das in dieser PUT-Anfrage enthalten ist. Wenn beispielsweise der Upload eines Objekts abgeschlossen werden soll, dessen Gesamtgröße 20000000 ist, dann ist 1999999 der Wert für LAST_BYTE.
    • TOTAL_OBJECT_SIZE ist die Gesamtgröße des Objekts, das Sie hochladen. Beispiel: 20000000
    • SESSION_URI ist der Wert, der im Location-Header zurückgegeben wird, wenn Sie den fortsetzbaren Upload gestartet haben.

XML API

  1. Prüfen Sie den Status des fortsetzbaren Uploads.

  2. Speichern Sie den höchsten Wert des Range-Headers, der in der Antwort auf Ihre Statusprüfung enthalten ist. Wenn die Antwort keinen Range-Header hat, hat Cloud Storage noch kein Byte empfangen und Sie sollten den Upload von vorne beginnen.

  3. Achten Sie darauf, dass die Objektdaten, die Sie hochladen möchten, mit dem Byte nach dem höchsten Wert im Range-Header beginnen.

  4. Verwenden Sie cURL, um die XML API mit einer PUT-Objektanfrage aufzurufen, die das Byte nach dem Wert im Range-Header abruft:

    curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
        -H "Content-Length: UPLOAD_SIZE_REMAINING" \
        -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    Hierbei gilt:

    • PARTIAL_OBJECT_LOCATION ist der lokale Pfad zum verbleibenden Teil der Daten, die Sie hochladen möchten.
    • UPLOAD_SIZE_REMAINING ist die Anzahl der Byte, die Sie in der aktuellen Anfrage hochladen. Wenn Sie beispielsweise den Rest eines Objekts mit einer Gesamtgröße von 20.000.000 hochladen und der Upload wurde nach den Byte 0–42 unterbrochen, dann hat UPLOAD_SIZE_REMAINING den Wert 1999957.
    • NEXT_BYTE ist die nächste Ganzzahl nach dem in Schritt 2 gespeicherten Wert. Ist 42 beispielsweise der höchste Wert in Schritt 2, dann ist 43 der Wert für NEXT_BYTE.
    • LAST_BYTE ist das Endbyte, das in dieser PUT-Anfrage enthalten ist. Wenn beispielsweise der Upload eines Objekts abgeschlossen werden soll, dessen Gesamtgröße 20000000 ist, dann ist 1999999 der Wert für LAST_BYTE.
    • TOTAL_OBJECT_SIZE ist die Gesamtgröße des Objekts, das Sie hochladen. Beispiel: 20000000
    • SESSION_URI ist der Wert, der im Location-Header zurückgegeben wird, wenn Sie den fortsetzbaren Upload gestartet haben.

Sie können Uploads beliebig oft fortsetzen. Wenn Sie aber Anfragen wiederholen, folgen Sie den Richtlinien für Wiederholungsversuche bei fortsetzbaren Uploads.

Wenn die Datei erfolgreich hochgeladen wurde, antwortet Cloud Storage mit dem Statuscode 200 OK oder 201 created.

Upload abbrechen

So können Sie einen fortsetzbaren Upload abbrechen und eine weitere Verarbeitung verhindern:

JSON API

  1. Verwenden Sie cURL, um die JSON API mit einer DELETE-Anfrage aufzurufen:

    curl -X DELETE -H "Content-Length: 0" \
      "SESSION_URI"

    Hierbei gilt:

XML API

  1. Verwenden Sie cURL, um die XML API mit einer DELETE-Anfrage aufzurufen:

    curl -X DELETE -H "Content-Length: 0" \
      "SESSION_URI"

    Hierbei gilt:

Bei Erfolg enthält die Antwort den Statuscode 499. Bei zukünftigen Abfrageversuchen oder Versuchen, den Upload fortzusetzen, wird als Antwort 4xx zurückgegeben.

Weitere Informationen