Von gsutil zu gcloud storage wechseln

gcloud storage (allgemeine Verfügbarkeit) ist das empfohlene Befehlszeilentool für die Interaktion mit Cloud Storage. Auf dieser Seite wird der Umstieg von gsutil auf gcloud storage erleichtert. Dazu werden die wichtigsten Unterschiede und Befehlszuordnungen zwischen den beiden Tools beschrieben. Eine ausführliche Beschreibung des gcloud storage-Tools finden Sie in der Referenzdokumentation zu gcloud storage.

Informationen zum Installieren und Verwenden der Google Cloud CLI finden Sie unter Google Cloud CLI installieren.

Verhaltensunterschiede

In den folgenden Abschnitten werden die Verhaltensunterschiede zwischen gsutil und gcloud storage beschrieben.

Parallele Aufrufe

gcloud storage unterstützt nicht die gleichzeitige Ausführung mehrerer Instanzen der CLI über verschiedene Terminals.

Parallelverarbeitung

gcloud storage unterstützt die parallele Verarbeitung.

Umgang mit Platzhaltern

gcloud storage vereinfacht die Verwendung mehrerer Sternchen. Wenn Sie drei oder mehr Sternchen in einer Zeile verwenden (***), werden sie als einzelnes Sternchen (*) behandelt.

Verarbeitung von Buckets mit hierarchischem Namespace

Mit gcloud storage können Sie Buckets mit aktiviertem hierarchischen Namespace erstellen und verwalten.

Ausgabeformat

Die Befehle gcloud storage und gsutil formatieren ihre Ausgabe unterschiedlich. Geringfügige Änderungen wie das Protokollierungsformat wirken sich möglicherweise nicht auf Sie aus. Bei größeren Unterschieden bei Fehlermeldungen und Datenlisten können jedoch automatisierte Skripts fehlerhaft ausgeführt werden.

Wenn Sie Skripts haben, die auf dem Parsen der Ausgabe des Befehls gsutil basieren, sollten Sie sie vor der Umstellung auf das Format gcloud storage überprüfen und aktualisieren.

Entsprechende gcloud-Befehle

Für alle gsutil-Befehle gibt es, abgesehen von wenigen Ausnahmen, gleichwertige Befehle in gcloud storage. Eine vollständige Liste der gcloud storage-Befehle finden Sie in der Referenzdokumentation oder durch Ausführung des Befehls gcloud storage --help. In der nachfolgenden Tabelle sind die Unterschiede zu den häufig genutzten gsutil-Befehlen kurz dargestellt.

Vorgang gsutil-Befehl gcloud storage-Befehl
Zugriffssteuerungslisten (Access Control Lists, ACLs) verwalten 
gsutil acl get
gsutil acl set
gsutil acl ch

gcloud storage RESOURCE describe --format="multi(acl:format=json)"
gcloud storage RESOURCE update --acl-file=ACL_FILE_PATH
gcloud storage RESOURCE update --add-acl-grant=GRANT
gcloud storage RESOURCE update --remove-acl-grant=GRANT
Vorgang gsutil-Befehl gcloud storage-Befehl
Objekte verketten und Objektinhalte anzeigen 
gsutil cat
 
gcloud storage cat
Vorgang gsutil-Befehl gcloud storage-Befehl
Objekte verketten, indem Sie sie in einem neuen Objekt kombinieren 
gsutil compose
 
gcloud storage objects compose
Hinweise
Wenn Sie Vorbedingungen in gcloud storage objects compose anwenden möchten, verwenden Sie bestimmte Flags wie --if-generation-match oder --if-metageneration-match.
Vorgang gsutil-Befehl gcloud storage-Befehl
Objekte und andere Ressourcen kopieren 
gsutil cp
 
gcloud storage cp
Hinweise

Simulierte Ordner, die mit der Google Cloud Console erstellt wurden, werden als 0-Byte-Platzhalterobjekte erkannt. Mit gcloud storage cp können simulierte Ordner kopiert werden, mit gsutil cp nicht.

