Fortsetzbare Uploads

Einrichtung

Auf dieser Seite werden fortsetzbare Uploads in Cloud Storage erläutert. Fortsetzbare Uploads sind die empfohlene Methode zum Hochladen großer Dateien, da Sie sie nicht von Anfang an neu starten müssen, wenn während des Uploads ein Netzwerkfehler auftritt.

Einführung

Mit einem fortsetzbaren Upload können Sie den Datenübertragungsvorgang zu Cloud Storage fortsetzen, nachdem ein Kommunikationsfehler den Datenfluss unterbrochen hat. Fortsetzbare Uploads funktionieren durch Senden mehrerer Anfragen, von denen jede einen Teil des hochgeladenen Objekts enthält. Dies unterscheidet sich von einem Einzelanfrage-Upload, der alle Daten des Objekts in einer einzigen Anfrage enthält und von Anfang an neu gestartet werden muss, wenn beim Upload ein Fehler auftritt.

  • Verwenden Sie einen fortsetzbaren Upload, wenn Sie große Dateien hochladen oder über eine langsame Verbindung hochladen. Beispiel: Grenzwerte für die Dateigröße für die Verwendung fortsetzbarer Uploads finden Sie unter Überlegungen zur Uploadgröße.

  • Fortsetzbare Uploads müssen innerhalb einer Woche nach der Initiierung abgeschlossen werden, können aber jederzeit abgebrochen werden.

  • Es wird nur ein abgeschlossener fortsetzbarer Upload in Ihrem Bucket angezeigt und ersetzt ggf. ein vorhandenes Objekt mit demselben Namen.

Wie Tools und APIs fortsetzbare Uploads verwenden

Abhängig davon, wie Sie mit Cloud Storage interagieren, werden fortsetzbare Uploads möglicherweise automatisch in Ihrem Namen verwaltet. In diesem Abschnitt wird das Verhalten von fortsetzbaren Uploads für verschiedene Tools beschrieben und Sie erhalten Hinweise zum Konfigurieren der entsprechenden Puffergröße für Ihre Anwendung.

Console

Die Google Cloud Console verwaltet fortsetzbare Uploads automatisch in Ihrem Namen. Wenn Sie jedoch während eines Uploads eine Aktualisierung ausführen oder die Google Cloud Console verlassen, wird der Upload abgebrochen.

Befehlszeile

Die gcloud CLI verwendet beim Hochladen von Daten in Cloud Storage fortsetzbare Uploads in den Befehlen gcloud storage cp und gcloud storage rsync. Wenn der Upload unterbrochen wird, können Sie ihn mit demselben Befehl fortsetzen, den Sie zum Starten des Uploads verwendet haben. Verwenden Sie beim Fortsetzen eines Uploads, der mehrere Dateien enthält, das Flag --no-clobber, um einen erneuten Upload von Dateien zu verhindern, die bereits erfolgreich hochgeladen wurden.

Clientbibliotheken

C++

Funktionen in storage::Client haben ein anderes Verhalten:

Standardmäßig führt UploadFile() einen fortsetzbaren Upload aus, wenn das Objekt größer als 20 MiB ist. Andernfalls wird ein einfacher Upload oder ein mehrteiliger Upload durchgeführt. Sie können diesen Grenzwert konfigurieren. Dazu legen Sie MaximumSimpleUploadsSizeOption fest, wenn Sie storage::Client erstellen.

8 MiB ist die Standardpuffergröße, die Sie mit der Option UploadBufferSizeOption ändern können.

Die C++-Clientbibliothek verwendet eine Puffergröße, die der Blockgröße entspricht. Die Puffergröße muss ein Vielfaches von 256 KiB (256 x 1024 Byte) sein. Wenn Sie WriteObject() und UploadFile() verwenden, sollten Sie die Kompromisse zwischen der Uploadgeschwindigkeit und der Speichernutzung berücksichtigen. Der Einsatz kleiner Zwischenspeicher zum Hochladen großer Objekte kann den Upload verlangsamen. Weitere Informationen zur Beziehung zwischen Uploadgeschwindigkeit und Zwischenspeichergröße für C++ finden Sie in der detaillierten Analyse in GitHub.

C#

Beim Hochladen führt die C#-Clientbibliothek immer fortsetzbare Uploads aus. Sie können einen fortsetzbaren Upload mit CreateObjectUploader initiieren.

Die C++-Clientbibliothek verwendet eine Puffergröße, die der Blockgröße entspricht. Die Standardpuffergröße beträgt 10 MB. Sie können diesen Wert ändern. Legen Sie dazu ChunkSize auf UploadObjectOptions fest. Die Puffergröße muss ein Vielfaches von 256 KiB (256 x 1024 Byte) sein. Größere Puffergrößen beschleunigen Uploads in der Regel. Beachten Sie jedoch, dass zwischen Geschwindigkeit und Speichernutzung ein Kompromiss besteht.

