Tentang objek Cloud Storage

Halaman ini menjelaskan objek, resource dalam Cloud Storage. Untuk ringkasan umum cara kerja Cloud Storage, lihat ringkasan produk Cloud Storage.

Objek

Objek adalah bagian tersendiri dari data yang Anda simpan di Cloud Storage. Tidak ada batasan jumlah objek yang dapat Anda buat di dalam bucket.

Objek memiliki dua komponen: data objek dan metadata objek. Data objek biasanya merupakan file yang ingin disimpan di Cloud Storage dan benar-benar tersembunyi untuk Cloud Storage. Metadata objek adalah set pasangan nama-nilai yang menjelaskan berbagai kualitas objek.

Dua bagian penting dari metadata objek yang umum untuk semua objek adalah nama objek dan nomor pembuatan objek. Saat menambahkan objek ke bucket Cloud Storage, Anda menentukan nama objek dan Cloud Storage menetapkan nomor pembuatan. Bersama, nama dan pembuatan mengidentifikasi objek dalam bucket tersebut secara unik.

Anda dapat menggunakan daftar kontrol akses (ACL) untuk mengontrol akses ke setiap objek. Anda juga dapat menggunakan Identity and Access Management (IAM) untuk mengontrol akses ke semua objek dalam bucket atau folder terkelola.

Pertimbangan penamaan

Nama yang Anda berikan ke objek harus memenuhi persyaratan berikut:

  • Nama objek dapat berisi urutan karakter Unicode yang valid, dengan panjang 1-1.024 byte jika berenkode UTF-8.
  • Nama objek tidak boleh berisi karakter Enter atau Line Feed.
  • Nama objek tidak boleh diawali dengan .well-known/acme-challenge/.
  • Objek tidak boleh diberi nama . atau ...