Bei der Fehlerbehandlung versucht gcloud storage cp, alle Ressourcen zu kopieren, auch wenn eine der Ressourcen ungültig ist oder nicht vorhanden ist. gsutil cp kann den gesamten Vorgang beenden, sobald eine ungültige Ressource gefunden wird.

Beim Herunterladen eines Objekts erstellt gcloud storage cp alle fehlenden lokalen Verzeichnisse, die im Zielpfad angegeben sind. gsutil cp schlägt fehl, wenn das Zielverzeichnis nicht vorhanden ist.
Vorgang gsutil-Befehl gcloud storage-Befehl
Gesamten von Objekten belegten Speicherplatz anzeigen 
gsutil du
 
gcloud storage du
Vorgang gsutil-Befehl gcloud storage-Befehl
Datei-Hashes berechnen 
gsutil hash
 
gcloud storage hash
Hinweise

gsutil hash verwendet additive Flags, um bestimmte Hashes einzuschließen, z. B. -c oder -m. gcloud storage hash verwendet subtraktive Flags zum Ausschließen von Hashes, z. B. --skip-md5 oder --skip-crc32c.
Vorgang gsutil-Befehl gcloud storage-Befehl
Bucket-Labels verwalten 
gsutil label get
gsutil label set
gsutil label ch

gcloud storage buckets describe
gcloud storage buckets update
gcloud storage buckets update
Hinweise

Die Kombination aus dem Hinzufügen, Aktualisieren und Entfernen von Labels in einem einzelnen gsutil label ch-Befehl kann sich anders verhalten als die entsprechenden Vorgänge mit gcloud storage buckets update. Skripts, die auf einem bestimmten Lese-/Änderungs-/Schreibverhalten von gsutil basieren, sollten nach der Umstellung auf gcloud storage sorgfältig getestet werden.
Vorgang gsutil-Befehl gcloud storage-Befehl
Buckets, Objekte und Ordner auflisten 
gsutil ls
 
gcloud storage ls
Hinweise

Wenn ein Platzhalter verwendet wird, um Objekte in einem Projekt aufzulisten, gibt gsutil ls eine flache Liste von Objekten zurück, während gcloud storage ls Objekte nach Bucket-Name gruppiert zurückgibt.

Wenn Sie gcloud storage ls -L verwenden, um detaillierte Einträge als Ausgabe zurückzugeben, gelten die folgenden Verhaltensweisen:

  • Bei den Labels für die einzelnen Metadaten (auch als „Schlüssel“ bezeichnet) wird der erste Buchstabe jedes Wortes großgeschrieben.
  • Wenn ein Metadatenabschnitt für ein Objekt keinen Wert hat, wird diese Zeile in der Ausgabe von gcloud storage ausgelassen.

gcloud storage gibt Datetime-Werte immer in UTC aus.

gcloud storage gibt alle Fehlermeldungen am Ende der Befehlsausgabe zurück.
Vorgang gsutil-Befehl gcloud storage-Befehl
Objekte oder Verzeichnisse verschieben und umbenennen 
gsutil mv
 
gcloud storage mv
Vorgang gsutil-Befehl gcloud storage-Befehl
Objekte direkt umschreiben 
gsutil rewrite
 
gcloud storage objects update
Hinweise

Wenn in Ihrer Boto-Konfigurationsdatei ein encryption_key festgelegt ist, wendet gsutil rewrite -k den Schlüssel auf die Objekte an. Wenn encryption_key nicht festgelegt ist, entspricht gsutil rewrite -k dem Wert gcloud storage objects update --clear-encryption-key. Dadurch werden alle vom Kunden bereitgestellten Verschlüsselungsschlüssel (CSEK) oder vom Kunden verwalteten Verschlüsselungsschlüssel (CMEK) aus dem Objekt entfernt. Das Objekt wird dann mit dem Standard-KMS-Schlüssel des Buckets oder mit der von Googleverwalteten Verschlüsselung verschlüsselt.