Go

Standardmäßig werden fortsetzbare Uploads automatisch durchgeführt, wenn die Datei größer als 16 MiB ist. Sie ändern das Zeitlimit für fortsetzbare Uploads mit Writer.ChunkSize. Fortsetzbare Uploads werden bei Verwendung der Go-Clientbibliothek immer in Blöcke unterteilt.

Mehrteilige Uploads treten auf, wenn das Objekt kleiner als Writer.ChunkSize ist oder wenn Writer.ChunkSize auf 0 gesetzt ist, wobei die Aufteilung deaktiviert wird. Writer kann Anfragen nicht wiederholen, wenn ChunkSize auf 0 gesetzt ist.

Die Go-Clientbibliothek verwendet eine Puffergröße, die der Blockgröße entspricht. Die Puffergröße muss ein Vielfaches von 256 KiB (256 x 1024 Byte) sein. Größere Puffergrößen beschleunigen Uploads in der Regel. Beachten Sie jedoch, dass zwischen Geschwindigkeit und Speichernutzung ein Kompromiss besteht. Wenn Sie mehrere fortsetzbare Uploads gleichzeitig ausführen, sollten Sie für Writer.ChunkSize einen Wert festlegen, der kleiner als 16 MiB ist. So vermeiden Sie Speicher-Bloat.

Beachten Sie, dass das Objekt erst in Cloud Storage fertiggestellt ist, wenn Sie Writer.Close() aufrufen und eine Erfolgsantwort erhalten. Writer.Close gibt einen Fehler zurück, wenn die Anfrage nicht erfolgreich war.

Java

Die Java-Clientbibliothek hat separate Methoden für mehrteilige und fortsetzbare Uploads. Die folgenden Methoden führen immer einen fortsetzbaren Upload aus:

Die Standardpuffergröße beträgt 15 MiB. Sie können die Puffergröße entweder mit der Methode WriteChannel#setChunkSize(int) oder durch Übergabe einesbufferSize-Parameters an die Methode Storage#createFrom festlegen. Die Puffergröße hat ein festes Minimum von 256 KiB. Beim internen Aufruf von WriteChannel#setChunkSize(int) wird die Puffergröße auf ein Vielfaches von 256 KiB verschoben.

Ein Puffer für fortsetzbare Uploads dient als minimaler Grenzwert zum Leeren. Schreibvorgänge, die kleiner als die Puffergröße sind, werden zwischengespeichert, bis ein Schreibvorgang die Anzahl der zwischengespeicherten Byte über die Puffergröße hinaus überträgt.

Wenn Sie kleinere Datenmengen hochladen, sollten Sie Storage#create(BlobInfo, byte[], Storage.BlobTargetOption...) oder Storage#create(BlobInfo, byte[], int, int, Storage.BlobTargetOption...) verwenden.

Node.js

Fortsetzbare Uploads werden automatisch durchgeführt. Sie können fortsetzbare Uploads deaktivieren, wenn Sie resumable auf UploadOptions auf false setzen. Wenn Sie die Methode createWriteStream verwenden, werden fortsetzbare Uploads automatisch verwaltet.

Es gibt keine Standardpuffergröße und aufgeteilte Uploads müssen manuell aufgerufen werden. Dazu legen Sie die Option chunkSize auf CreateResumableUploadOptions fest. Wenn chunkSize angegeben ist, werden die Daten in separaten HTTP-Anfragen mit jeweils einer Nutzlast der Größe chunkSize gesendet. Wenn keine chunkSize angegeben ist und die Bibliothek einen fortsetzbaren Upload durchführt, werden alle Daten in einer einzigen HTTP-Anfrage gestreamt.

Die Node.js-Clientbibliothek verwendet eine Puffergröße, die der Blockgröße entspricht. Die Puffergröße muss ein Vielfaches von 256 KiB (256 x 1024 Byte) sein. Größere Zwischenspeicher machen Uploads in der Regel schneller. Beachten Sie jedoch, dass zwischen Geschwindigkeit und Speichernutzung ein Kompromiss besteht.

PHP

Standardmäßig werden fortsetzbare Uploads automatisch durchgeführt, wenn die Objektgröße größer als 5 MB ist. Andernfalls erfolgen mehrteilige Uploads. Dieser Schwellenwert kann nicht geändert werden. Sie können einen fortsetzbaren Upload erzwingen, wenn Sie in der Funktion upload die Option resumable festlegen.

