Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
Google Cloud CLI mendukung penggunaan karakter pengganti URI untuk file, bucket, dan objek. Karakter pengganti memungkinkan Anda bekerja secara efisien dengan kelompok file yang cocok dengan pola penamaan tertentu. Halaman ini menjelaskan karakter pengganti yang
didukung dan mencatat pertimbangan penting saat menggunakan karakter pengganti dalam perintah.
Karakter pengganti
gcloud CLI mendukung karakter pengganti berikut:
Berbasis karakter
Deskripsi
*
Mencocokkan nol karakter atau lebih dalam level direktori saat ini. Misalnya, cp gs://my-bucket/abc/d* cocok dengan objek abc/def.txt, tetapi tidak dengan objek abc/def/g.txt. Dalam hal perintah listingan seperti ls, jika * di akhir cocok dengan sub-direktori di tingkat direktori saat ini, konten sub-direktori juga akan dicantumkan.
**
Mencocokkan nol karakter atau lebih di seluruh batas direktori. Saat digunakan sebagai bagian dari jalur file lokal, karakter pengganti ** harus selalu diawali dengan pemisah direktori. Misalnya, my-directory/**.txt valid, tetapi my-directory/abc** tidak.
?
Mencocokkan satu karakter. Misalnya, gs://bucket/??.txt hanya mencocokkan objek dengan tepat dua karakter yang diikuti dengan .txt.
[CHARACTERS]
Mencocokkan dengan karakter yang ditentukan. Misalnya, gs://bucket/[aeiou].txt mencocokkan objek yang berisi karakter vokal tunggal yang diikuti dengan .txt.
[CHARACTER_RANGE]
Mencocokkan salah satu rentang karakter. Misalnya, gs://bucket/[a-e].txt mencocokkan objek yang berisi huruf a, b, c, d, atau e, yang diikuti dengan .txt.
Anda dapat menggabungkan karakter pengganti untuk memberikan pencocokan yang lebih kuat, misalnya:
gs://*/[a-m]??.j*g
Perlu diperhatikan bahwa karakter pengganti ini hanya cocok dengan versi objek aktif, kecuali jika perintah Anda menyertakan flag untuk menampilkan versi objek lama dalam hasil.
gcloud CLI mendukung karakter pengganti yang sama untuk nama objek dan
file. Jadi, misalnya:
gcloud storage cp data/abc* gs://bucket
cocok dengan semua file yang dimulai dengan abc di direktori data sistem file
lokal.
Pertimbangan perilaku
Ada beberapa kasus ketika penggunaan karakter pengganti dapat menghasilkan perilaku yang mengejutkan:
Saat menggunakan karakter pengganti dalam nama bucket, pencocokan dibatasi pada bucket dalam satu project. Banyak perintah yang memungkinkan Anda menentukan project menggunakan
flag. Jika suatu perintah tidak menyertakan flag project atau tidak mendukung penggunaan
flag project, pencocokan akan dibatasi pada bucket dalam project default.
Shell (seperti bash dan zsh) dapat mencoba memperluas karakter pengganti sebelum meneruskan argumen ke gcloud CLI. Jika karakter pengganti seharusnya merujuk ke objek cloud, hal ini dapat menyebabkan error "Tidak ditemukan" yang mengejutkan. Misalnya, shell mungkin mencoba memperluas karakter pengganti gs://my-bucket/* di
mesin lokal, yang tidak akan cocok dengan file lokal, sehingga menyebabkan perintah gagal.
Selain itu, beberapa shell menyertakan karakter lain dalam kumpulan karakter penggantinya. Misalnya, jika Anda menggunakan zsh yang mengaktifkan opsi extendedglob, zsh akan memperlakukan # sebagai karakter khusus, yang bertentangan dengan penggunaan karakter tersebut dalam mereferensikan objek berversi (lihat
Memulihkan versi objek.
Untuk menghindari masalah ini, apit ekspresi karakter pengganti dengan tanda kutip tunggal (di Linux) atau tanda kutip ganda (di Windows).
Mencoba menentukan nama file yang berisi karakter pengganti tidak akan berhasil,
karena alat command line mencoba memperluas karakter pengganti,
bukan menggunakannya sebagai karakter literal. Misalnya, menjalankan perintah:
gcloud storage cp './file[1]' gs://my-bucket
jangan pernah menyalin file lokal bernama file[1]. Sebagai gantinya, gcloud CLI selalu memperlakukan [1] sebagai karakter pengganti.
gcloud CLI tidak mendukung mode "mentah" yang memungkinkannya
berfungsi dengan nama file yang berisi karakter pengganti. Untuk file tersebut, Anda harus menggunakan alat lain, seperti konsol Google Cloud , atau menggunakan karakter pengganti untuk mengambil file. Misalnya, untuk mengambil file bernama
file[1], Anda dapat menggunakan perintah berikut:
gcloud storage cp './file*1*' gs://my-bucket
Sesuai perilaku Unix standar, karakter pengganti * hanya mencocokkan file yang tidak
diawali dengan karakter . (untuk menghindari kebingungan dengan direktori . dan
.. yang ada di semua direktori Unix). CLI gcloud
memberikan perilaku yang sama saat menggunakan karakter pengganti pada URI sistem file, tetapi
tidak memberikan perilaku ini di atas URI cloud. Misalnya, perintah berikut
menyalin semua objek dari gs://bucket1 ke gs://bucket2:
gcloud storage cp gs://bucket1/* gs://bucket2
Namun, perintah berikut hanya menyalin file yang tidak diawali dengan
. dari direktori dir ke gs://bucket1:
gcloud storage cp dir/* gs://bucket1
Pertimbangan efisiensi
Traffic jaringan akan lebih efisien, lebih cepat, dan lebih hemat jika menggunakan karakter pengganti yang memiliki awalan nama objek non-karakter pengganti, seperti:
gs://bucket/abc*.txt
daripada menggunakan karakter pengganti sebagai bagian pertama dari nama objek, seperti:
gs://bucket/*abc.txt
Hal ini karena permintaan untuk gs://bucket/abc*.txt meminta server mengirimkan kembali subset hasil yang nama objeknya diawali dengan abc di root bucket, lalu memfilter daftar hasil untuk objek yang namanya diakhiri dengan
.txt. Sebaliknya, gs://bucket/*abc.txt akan meminta daftar lengkap objek di root bucket, lalu memfilter objek yang namanya diakhiri dengan abc.txt. Pertimbangan efisiensi ini akan menjadi semakin jelas saat Anda menggunakan bucket yang berisi ribuan objek atau lebih. Terkadang, Anda dapat menyiapkan nama objek agar sesuai dengan pola pencocokan karakter pengganti yang diharapkan untuk memanfaatkan efisiensi permintaan awalan sisi server.
Misalkan Anda memiliki bucket dengan objek berikut:
gcloud storage menjalankan listingan bucket level teratas yang dibatasi /, lalu
satu listingan bucket untuk setiap subdirektori, dengan total 3 listingan bucket:
GET /bucket/?delimiter=/
GET /bucket/?prefix=dir1/obj5&delimiter=/
GET /bucket/?prefix=dir2/obj5&delimiter=/
Makin banyak bucket yang mencantumkan karakter pengganti yang Anda butuhkan, bucket tersebut akan semakin lambat dan mahal. Jumlah listingan bucket yang diperlukan bertambah seiring:
jumlah komponen karakter pengganti (misalnya, gs://bucket/a??b/c*/*/d memiliki 3
komponen karakter pengganti);
jumlah subdirektori yang cocok dengan setiap komponen; dan
jumlah hasil (penomoran halaman diterapkan saat jumlah hasil terlalu besar, yang menentukan penanda untuk setiap hasil).
Jika ingin menggunakan karakter pengganti di jalur tengah, Anda dapat mencoba menggunakan karakter pengganti berulang, misalnya:
gcloud storage ls gs://bucket/**/obj5
Ini cocok dengan lebih banyak objek daripada gs://bucket/*/obj5 (karena mencakup direktori), tetapi diterapkan menggunakan permintaan listingan bucket tanpa pembatas (yang berarti lebih sedikit permintaan bucket, meskipun mencantumkan seluruh bucket dan memfilter secara lokal, sehingga mungkin memerlukan jumlah
traffic jaringan yang tidak umum).
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Sulit dipahami","hardToUnderstand","thumb-down"],["Informasi atau kode contoh salah","incorrectInformationOrSampleCode","thumb-down"],["Informasi/contoh yang saya butuhkan tidak ada","missingTheInformationSamplesINeed","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 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)."]]
