URI-Platzhalter

Die Google Cloud CLI unterstützt die Verwendung von URI-Platzhaltern für Dateien, Buckets und Objekte. Mit Platzhaltern können Sie effizient mit Gruppen von Dateien arbeiten, die bestimmten Benennungsmustern entsprechen. Auf dieser Seite werden die unterstützten Platzhalter beschrieben. Außerdem werden wichtige Überlegungen zur Verwendung von Platzhaltern in Befehlen aufgeführt.

Platzhalterzeichen

Die gcloud-Befehlszeile unterstützt die folgenden Platzhalter:

Zeichen Beschreibung
* Entspricht null oder mehr Zeichen innerhalb der aktuellen Verzeichnisebene. Beispiel: cp gs://my-bucket/abc/d* stimmt mit dem Objekt abc/def.txt überein, aber nicht mit dem Objekt abc/def/g.txt. Bei der Auflistung von Befehlen wie ls, wenn ein nachgestelltes * mit einem Unterverzeichnis auf der aktuellen Verzeichnisebene übereinstimmt, wird auch der Inhalt des Unterverzeichnisses aufgelistet.
** Entspricht null oder mehr Zeichen über Verzeichnisgrenzen hinweg. Bei Verwendung als Teil eines lokalen Dateipfads sollte dem Platzhalter ** immer ein Verzeichnistrennzeichen unmittelbar vorangestellt werden. Beispiel: my-directory/**.txt ist gültig, my-directory/abc** jedoch nicht.
? Entspricht einem einzelnen Zeichen. gs://bucket/??.txt entspricht beispielsweise nur Objekten mit zwei Zeichen, gefolgt von .txt.
[CHARACTERS] Stimmt mit einem der angegebenen Zeichen überein. Beispielsweise sucht gs://bucket/[aeiou].txt nach Objekten mit einem einzelnen Vokalzeichen gefolgt von .txt.
[CHARACTER_RANGE] entspricht einem beliebigen Zeichenbereich. Beispielsweise sucht gs://bucket/[a-e].txt nach Objekten, die den Buchstaben a, b, c, d oder e gefolgt von .txt enthalten.

Sie können Platzhalter kombinieren, um leistungsstärkere Übereinstimmungen zu erhalten. Beispiel:

gs://*/[a-m]??.j*g

Beachten Sie, dass, sofern Ihr Befehl kein Flag zum Zurückgeben von nicht aktuellen Objektversionen in den Ergebnissen enthält, diese Platzhalter Live-Objektversionen entsprechen.

Die gcloud-Befehlszeile unterstützt für Objekt- und Dateinamen dieselben Platzhalter. So gilt zum Beispiel:

gcloud storage cp data/abc* gs://bucket

entspricht allen Dateien, die mit abc im Verzeichnis data des lokalen Dateisystems beginnen.

Überlegungen zum Verhalten