Die PHP-Clientbibliothek verwendet eine Puffergröße, die der Blockgröße entspricht. 256 KiB ist die Standardpuffergröße für einen fortsetzbaren Upload. Sie können die Puffergröße ändern, indem Sie das Attribut chunkSize festlegen. Die Puffergröße muss ein Vielfaches von 256 KiB (256 x 1024 Byte) sein. Größere Puffergrößen beschleunigen Uploads in der Regel. Beachten Sie jedoch, dass zwischen Geschwindigkeit und Speichernutzung ein Kompromiss besteht.

Python

Fortsetzbare Uploads treten auf, wenn das Objekt größer als 8 MiB ist. Mehrteilige Uploads treten auf, wenn das Objekt kleiner als 8 MiB ist. Dieser Grenzwert kann nicht geändert werden. Die Python-Clientbibliothek verwendet eine Puffergröße, die der Blockgröße entspricht. 100 MiB ist die Standardpuffergröße für einen fortsetzbaren Upload. Sie können die Puffergröße ändern, indem Sie das Attribut blob.chunk_size festlegen.

Verwenden Sie die Klasse storage.BlobWriter oder die Methode storage.Blob.open(mode='w'), um unabhängig von der Objektgröße immer einen fortsetzbaren Upload durchzuführen. Bei diesen Methoden beträgt die Standardpuffergröße 40 MiB. Sie können auch Fortsetzbare Medien verwenden, um fortsetzbare Uploads zu verwalten.

Die Blockgröße muss ein Vielfaches von 256 KiB (256 x 1.024 Byte) sein. Größere Chunk-Größen machen Uploads in der Regel schneller. Beachten Sie jedoch, dass zwischen Geschwindigkeit und Speichernutzung ein Kompromiss besteht.

Ruby

Die Ruby-Clientbibliothek behandelt alle Uploads als nicht aufgeteilte fortsetzbare Uploads.

REST APIs

JSON API

Die Cloud Storage JSON API verwendet eine POST Object-Anfrage, die den Abfrageparameter uploadType=resumable enthält, um den fortsetzbaren Upload zu starten. Für diese Anfrage wird ein Sitzungs-URI zurückgegeben, den Sie dann in einer oder mehreren PUT Object-Anfragen zum Hochladen der Objektdaten verwenden. Eine detaillierte Anleitung zum Erstellen einer eigenen Logik für fortsetzbare Uploads finden Sie unter Fortsetzbare Uploads durchführen.

XML API

Die Cloud Storage XML API verwendet eine POST Object-Anfrage, die den Header x-goog-resumable: start enthält, um den fortsetzbaren Upload zu starten. Für diese Anfrage wird ein Sitzungs-URI zurückgegeben, den Sie dann in einer oder mehreren PUT Object-Anfragen zum Hochladen der Objektdaten verwenden. Eine detaillierte Anleitung zum Erstellen einer eigenen Logik für fortsetzbare Uploads finden Sie unter Fortsetzbare Uploads durchführen.

Fortsetzbare Uploads unbekannter Größe

Der Mechanismus für fortsetzbare Uploads unterstützt Übertragungen, bei denen die Dateigröße nicht im Voraus bekannt ist. Dies ist insbesondere dann hilfreich, wenn ein Objekt beispielsweise sofort beim Hochladen komprimiert wird. In diesem Fall ist es nämlich schwierig, die genaue Dateigröße für die komprimierte Datei zu Beginn einer Übertragung vorherzusagen. Verwenden Sie diesen Mechanismus, wenn Sie eine Übertragung streamen möchten, die nach einer Unterbrechung fortgesetzt werden kann, oder wenn die aufgeteilte Transferverschlüsselung für Ihre Anwendung nicht funktioniert.

Weitere Informationen finden Sie unter Streaming-Uploads.

Uploadleistung

Sitzungsregionen auswählen

Fortsetzbare Uploads sind an die Region gebunden, in der Sie diese starten. Wenn Sie beispielsweise in den USA einen fortsetzbaren Upload initiieren und den Sitzungs-URI an einen Client in Asien übergeben, wird der Upload trotzdem durch die USA geleitet. Zur Reduzierung des regionenübergreifenden Traffics und zur Verbesserung der Leistung sollten Sie eine Sitzung für den fortsetzbaren Upload in der Region beibehalten, in der er erstellt wurde.

Wenn Sie eine Compute Engine-Instanz verwenden, um einen fortsetzbaren Upload zu starten, sollte sich die Instanz am selben Speicherort wie der Cloud Storage-Bucket befinden, in den Sie Daten hochladen. Sie können dann einen Geo-IP-Dienst nutzen, um die Compute Engine-Region zu übernehmen, an die Sie die Kundenanfragen weiterleiten. Auf diese Weise bleibt der Traffic innerhalb der Region.

Daten in Blöcken hochladen

