Parallele zusammengesetzte Uploads

Mit parallelen zusammengesetzten Uploads können Sie große Dateien erheblich schneller hochladen, wenn Netzwerk- und Laufwerksgeschwindigkeit keine einschränkenden Faktoren darstellen. Bei einem parallelen zusammengesetzten Upload wird eine Datei in bis zu 32 Teile aufgeteilt. Die Teile werden parallel in temporäre Objekte hochgeladen, das endgültige Objekt wird mithilfe der temporären Objekte neu erstellt und die temporären Objekte werden gelöscht.

Wenn Sie über die XML API mit Cloud Storage interagieren, sollten Sie stattdessen mehrteilige XML API-Uploads verwenden. Mehrteilige XML API-Uploads unterstützen eine größere Anzahl von Teilen als Zusammensetzungsvorgänge, haben ein geringeres Potenzial für Gebühren für vorzeitiges Löschen und erfordern keine Delete-Anfragen zum Entfernen der Quellteile, sobald das endgültige Objekt zusammengesetzt ist.

Hinweise

Das letzte Objekt, das ein paralleler zusammengesetzter Upload in Ihrem Bucket speichert, ist ein zusammengesetztes Objekt, das nur einen crc32c-Hash und keinen MD5-Hash hat. Daher müssen Sie crcmod verwenden, um Integritätsprüfungen durchzuführen, wenn Sie das Objekt mit Python-Anwendungen herunterladen. Sie sollten parallele zusammengesetzte Uploads nur ausführen, wenn Folgendes zutrifft:

  • Die hochgeladenen Objekte müssen keinen MD5-Hash haben.

  • Jeder Python-Nutzer, einschließlich gsutil-Nutzer, der Ihre Objekte herunterladen muss, hat entweder google-crc32c oder crcmod installiert.

    Wenn Sie beispielsweise Python verwenden, um Video-Assets hochzuladen, die nur von einer Java-Anwendung bereitgestellt werden, sind parallele zusammengesetzte Uploads eine gute Wahl, da in Java effiziente CRC32C-Implementierungen verfügbar sind.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Storage-Objekt-Nutzer (roles/storage.objectUser) für den Bucket zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen paralleler zusammengesetzter Uploads benötigen.

Die Rolle „Storage-Administrator“ (roles/storage.admin) enthält die Berechtigungen, die zum Hochladen, Lesen und Löschen von Objektblöcken erforderlich sind. Sie enthält auch die erforderliche Berechtigung für die gcloud CLI, um eine Kompatibilitätsprüfung auf Bucket-Ebene mit parallelen zusammengesetzten Uploads durchzuführen. Wenn Sie die Rolle „Storage-Administrator“ (roles/storage.admin) nicht erhalten können, können Sie dennoch parallele zusammengesetzte Uploads mit der gcloud CLI ausführen. Dazu müssen Sie die Rolle „Storage-Objekt-Nutzer“ (roles/storage.objectUser) erhalten und das Attribut storage/parallel_composite_upload_compatibility_check deaktivieren. Weitere Informationen finden Sie im Tab Befehlszeile im Abschnitt So verwenden Tools und APIs parallele zusammengesetzte Uploads.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Eine Anleitung zum Zuweisen von Rollen für Buckets finden Sie unter IAM-Richtlinien für Buckets festlegen und verwalten.

So verwenden Tools und APIs parallele zusammengesetzte Uploads

Abhängig davon, wie Sie mit Cloud Storage interagieren, werden parallele zusammengesetzte Uploads möglicherweise automatisch in Ihrem Namen verwaltet. In diesem Abschnitt wird das Verhalten paralleler zusammengesetzter Uploads für verschiedene Tools beschrieben und Sie erfahren, wie Sie das Verhalten ändern können.

Console

Die Google Cloud Console führt keine parallelen zusammengesetzten Uploads durch.

Befehlszeile

