Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
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:
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).
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-08-18 (UTC)."],[],[],null,["# URI wildcards\n\nThe [Google Cloud CLI](/sdk/gcloud/reference/storage) supports the use of URI wildcards for files, buckets,\nand objects. Wildcards allow you to efficiently work with groups of files that\nmatch specified naming patterns. This page describes the wildcards that are\nsupported and notes important considerations when using wildcards in commands.\n| **Note:** You cannot use the gcloud CLI to perform operations on folders that have wildcards in the folder's name. For example, you cannot use the gcloud CLI to list objects in the folder `gs://my-bucket/*my-folder/`, which contains the `*` wildcard. Instead, use the Google Cloud console.\n\nWildcard characters\n-------------------\n\nThe gcloud CLI supports the following wildcards:\n\nYou can combine wildcards to provide more powerful matches, for example: \n\n```\ngs://*/[a-m]??.j*g\n```\n\nNote that unless your command includes a flag to return\n[noncurrent object versions](/storage/docs/object-versioning) in the results, these wildcards only match live\nobject versions.\n\nThe gcloud CLI supports the same wildcards for both object and file\nnames. Thus, for example: \n\n```\ngcloud storage cp data/abc* gs://bucket\n```\n\nmatches all files that start with `abc` in the `data` directory of the local\nfile system.\n\nBehavior considerations\n-----------------------\n\nThere are several cases where using wildcards can result in surprising behavior:\n\n- When using wildcards in bucket names, matches are limited to buckets in a\n single [project](/storage/docs/projects). Many commands allow you to specify a project using a\n flag. If a command does not include a project flag or does not support the use\n of a project flag, matches are limited to buckets in the default project.\n\n- Shells (like bash and zsh) can attempt to expand wildcards before passing the\n arguments to the gcloud CLI. If the wildcard was supposed to refer\n to a cloud object, this can result in surprising \"Not found\" errors. For\n example, the shell might try to expand the wildcard `gs://my-bucket/*` on the\n local machine, which would match no local files, causing the command to fail.\n\n Additionally, some shells include other characters in their wildcard\n character sets. For example, if you use zsh with the extendedglob option\n enabled, it treats `#` as a special character, which conflicts with that\n character's use in referencing versioned objects (see\n [Restore noncurrent object versions](/storage/docs/using-versioned-objects#restore) for an example).\n\n To avoid these problems, surround the wildcarded expression with single\n quotes (on Linux) or double quotes (on Windows).\n- Attempting to specify a filename that contains wildcard characters won't work,\n because the command line tools try to expand the wildcard characters rather\n than using them as literal characters. For example, running the command:\n\n ```\n gcloud storage cp './file[1]' gs://my-bucket\n ```\n\n never copies a local file named `file[1]`. Instead, the\n gcloud CLI always treat the `[1]` as a wildcard.\n\n The gcloud CLI does not support a \"raw\" mode that allows it to\n work with file names that contain wildcard characters. For such files, you\n should either use a different tool such as the Google Cloud console or use\n a wildcard to capture the files. For example, to capture a file named\n `file[1]`, you could use the following command: \n\n ```\n gcloud storage cp './file*1*' gs://my-bucket\n ```\n- Per standard Unix behavior, the wildcard `*` only matches files that don't\n start with a `.` character (to avoid confusion with the `.` and `..`\n directories present in all Unix directories). The gcloud CLI\n provides this same behavior when using wildcards over a file system URI, but\n does not provide this behavior over cloud URIs. For example, the following\n command copies all objects from `gs://bucket1` to `gs://bucket2`:\n\n ```\n gcloud storage cp gs://bucket1/* gs://bucket2\n ```\n\n However, the following command copies only files that don't start with a\n `.` from the directory `dir` to `gs://bucket1`: \n\n ```\n gcloud storage cp dir/* gs://bucket1\n ```\n\nEfficiency considerations\n-------------------------\n\n- It is more efficient, faster, and less network traffic-intensive to use\n wildcards that have a non-wildcard object-name prefix, such as:\n\n ```\n gs://bucket/abc*.txt\n ```\n\n than it is to use wildcards as the first part of the object name, such as: \n\n ```\n gs://bucket/*abc.txt\n ```\n\n This is because the request for `gs://bucket/abc*.txt` asks the server to\n send back the subset of results whose object name start with `abc` at the\n bucket root, and then filters the result list for objects whose name ends\n with `.txt`. In contrast, `gs://bucket/*abc.txt` asks the server for the\n complete list of objects in the bucket root, and then filters for those\n objects whose name ends with `abc.txt`. This efficiency consideration\n becomes increasingly noticeable when you use buckets containing thousands or\n more objects. It is sometimes possible to set up the names of your objects\n to fit with expected wildcard matching patterns to take advantage of the\n efficiency of doing server-side prefix requests.\n- Suppose you have a bucket with these objects:\n\n ```\n gs://bucket/obj1\n gs://bucket/obj2\n gs://bucket/obj3\n gs://bucket/obj4\n gs://bucket/dir1/obj5\n gs://bucket/dir2/obj6\n ```\n\n If you run the command: \n\n ```\n gcloud storage ls gs://bucket/*/obj5\n ```\n\n `gcloud storage` performs a `/`-delimited top-level bucket listing and then\n one bucket listing for each subdirectory, for a total of 3 bucket listings: \n\n ```\n GET /bucket/?delimiter=/\n GET /bucket/?prefix=dir1/obj5&delimiter=/\n GET /bucket/?prefix=dir2/obj5&delimiter=/\n ```\n\n The more bucket listings your wildcard requires, the slower and more\n expensive it becomes. The number of bucket listings required grows as:\n - the number of wildcard components (e.g., `gs://bucket/a??b/c*/*/d` has 3\n wildcard components);\n\n - the number of subdirectories that match each component; and\n\n - the number of results (pagination is implemented when the number of\n results is too large, specifying markers for each).\n\n If you want to use a mid-path wildcard, you might try instead using a\n recursive wildcard, for example: \n\n ```\n gcloud storage ls gs://bucket/**/obj5\n ```\n\n This matches more objects than `gs://bucket/*/obj5` (since it spans\n directories), but is implemented using a delimiter-less bucket listing\n request (which means fewer bucket requests, though it lists the entire\n bucket and filters locally, so that could require a non-trivial amount of\n network traffic)."]]