Teilen Sie Übertragungen möglichst nicht in Blöcke auf, sondern laden Sie den gesamten Inhalt auf einmal hoch. Dadurch verbessern Sie den Durchsatz und vermeiden zusätzliche Latenzkosten und Vorgangsgebühren, die beim Abfragen des persistenten Offsets für jeden Block entstehen. In den folgenden Fällen empfiehlt es sich jedoch, Inhalte in Blöcke hochzuladen:

  • Wenn Ihre Quelldaten dynamisch generiert werden und Sie einschränken möchten, wie viel davon clientseitig gepuffert werden soll, wenn der Upload fehlschlägt.

  • Wenn Ihre Clients Größenbeschränkungen für Anfragen haben, wie es bei vielen Browsern der Fall ist.

Wenn Sie die JSON oder XML API verwenden und Ihr Client einen Fehler erhält, kann er den Server nach dem persistenten Offset abfragen und die verbleibenden Byte aus diesem Offset fortsetzen. Die Google Cloud Console, die Google Cloud CLI und die Clientbibliotheken verarbeiten dies automatisch für Sie. Weitere Informationen zum Aufteilen nach bestimmten Clientbibliotheken finden Sie unter Wie Tools und APIs fortsetzbare Uploads verwenden.

Hinweise

Dieser Abschnitt ist hilfreich, wenn Sie einen eigenen Client erstellen, der Anfragen für fortsetzbare Uploads direkt an die JSON API oder die XML API sendet.

Sitzungs-URIs

Wenn Sie einen fortsetzbaren Upload starten, gibt Cloud Storage einen Sitzungs-URI zurück, den Sie in nachfolgenden Anfragen verwenden, um die tatsächlichen Daten hochzuladen. Dies ist ein Beispiel für einen Sitzungs-URI in der JSON API:

https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=resumable&name=my-file.jpg&upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

Dies ist ein Beispiel für einen Sitzungs-URI in der XML API:

 https://storage.googleapis.com/my-bucket/my-file.jpg?upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

Dieser Sitzungs-URI fungiert als Authentifizierungstoken. Daher müssen die Anfragen, in denen er verwendet wird, nicht signiert werden und jeder kann sie ohne weitere Authentifizierung verwenden, um Daten in den Ziel-Bucket hochzuladen. Teilen Sie den Sitzungs-URI daher mit Bedacht und nur über HTTPS.

Ein Sitzungs-URI läuft nach einer Woche ab, kann aber vor dem Ablauf abgebrochen werden. Wenn Sie eine Anfrage mit einem Sitzungs-URI stellen, der nicht mehr gültig ist, wird einer der folgenden Fehler angezeigt:

  • Der Statuscode 410 Gone, wenn seit dem Start des Uploads weniger als eine Woche vergangen ist.
  • Der Statuscode 404 Not Found, wenn der Upload mehr als eine Woche zurückliegt.

In beiden Fällen müssen Sie einen neuen fortsetzbaren Upload auslösen, einen neuen Sitzungs-URI abrufen und den Upload unter Verwendung des neuen Sitzungs-URIs von vorn beginnen.

Integritätsprüfungen

Es ist empfehlenswert, eine Integritätsprüfung des endgültig hochgeladenen Objekts anzufordern, um zu prüfen, ob dieses mit der Quelldatei übereinstimmt. Dazu berechnen Sie den MD5-Digest-Wert der Quelldatei und fügen ihn dem Anfrageheader Content-MD5 hinzu.

Die Integritätsprüfung der hochgeladenen Datei ist besonders dann wichtig, wenn Sie eine große Datei über einen längeren Zeitraum hochladen, da hier die Wahrscheinlichkeit größer ist, dass die Quelldatei während des Uploads geändert wurde.

Beim Starten eines fortsetzbaren Uploads wird der Wert x-goog-content-sha256 ignoriert. Daher wird empfohlen, x-goog-content-sha256 auf UNSIGNED-PAYLOAD zu setzen.

Daten wiederholen und noch einmal senden

Sobald Cloud Storage Byte in einem fortsetzbaren Upload beibehält, können diese Byte nicht mehr überschrieben werden. Cloud Storage ignoriert Versuche, dies zu tun. Aus diesem Grund sollten Sie keine andere Daten senden, wenn Sie zu einem Offset zurückspulen.

Beispiel: Sie laden ein 100.000-Byte-Objekt hoch und Ihre Verbindung wird unterbrochen. Beim Prüfen des Status stellen Sie fest, dass 50.000 Byte erfolgreich hochgeladen und beibehalten wurden. Wenn Sie versuchen, den Upload mit 40.000 Byte neu zu starten, ignoriert Cloud Storage die Byte, die Sie von 40.000 bis 50.000 senden. Cloud Storage beginnt mit der Speicherung der gesendeten Daten ab Byte 50.001.

Nächste Schritte