Sebaiknya hindari hal-hal berikut dalam nama objek Anda:

  • Karakter kontrol yang tidak sah di XML 1.0 (#x7F–#x84 dan #x86–#x9F): karakter ini menyebabkan masalah pencantuman XML saat Anda mencoba mencantumkan objek.
  • Karakter #: Perintah Google Cloud CLI menafsirkan nama objek yang diakhiri dengan #<numerik string> sebagai ID versi, sehingga menyertakan # dalam nama objek dapat membuatnya sulit atau tidak mungkin untuk menjalankan operasi pada objek berversi seperti itu menggunakan gcloud CLI.
  • Karakter [, ], *, atau ?: Perintah Google Cloud CLI menginterpretasikan karakter ini sebagai karakter pengganti, sehingga menyertakannya dalam nama objek dapat membuatnya sulit atau tidak mungkin menjalankan operasi karakter pengganti. Selain itu, * dan ? bukan karakter yang valid untuk nama file di Windows.
  • Karakter :, ", <, >, atau |: Ini bukan karakter yang valid untuk nama file di Windows, jadi berupaya mendownload objek yang menggunakan karakter tersebut dalam namanya menjadi file Windows akan gagal kecuali jika metode download menyertakan penggantian nama file Windows yang dihasilkan. Karakter /, meskipun juga bukan karakter yang valid untuk nama file di Windows, biasanya dapat digunakan dalam nama objek untuk meniru struktur direktori; alat seperti Google Cloud CLI akan otomatis mengonversi karakter menjadi \ saat mendownload ke lingkungan Windows.
  • Informasi identitas pribadi (PII) atau sensitif: nama objek terlihat lebih luas daripada data objek. Misalnya, nama objek muncul di URL untuk objek tersebut dan saat mencantumkan objek di dalam bucket.

Objek yang ada tidak dapat diganti namanya secara langsung, tetapi Anda dapat mengganti nama objek secara tidak langsung dengan menyalin dan menghapus objek aslinya.

Namespace objek

Nama objek berada di namespace datar dalam bucket. Hal ini berarti:

  • Bucket yang berbeda dapat memiliki objek dengan nama yang sama.
  • Objek tidak berada dalam subdirektori di bucket.

Untuk memudahkan, ada beberapa cara objek diperlakukan seolah-olah objek disimpan dalam hierarki folder:

Misalnya, jika Anda membuat objek bernama folder1/file.txt dalam bucket your-bucket, jalur ke objek tersebut adalah your-bucket/folder1/file.txt, dan Cloud Storage tidak memiliki folder bernama folder1 yang tersimpan di dalamnya. Dari perspektif Cloud Storage, string folder1/ adalah bagian dari nama objek.

Namun, karena objek memiliki / di namanya, beberapa alat mengimplementasikan tampilan folder. Misalnya, saat menggunakan konsol Google Cloud, Anda akan membuka objek folder1/file1.txt seolah-olah objek tersebut bernama file1.txt dalam folder bernama folder1. Demikian pula, Anda dapat membuat folder terkelola dengan nama folder1, lalu file1.txt akan tunduk pada kebijakan akses yang disetel oleh folder terkelola ini.

Perhatikan bahwa karena objek berada dalam namespace datar, struktur bertingkat yang dalam, seperti direktori tidak memiliki performa seperti yang dimiliki sistem file native saat mencantumkan sub-direktori bertingkat yang dalam.

Lihat Praktik terbaik rasio permintaan untuk mendapatkan rekomendasi tentang cara mengoptimalkan performa dengan menghindari nama berurutan selama upload berskala besar. Objek yang diupload dengan nama berurutan cenderung akan menjangkau server backend yang sama dan menghambat performa.

Folder simulasi

Untuk membantu Anda mengatur objek di bucket Cloud Storage, beberapa alat menyimulasikan folder, dan JSON API maupun XML API memiliki kemampuan yang dapat Anda gunakan untuk mendesain skema penamaan Anda sendiri guna menyimulasikan folder. Klik tab berikut untuk melihat cara alat yang berbeda menangani folder simulasi.

Konsol

Konsol Google Cloud membuat representasi visual untuk folder yang menyerupai file browser lokal.

Di Konsol Google Cloud, Anda dapat membuat folder kosong di dalam bucket, atau mengupload folder yang sudah ada.

Saat Anda mengupload folder yang ada, nama folder tersebut menjadi bagian dari jalur untuk semua objek yang dimuat dalam folder. Setiap subfolder dan objek yang ada di dalamnya juga akan disertakan dalam file yang diupload.

Untuk membuat folder:

  1. Di Konsol Google Cloud, buka halaman Buckets Cloud Storage.

    Buka Buckets

  2. Buka bucket.

  3. Klik Create folder untuk membuat folder baru yang kosong, atau Upload folder untuk mengupload folder yang sudah ada.

Command line

Cloud Storage CLI menyimulasikan pengalaman direktori command line standar menggunakan berbagai aturan.

Untuk mewujudkan ilusi hierarki file yang hierarkis, gcloud CLI menerapkan aturan berikut untuk menentukan apakah URL tujuan dalam suatu perintah harus diperlakukan sebagai nama objek atau folder:

  1. Jika URL tujuan diakhiri dengan karakter /, perintah gcloud CLI memperlakukan URL tujuan sebagai folder. Misalnya, pertimbangkan perintah berikut, dengan your-file sebagai nama file:

    gcloud storage cp your-file gs://your-bucket/abc/

    Sebagai hasil dari perintah ini, Cloud Storage membuat objek bernama abc/your-file dalam bucket your-bucket.

  2. Jika Anda menyalin beberapa file sumber ke URL tujuan, gcloud CLI akan memperlakukan URL tujuan sebagai folder. Misalnya, pertimbangkan perintah berikut dengan your-dir adalah folder yang berisi file seperti file1 dan file2:

    gcloud storage cp your-dir gs://your-bucket/abc --recursive

    Sebagai hasil dari perintah ini, Cloud Storage membuat objek abc/your-dir/file1 dan abc/your-dir/file2 di bucket your-bucket.

  3. Jika tidak satu pun aturan ini berlaku, gcloud CLI akan memeriksa objek di dalam bucket untuk menentukan apakah URL tujuan merupakan nama objek atau folder. Misalnya, pertimbangkan perintah berikut dengan your-file adalah nama file:

    gcloud storage cp your-file gs://your-bucket/abc

    Gcloud CLI membuat permintaan listingan objek untuk your-bucket, menggunakan pembatas / dan awalan=abc, guna menentukan apakah ada objek di your-bucket yang jalurnya dimulai dengan abc/. Jika demikian, gcloud CLI memperlakukan abc/ sebagai nama folder, dan perintah tersebut akan membuat objek abc/your-file di bucket your-bucket. Jika tidak, gcloud CLI akan membuat objek abc di your-bucket.

Pendekatan berbasis aturan ini berbeda dengan cara kerja banyak alat, yang membuat objek 0 byte untuk menandai keberadaan folder. Gcloud CLI memahami beberapa konvensi yang digunakan oleh alat tersebut, seperti konvensi penambahan _$folder$ di akhir nama objek 0 byte, tetapi tidak memerlukan objek penanda tersebut untuk menerapkan perilaku penamaan yang konsisten dengan perintah UNIX.

Percobaan ulang dan penamaan

Saat gcloud CLI mencoba ulang permintaan yang terganggu, Anda mungkin akan mengalami masalah saat upaya pertama menyalin subset file, dan upaya berikutnya akan menemukan folder tujuan yang sudah ada, yang menyebabkan objek Anda salah diberi nama.

Misalnya, pertimbangkan perintah berikut, jika ada subfolder di your-dir/, seperti dir1 dan dir2, dan kedua subfolder berisi file abc:

gcloud storage cp ./your-dir gs://your-bucket/new --recursive

Jika jalur gs://your-bucket/new belum ada, gcloud CLI akan membuat objek berikut pada upaya pertama yang berhasil:

new/dir1/abc
new/dir2/abc

Namun, jika perintah yang sama berhasil berikutnya berhasil, gcloud CLI akan membuat objek berikut:

new/your-dir/dir1/abc
new/your-dir/dir2/abc

Agar gcloud CLI berfungsi secara konsisten setiap kali Anda mencoba, coba langkah berikut:

  1. Tambahkan garis miring di akhir URL tujuan agar gcloud CLI selalu memperlakukannya sebagai folder.

  2. Gunakan gcloud storage rsync. Karena rsync tidak menggunakan aturan penamaan folder yang ditentukan oleh Unix, kode ini akan berfungsi secara konsisten, baik subfolder tujuan ada atau tidak.

Untuk mengetahui informasi selengkapnya tentang cara pembuatan nama, lihat konstruksi nama menggunakan cp.

Catatan tambahan

  • Anda tidak dapat membuat objek zero-byte untuk meniru folder kosong menggunakan gcloud CLI.

  • Jika Anda menggunakan skrip untuk membuat jalur file dengan menggabungkan subjalur, perhatikan bahwa karena / hanyalah karakter yang kebetulan ada dalam nama objek, CLI akan menafsirkan gs://my-bucket/folder/ sebagai objek yang berbeda dengan gs://my-bucket//folder.

REST API

JSON API

Folder tidak ada di JSON API. Anda dapat mempersempit objek yang dicantumkan dan menyimulasikan folder menggunakan parameter kueri prefix dan delimiter.

Misalnya, untuk menampilkan daftar semua objek di bucket my-bucket dengan awalan folder/subfolder/, buat permintaan listingan objek menggunakan URL ini:

"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"

XML API

Folder tidak ada di XML API. Anda dapat mempersempit objek yang dicantumkan dan menyimulasikan folder menggunakan parameter kueri prefix dan delimiter.

Misalnya, untuk menampilkan daftar semua objek di bucket my-bucket dengan awalan folder/subfolder/, buat permintaan listingan objek menggunakan URL ini:

"https://storage.googleapis.com/my-bucket?prefix=folder/subfolder/"

Menghapus folder simulasi

Karena folder simulasi sebenarnya tidak ada, Anda biasanya dapat menghapus folder simulasi dengan mengganti nama objek sehingga folder yang disimulasikan tidak lagi menjadi bagian dari nama objek. Misalnya, jika memiliki objek bernama folder1/file, Anda dapat menghapus folder simulasi folder1/ dengan mengganti nama objek menjadi file saja.

Namun, jika Anda pernah menggunakan alat yang membuat objek zero-byte sebagai placeholder folder, seperti Google Cloud Console, Anda harus menghapus objek zero-byte agar folder ini dihapus.

Imutabilitas objek

Objek tidak dapat diubah, artinya objek yang diupload tidak dapat berubah selama masa penyimpanannya. Masa aktif penyimpanan objek adalah waktu antara berhasil membuat objek, seperti mengupload, dan menghapus objek. Dalam praktiknya, Anda tidak dapat melakukan perubahan inkremental pada objek, seperti operasi penambahan atau operasi pemotongan. Namun, Anda dapat mengganti objek yang disimpan di Cloud Storage, dan hal itu terjadi secara atomik: hingga upload baru selesai, versi lama objek akan ditayangkan kepada pembaca, dan setelah upload selesai, versi baru objek akan ditayangkan kepada pembaca. Operasi penggantian tunggal menandai akhir masa aktif satu objek yang tidak dapat diubah dan awal masa aktif objek baru yang tidak dapat diubah.

Nomor pembuatan untuk objek berubah setiap kali Anda mengganti data objek. Dengan demikian, nomor pembuatan secara unik mengidentifikasi objek yang tidak dapat diubah.

Perlu diketahui bahwa ada batas sekali per detik untuk mengganti objek yang sama dengan cepat. Mengganti objek yang sama lebih sering dapat menyebabkan error 429 Too Many Requests. Anda harus mendesain aplikasi agar mengupload data untuk objek tertentu tidak lebih dari sekali per detik dan menangani error 429 Too Many Requests sesekali menggunakan strategi coba ulang backoff eksponensial.

Langkah selanjutnya