Es gibt mehrere Fälle, in denen Platzhalter zu unerwartetem Verhalten führen können:

  • Wenn Sie Platzhalter in Bucket-Namen verwenden, sind Übereinstimmungen auf Buckets in einem einzelnen Projekt beschränkt. Bei vielen Befehlen können Sie Projekte mit einem Flag angeben. Wenn ein Befehl kein Projekt-Flag enthält oder die Verwendung eines Projekt-Flags nicht unterstützt, sind Übereinstimmungen auf Buckets im Standardprojekt beschränkt.

  • Hinweis: Shells (wie bash und zsh) können versuchen, Platzhalter zu erweitern, bevor die Argumente an die gcloud CLI übergeben werden. Wenn der Platzhalter auf ein Cloud-Objekt verweisen sollte, kann dies zu unerwarteten "Nicht gefunden"-Fehlern führen. Beispielsweise könnte die Shell versuchen, den Platzhalter gs://my-bucket/* auf dem lokalen Computer zu erweitern, der keine lokalen Dateien entspricht, was dazu führt, dass der Befehl fehlschlägt.

    Darüber hinaus enthalten einige Shells andere Zeichen in ihren Platzhalter-Zeichensätzen. Wenn Sie beispielsweise zsh mit der extendedglob-Option verwenden, wird # als Sonderzeichen behandelt, das mit der Verwendung dieses Zeichens in Bezug auf versionierte Objekte in Konflikt steht. Ein Beispiel finden Sie unter Nicht aktuelle Objektversionen wiederherstellen.

    Setzen Sie den Ausdruck mit Platzhalter zur Vermeidung dieser Probleme in einfache Anführungszeichen (unter Linux) oder doppelte Anführungszeichen (unter Windows).

  • Der Versuch, einen Dateinamen anzugeben, der Platzhalterzeichen enthält, schlägt fehl, da die Befehlszeilentools versuchen, die Platzhalterzeichen zu erweitern, statt sie als Literalzeichen zu verwenden. Führen Sie beispielsweise den folgenden Befehl aus:

    gcloud storage cp './file[1]' gs://my-bucket

    kopiert nie eine lokale Datei mit dem Namen file[1]. Stattdessen behandelt die gcloud CLI [1] immer als Platzhalter.

    Die gcloud CLI unterstützt keinen „Roh“-Modus, in dem Dateinamen mit Platzhalterzeichen verwendet werden können. Für solche Dateien sollten Sie entweder ein anderes Tool, z. B. die Google Cloud Console, oder einen Platzhalter zum Erfassen der Dateien verwenden. Wenn Sie beispielsweise eine Datei mit dem Namen file[1] erfassen möchten, können Sie folgenden Befehl verwenden:

    gcloud storage cp './file*1*' gs://my-bucket

  • Gemäß dem Unix-Standardverhalten ordnet der Platzhalter * nur Dateien zu, die nicht mit einem .-Zeichen beginnen (um Verwechslungen mit den Verzeichnissen . und .. zu vermeiden, die in allen Unix-Verzeichnissen vorkommen). Die gcloud CLI bietet dieses Verhalten, wenn Sie Platzhalter über einen Dateisystem-URI verwenden, bietet dieses Verhalten aber nicht für Cloud-URIs. Mit folgendem Befehl werden beispielsweise alle Objekte von gs://bucket1 nach gs://bucket2 kopiert:

    gcloud storage cp gs://bucket1/* gs://bucket2

    Mit folgendem Befehl werden jedoch nur Dateien kopiert, die nicht mit einem . beginnen, und zwar aus dem Verzeichnis dir nach gs://bucket1:

    gcloud storage cp dir/* gs://bucket1

Überlegungen zur Effizienz

  • Die Verwendung von Platzhaltern mit einem Objektnamenpräfix ohne Platzhalter ist effizienter, schneller und weniger netzwerkintensiv. Beispiel:

    gs://bucket/abc*.txt

    als Platzhalter als ersten Teil des Objektnamens zu verwenden. Beispiel:

    gs://bucket/*abc.txt

    Dies liegt daran, dass die Anfrage für gs://bucket/abc*.txt den Server auffordert, die Teilmenge der Ergebnisse zurückzusenden, deren Objektname mit abc im Bucket-Stammverzeichnis beginnt, und dann die Ergebnisliste nach Objekten filtert, deren Name mit .txt endet. Im Gegensatz dazu fragt gs://bucket/*abc.txt den Server nach der vollständigen Liste der Objekte im Bucket-Stammverzeichnis und filtert dann nach den Objekten, deren Name mit abc.txt endet. Die Effizienz wirkt sich immer deutlicher aus, wenn Sie Buckets mit Tausenden oder mehr Objekten verwenden. Es ist möglich, die Namen Ihrer Objekte so einzurichten, dass sie mit den Mustern für den Abgleich mit erwarteten Platzhaltern übereinstimmen, um die Effizienz von serverseitigen Präfixanfragen nutzen zu können.

  • Angenommen, Sie haben einen Bucket mit diesen Objekten:

    gs://bucket/obj1
gs://bucket/obj2
gs://bucket/obj3
gs://bucket/obj4
gs://bucket/dir1/obj5
gs://bucket/dir2/obj6

    Wenn Sie den Befehl ausführen:

    gcloud storage ls gs://bucket/*/obj5

    gcloud storage führt eine /-getrennte Top-Level-Bucket-Auflistung durch und erstellt dann Listen für alle Unterverzeichnisse. Insgesamt gibt es also drei Bucket-Einträge:

    GET /bucket/?delimiter=/
GET /bucket/?prefix=dir1/obj5&delimiter=/
GET /bucket/?prefix=dir2/obj5&delimiter=/

    Je mehr Buckets Ihr Platzhalter enthält, desto langsamer und teurer ist es. Die Anzahl der erforderlichen Bucket-Einträge erhöht sich so:

    • Die Anzahl der Platzhalterkomponenten (z. B. gs://bucket/a??b/c*/*/d hat drei Platzhalterkomponenten).

    • Die Anzahl der Unterverzeichnisse, die der jeweiligen Komponente entsprechen und

    • Die Anzahl der Ergebnisse (Paginierung erfolgt, wenn die Anzahl der Ergebnisse zu groß ist, wobei Markierungen pro Anfrage angegeben werden).

    Wenn Sie einen Mid-Path-Platzhalter verwenden möchten, können Sie stattdessen einen rekursiven Platzhalter verwenden. Beispiel:

    gcloud storage ls gs://bucket/**/obj5

    Dies entspricht mehr Objekten als gs://bucket/*/obj5 (da es sich über Verzeichnisse erstreckt), ist aber durch eine Auflistungsanfrage ohne Trennzeichen implementiert (was weniger Bucket-Anfragen bedeutet, obwohl es den gesamten Bucket auflistet und lokal filtert, sodass eine nicht unerhebliche Menge an Netzwerkverkehr erforderlich sein könnte).