Die folgenden Attribute bestimmen, wie und wann die gcloud CLI parallele zusammengesetzte Uploads ausführt:

  • storage/parallel_composite_upload_enabled: Attribut zum Aktivieren paralleler zusammengesetzter Uploads. Wird False festgelegt, werden parallele zusammengesetzte Uploads deaktiviert und Kompatibilitätsprüfungen auf Bucket-Ebene übersprungen. Mit True oder None werden parallele zusammengesetzte Uploads für Objekte aktiviert, die die in den anderen Attributen definierten Kriterien erfüllen, und Kompatibilitätsprüfungen werden aktiviert. Die Standardeinstellung ist None.

  • storage/parallel_composite_upload_compatibility_check: Attribut zum Aktivieren/Deaktivieren von Prüfungen auf Bucket-Ebene auf Kompatibilität und Sicherheit mit parallelen zusammengesetzten Uploads. Wenn True, sendet die gcloud CLI eine GET-Anfrage für die Metadaten des Ziel-Buckets, bevor sie einen parallelen zusammengesetzten Upload versucht. Dazu benötigt das Hauptkonto die Berechtigung storage.buckets.get. Die gcloud CLI führt parallele zusammengesetzte Uploads nur aus, wenn alle folgenden Bedingungen erfüllt sind:

    Die Standardeinstellung ist True. Wenn False, führt die gcloud CLI die Kompatibilitätsprüfung nicht durch.

    Wenn Sie storage/parallel_composite_upload_compatibility_check auf False setzen, werden parallele zusammengesetzte Uploads nicht deaktiviert. Wenn storage/parallel_composite_upload_compatibility_check auf False und storage/parallel_composite_upload_enabled auf None oder True gesetzt ist, überspringt die gcloud CLI die Bucket-Prüfung und fährt direkt mit einem parallelen zusammengesetzten Upload fort.

    Wenn Sie diese Prüfung überspringen möchten, deaktivieren Sie das Attribut storage/parallel_composite_upload_compatibility_check:

    gcloud config set storage/parallel_composite_upload_compatibility_check False

  • storage/parallel_composite_upload_threshold: Die minimale Gesamtgröße der Datei für einen parallelen zusammengesetzten Upload. Die Standardeinstellung ist 150 MiB.

  • storage/parallel_composite_upload_component_size: Die maximale Größe für jedes temporäre Objekt. Das Attribut wird ignoriert, wenn die Datei insgesamt so groß ist, dass mehr als 32 Blöcke dieser Größe erforderlich wären.

  • storage/parallel_composite_upload_component_prefix: Das Präfix, das beim Benennen temporärer Objekte verwendet wird. Dieses Attribut kann entweder als absoluter Pfad oder als Pfad relativ zum endgültigen Objekt festgelegt werden. Weitere Informationen findest du in der Beschreibung der Property. Das Standardpräfix ist der absolute Pfad /gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details.

Um diese Attribute zu ändern, erstellen Sie eine benannte Konfiguration und wenden diese entweder mit dem projektweiten Flag --configuration pro Befehl oder für alle gcloud CLI-Befehle mit dem gcloud config set-Befehl an.

Wenn Sie mit gcloud CLI parallele zusammengesetzte Uploads ausführen möchten, benötigen Sie keinen zusätzlichen lokalen Speicherplatz. Wenn ein paralleler zusammengesetzter Upload vor der Zusammensetzung fehlschlägt, führen Sie den gcloud CLI-Befehl noch einmal aus, um die fortsetzbaren Uploads für die temporären Objekte zu nutzen, die fehlgeschlagen sind. Alle temporären Objekte, die vor dem Fehler erfolgreich hochgeladen wurden, werden beim Fortsetzen des Uploads nicht noch einmal hochgeladen.

Temporäre Objekte werden so benannt:

TEMPORARY_PREFIX/RANDOM_VALUE_HEX_DIGEST_COMPONENT_ID

Dabei gilt:

  • TEMPORARY_PREFIX wird über das Attribut storage/parallel_composite_upload_component_prefix gesteuert.
  • RANDOM_VALUE ist ein zufälliger numerischer Wert.
  • HEX_DIGEST ist ein Hash, der vom Namen der Quellressource abgeleitet wird.
  • COMPONENT_ID ist die fortlaufende Nummer der Komponente.

Im Allgemeinen werden temporäre Objekte am Ende eines parallelen zusammengesetzten Uploads gelöscht. Damit keine doppelten temporären Objekte zurückbleiben, sollten Sie über den gcloud CLI-Befehl den Exit-Status prüfen und alle temporären Objekte, die Teil eines abgebrochenen Uploads waren, manuell löschen.

Clientbibliotheken

