Fortsetzbare Uploads durchführen

Übersicht

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.

Informationen zur Verwendung fortsetzbarer Uploads in der Google Cloud CLI und in den Clientbibliotheken finden Sie unter So verwenden Tools und APIs fortsetzbare Uploads.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen eine der folgenden Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie für einen fortsetzbaren Upload benötigen:

  • Bitten Sie bei Uploads mit einer Objektaufbewahrungssperre Ihren Administrator, Ihnen die IAM-Rolle Storage-Objekt-Administrator (roles/storage.objectAdmin) für den Bucket zuzuweisen.

  • In allen anderen Fällen bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Storage-Objekt-Nutzer (roles/storage.objectUser) für den Bucket zuzuweisen.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Hochladen eines Objekts in einen Bucket für den jeweiligen Fall erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

  • storage.objects.create
  • storage.objects.delete
    • Diese Berechtigung ist nur für Uploads erforderlich, die ein vorhandenes Objekt überschreiben.
  • storage.objects.setRetention
    • Diese Berechtigung ist nur für Uploads erforderlich, die eine Objektaufbewahrungssperre enthalten.

Sie können diese Berechtigungen auch mit anderen vordefinierten Rollen oder benutzerdefinierten Rollen erhalten.

Informationen zum Zuweisen von Rollen für Buckets finden Sie unter IAM mit Buckets verwenden.

Fortsetzbare Uploadsitzung starten

So starten Sie eine fortsetzbare Uploadsitzung:

JSON API

  1. Installieren und initialisieren Sie die dcloud CLI, um ein Zugriffstoken für den Header Authorization zu generieren.

    Alternativ können Sie mit dem OAuth 2.0 Playground ein Zugriffstoken erstellen und in den Header Authorization einfügen.

  2. Erstellen Sie optional eine JSON-Datei, die die Metadaten für das Objekt enthält, das Sie hochladen möchten. Beispiel: Die folgende JSON-Datei legt die contentType-Metadaten des Objekts fest, das Sie in image/png hochladen möchten:

    {
    "contentType": "image/png"
}

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

    curl -i -X POST --data-binary @METADATA_LOCATION \
    -H "Authorization: Bearer $(gcloud auth print-access-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"

    Dabei 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.
    • INITIAL_REQUEST_LENGTH ist die Anzahl der Byte im Text dieser ersten Anfrage, z. B. 79.
    • BUCKET_NAME ist der Name des Buckets, in den Sie das Objekt hochladen. Beispiel: my-bucket.
    • OBJECT_NAME ist der URL-codierte Name, den Sie dem Objekt geben möchten. Beispiel: pets/dog.png, URL-codiert als pets%2Fdog.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. Die gcloud CLI installieren und initialisieren, um ein Zugriffstoken für den Header Authorization zu generieren.

    Alternativ können Sie mit dem OAuth 2.0 Playground ein Zugriffstoken erstellen und in den Header Authorization einfügen.

  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 $(gcloud auth print-access-token)" \
    -H "Content-Length: 0" \
    -H "Content-Type: OBJECT_CONTENT_TYPE" \
    -H "x-goog-resumable: start" \
    "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    Dabei gilt:

    • 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 URL-codierte Name, den Sie dem Objekt geben möchten. Beispiel: pets/dog.png, URL-codiert als pets%2Fdog.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.

Daten hochladen

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

  • In einem Block: 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.

Einzelnen Block hochladen

So laden Sie die Datei in einem einzelnen Block 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"

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

    Optional können Sie Header mit dem Präfix X-Goog-Meta- einfügen, um benutzerdefinierte Metadaten für das Objekt als Teil dieser Anfrage hinzuzufügen.

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"

    Dabei 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 Daten in mehreren Blöcken hoch:

JSON API

  1. Erstellen Sie einen Datenblock aus den Gesamtdaten, 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 Block des Uploads. Durch größere Blöcke werden Uploads in der Regel schneller. Beachten Sie jedoch, dass zwischen Geschwindigkeit und Speichernutzung ein Kompromiss besteht. Es wird empfohlen, als Blockgröße mindestens 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"

    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: 8388608
    • 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-8388607/20000000. 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.

  3. Wiederholen Sie die oben genannten Schritte für jeden verbleibenden Datenblock, den Sie hochladen möchten. Verwenden Sie dazu den höchsten Wert, der im Range-Header jeder Antwort enthalten ist, um zu bestimmen, wo der jeweils folgende Block beginnt. Sie sollten nicht davon ausgehen, dass der Server alle Byte erhalten hat, die in einer bestimmten Anfrage gesendet wurden.

    Optional können Sie in der letzten Anfrage des fortsetzbaren Uploads Header mit dem Präfix X-Goog-Meta- einfügen, um benutzerdefinierte Metadaten für das Objekt hinzuzufügen.

XML API

  1. Erstellen Sie einen Datenblock aus den Gesamtdaten, 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 Block des Uploads. Durch größere Blöcke werden Uploads in der Regel schneller. Beachten Sie jedoch, dass zwischen Geschwindigkeit und Speichernutzung ein Kompromiss besteht. Es wird empfohlen, als Blockgröße mindestens 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: 8388608
    • 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-8388607/20000000. 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.

  3. Wiederholen Sie die oben genannten Schritte für jeden verbleibenden Datenblock, den Sie hochladen möchten. Verwenden Sie dazu den höchsten Wert, der im Range-Header jeder Antwort enthalten ist, um zu bestimmen, wo der jeweils folgende Block beginnt. Sie sollten nicht davon ausgehen, dass der Server alle Byte erhalten hat, die in einer bestimmten Anfrage gesendet wurden.

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 eine 5xx-Antwort erhalten, sollten Sie entweder den unterbrochenen Block noch einmal komplett senden oder den unterbrochenen Upload an der Stelle fortsetzen, an der er unterbrochen wurde.

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 JSON API mit einer PUT-Objektanfrage aufzurufen:

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

    Dabei gilt:

    • OBJECT_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"

    Dabei gilt:

    • OBJECT_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 Daten fortsetzen müssen.

  • Wenn Cloud Storage noch keine Byte gespeichert 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 gespeichert 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 gespeichert 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. Wenn die unterbrochene Anfrage Header mit dem Präfix X-Goog-Meta- enthielt, fügen Sie diese Header in die Anfrage ein, um den Upload fortzusetzen.

  5. 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"

    Dabei 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 19999957.
    • 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 19999999 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 gespeichert 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"

    Dabei 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 19999957.
    • 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 19999999 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, während der Sitzungs-URI aktiv ist. Der Sitzungs-URI läuft nach einer Woche ab. Wenn die Daten erfolgreich hochgeladen wurden, antwortet Cloud Storage mit dem Statuscode 200 OK oder 201 created.

Upload abbrechen

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

JSON API

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

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

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

XML API

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

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

    Dabei gilt:

Wenn die Anfrage erfolgreich ist, enthält die Antwort einen Statuscode 204 und zukünftige Versuche, den Upload abzufragen oder fortzusetzen, führen ebenfalls zu einer 204-Antwort.

Nächste Schritte