Karakter pengganti URI

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 yang ditentukan. 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). gcloud CLI memberikan perilaku yang sama saat menggunakan karakter pengganti pada URI sistem file, tetapi tidak menyediakan 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:

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

    Jika Anda menjalankan perintah:

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

    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).