Java

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Java API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Sie können parallele zusammengesetzte Uploads ausführen. Setzen Sie dazu AllowParallelCompositeUpload auf true. Beispiele:

import com.google.cloud.storage.transfermanager.ParallelUploadConfig;
import com.google.cloud.storage.transfermanager.TransferManager;
import com.google.cloud.storage.transfermanager.TransferManagerConfig;
import com.google.cloud.storage.transfermanager.UploadResult;
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;

class AllowParallelCompositeUpload {

  public static void parallelCompositeUploadAllowed(String bucketName, List<Path> files)
      throws IOException {
    TransferManager transferManager =
        TransferManagerConfig.newBuilder()
            .setAllowParallelCompositeUpload(true)
            .build()
            .getService();
    ParallelUploadConfig parallelUploadConfig =
        ParallelUploadConfig.newBuilder().setBucketName(bucketName).build();
    List<UploadResult> results =
        transferManager.uploadFiles(files, parallelUploadConfig).getUploadResults();
    for (UploadResult result : results) {
      System.out.println(
          "Upload for "
              + result.getInput().getName()
              + " completed with status "
              + result.getStatus());
    }
  }
}

Node.js

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Node.js API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Die Node.js-Clientbibliothek unterstützt keine parallelen zusammengesetzten Uploads. Verwenden Sie stattdessen mehrteilige XML API-Uploads.

Python

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Python API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Die Python-Clientbibliothek unterstützt keine parallelen zusammengesetzten Uploads. Verwenden Sie stattdessen mehrteilige XML API-Uploads.

REST APIs

JSON API

Die JSON API unterstützt das parallele Hochladen von Objektblöcken und das Zusammenführen in einem einzelnen Objekt mit dem compose-Vorgang.

Beachten Sie beim Entwickeln von Code für parallele zusammengesetzte Uploads Folgendes:

  • Wenn Sie den compose-Vorgang verwenden, können Sie die Quellobjekte im Rahmen des Zusammensetzungsprozesses endgültig löschen. Verwenden Sie diese Option, um die Abrechnung für temporäre Objekte zu minimieren, die nicht durch vorläufiges Löschen oder Objektversionsverwaltung geschützt werden müssen.

  • Um zu verhindern, dass Quellobjekte in der Zeit zwischen dem Hochladen und der Anfrage zur Zusammensetzung geändert werden, sollten allen Quellobjekten plausible Generierungsnummern‌ zugewiesen werden.

XML API

Die XML API unterstützt das parallele Hochladen von Objektblöcken und das Zusammenführen in einem einzelnen Objekt mit dem compose-Vorgang.

Beachten Sie beim Entwickeln von Code für parallele zusammengesetzte Uploads Folgendes:

  • Wenn Sie den compose-Vorgang verwenden, sind die Quellobjekte vom Zusammensetzungsprozess nicht betroffen.

    Wenn sie also temporär sein sollen, müssen Sie sie explizit löschen, nachdem die Zusammensetzung erfolgreich abgeschlossen wurde. Andernfalls verbleiben die Quellobjekte in Ihrem Bucket und werden entsprechend in Rechnung gestellt.

  • Um zu verhindern, dass Quellobjekte in der Zeit zwischen dem Hochladen und der Anfrage zur Zusammensetzung geändert werden, sollten allen Quellobjekten plausible Generierungsnummern‌ zugewiesen werden.

Fehlerbehebung

Dieser Abschnitt enthält Informationen zur Fehlerbehebung bei gcloud CLI-Fehlern, die bei parallelen zusammengesetzten Uploads auftreten können.

Es kann nicht geprüft werden, ob der Ziel-Bucket mit parallelen zusammengesetzten Uploads kompatibel ist

Problem: Wenn Sie eine Datei mit einer Größe von 150 MiB oder mehr mit gcloud storage cp oder gcloud storage mv hochladen, wird die folgende Meldung einmal im Befehl protokolliert, der Upload wird jedoch mit dem Exit-Code 0 erfolgreich abgeschlossen:

ERROR: Cannot check if the destination bucket is compatible for running
parallel composite uploads as the user does not permission to perform GET
operation on the bucket. The operation will be performed without parallel
composite upload feature and hence might perform relatively slower.