gsutil rewrite enthält Logik, um das Umschreiben eines Objekts zu überspringen, wenn die angeforderte Transformation seinen Status nicht ändern würde (z. B. wenn sich das Objekt bereits in einer Zielspeicherklasse befindet). gcloud storage objects update führt möglicherweise nicht dieselben Prüfungen durch, was zu unnötigen Vorgängen führen kann.
Vorgang gsutil-Befehl gcloud storage-Befehl
Objekte oder Buckets entfernen 
gsutil rm
 
gcloud storage rm
Hinweise

Die gsutil-Aliasse del, delete und remove werden nicht unterstützt.

Es gibt ein bekanntes Problem, bei dem sich gsutil und gcloud storage unterschiedlich verhalten, wenn die Flags -l und -r zusammen verwendet werden. Skripts, die eine Liste von Verzeichnissen übergeben, die rekursiv gelöscht werden sollen, sollten gründlich getestet werden, bevor von gsutil auf gcloud storage umgestellt wird.
Vorgang gsutil-Befehl gcloud storage-Befehl
Inhalte von zwei Buckets oder Verzeichnissen synchronisieren 
gsutil rsync
 
gcloud storage rsync
Hinweise

Standardmäßig betrachtet gsutil rsync ein Objekt als unverändert, wenn seine Größe und die letzte Änderungszeit zwischen Quelle und Ziel übereinstimmen. Ein gründlicherer Prüfsummenvergleich wird nur durchgeführt, wenn für ein Objekt die Änderungszeit fehlt oder wenn Sie ihn mit dem Flag -c manuell erzwingen. gcloud storage rsync prüft zuerst die Größe und das Datum der letzten Änderung einer Datei. Wenn die Objektgrößen übereinstimmen, die Änderungszeiten jedoch unterschiedlich sind oder fehlen, wird automatisch ein Prüfsummenvergleich durchgeführt.

gcloud storage rsync führt Vorgänge standardmäßig parallel aus, um die Leistung zu verbessern. gsutil rsync wird sequenziell ausgeführt, sofern nicht das -m-Flag auf oberster Ebene verwendet wird.

gsutil rsync folgt standardmäßig symbolischen Links. gcloud storage rsync ignoriert sie standardmäßig, sofern nicht das Flag --no-ignore-symlinks verwendet wird.
Vorgang gsutil-Befehl gcloud storage-Befehl
Metadaten für hochgeladene Objekte festlegen 
gsutil setmeta
 
gcloud storage objects update
Hinweise

gsutil setmeta verwendet ein einzelnes, wiederholbares -h-Flag, um anzugeben, welche Metadaten festgelegt oder entfernt werden sollen. gcloud storage objects update verwendet für jedes Metadatenfeld separate Flags, z. B. --content-type, --clear-cache-control oder --update-custom-metadata.

In gsutil setmeta wird das Flag -h verwendet, um den vollständigen Headernamen festzulegen (z. B. -h "x-goog-meta-icecreamflavor:vanilla"). In gcloud storage objects update wird stattdessen das Flag --update-custom-metadata verwendet, das Schlüssel/Wert-Paare akzeptiert (z. B. --update-custom-metadata=icecreamflavor=vanilla). Wenn Sie ein benutzerdefiniertes Metadatenfeld entfernen möchten, wird in gsutil setmeta -h "x-goog-meta-icecreamflavor" verwendet, in gcloud storage objects update hingegen --remove-custom-metadata=icecreamflavor.
Vorgang gsutil-Befehl gcloud storage-Befehl
Objektstatus anzeigen 
gsutil stat
 
gcloud storage objects list --stat --fetch-encrypted-object-hashes
Hinweise

Das Ausgabeformat von gcloud storage objects list --stat unterscheidet sich vom Ausgabeformat von gsutil stat. Es gibt bekannte Probleme im Zusammenhang mit inkonsistenten Abständen. Scripts, die zum Parsen der Ausgabe von gsutil stat geschrieben wurden, müssen möglicherweise angepasst werden, um das neue Ausgabeformat zu verarbeiten.