Lösung: Die gcloud CLI versucht, die Kompatibilitätsprüfung für parallele zusammengesetzte Uploads auszuführen. Das Hauptkonto hat nicht die Berechtigung storage.buckets.get für den Ziel-Bucket. Daher wird die Anfrage für die Metadaten des Buckets abgelehnt. Die gcloud CLI verarbeitet den Fehler intern und zeigt keinen HTTP-Statuscode an. Stattdessen wird die Nachricht protokolliert und ein regulärer Upload durchgeführt.

Wenn Sie parallele zusammengesetzte Uploads verwenden möchten, muss das Hauptkonto die Berechtigungen storage.buckets.get, storage.objects.get und storage.objects.delete für den Ziel-Bucket haben. Diese Berechtigungen können über die Rolle „Storage-Administrator“ (roles/storage.admin) gewährt werden. Wenn das Hauptkonto bereits die Berechtigungen storage.objects.get und storage.objects.delete über eine Rolle wie Storage-Objekt-Nutzer (roles/storage.objectUser) hat, kann es alternativ das Attribut storage/parallel_composite_upload_compatibility_check auf False setzen, um die Kompatibilitätsprüfung zu deaktivieren.

403: does not have storage.objects.get access

Problem: Uploads von Dateien, die kleiner als 150 MiB sind, sind erfolgreich, aber Uploads von Dateien, die 150 MiB oder größer sind, schlagen mit dem Exit-Code 1 und einem Fehler wie dem folgenden fehl:

HTTPError 403: PRINCIPAL does not have storage.objects.get access to
the Google Cloud Storage object.

Lösung: storage/parallel_composite_upload_compatibility_check ist auf False und storage/parallel_composite_upload_enabled entweder auf None oder True gesetzt. In dieser Konfiguration überspringt die gcloud CLI die Bucket-Kompatibilitätsprüfung und fährt direkt mit einem parallelen zusammengesetzten Upload fort.

Die temporären Objekte werden erfolgreich hochgeladen, da das Hauptkonto die Berechtigung storage.objects.create hat. Zum Zusammenfügen der temporären Objekte zum endgültigen Objekt ist jedoch die Berechtigung storage.objects.get erforderlich und zum anschließenden Löschen der temporären Objekte die Berechtigung storage.objects.delete.

Wählen Sie eine der folgenden Optionen aus, um dieses Problem zu beheben:

  • Wenn Sie keine parallelen zusammengesetzten Uploads benötigen, deaktivieren Sie sie:

    gcloud config set storage/parallel_composite_upload_enabled False

    Alle Dateien werden als reguläre Uploads hochgeladen und das Hauptkonto benötigt nur die Berechtigungen, die in der Rolle „Storage-Objekt-Ersteller“ (roles/storage.objectCreator) enthalten sind. Sie können storage/parallel_composite_upload_compatibility_check auf einem beliebigen Wert belassen.

  • Wenn Sie parallele zusammengesetzte Uploads benötigen, weisen Sie dem Hauptkonto die Berechtigungen storage.objects.get und storage.objects.delete für den Ziel-Bucket zu. Diese Berechtigungen können über die Rolle „Storage-Objekt-Nutzer“ (roles/storage.objectUser) gewährt werden.

Wenn durch den fehlgeschlagenen Upload temporäre Objekte in Ihrem Bucket verblieben sind, löschen Sie diese. Standardmäßig verwenden temporäre Objekte das Präfix gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details. Zum Löschen temporärer Objekte, die durch einen fehlgeschlagenen Upload entstanden sind, benötigen Sie die Berechtigung storage.objects.delete.

Der Befehl gcloud storage rsync verhält sich anders als gcloud storage cp und gcloud storage mv. Wenn das Ziel ein Bucket-Stammverzeichnis ist, z. B. gs://my-bucket, benötigt gcloud storage rsync immer die Berechtigung storage.buckets.get, um mit dem Bucket zu synchronisieren, unabhängig von Ihren Einstellungen für parallele zusammengesetzte Uploads. Wenn das Ziel ein Bucket-Unterverzeichnis wie gs://my-bucket/dir/ ist, benötigt gcloud storage rsync die Berechtigung storage.buckets.get nicht, solange die Kompatibilitätsprüfung in den Einstellungen für parallele zusammengesetzte Uploads deaktiviert ist. In diesem Szenario erfordert gcloud storage rsync die Berechtigung storage.objects.get anstelle von storage.buckets.get.