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

Saat memberi nama objek di Cloud Storage, Anda harus mematuhi persyaratan tertentu untuk memastikan kompatibilitas dan mencegah error. Persyaratan ini berlaku untuk bucket namespace datar dan bucket yang mengaktifkan namespace hierarkis.

Persyaratan umum

  • Nama objek dapat berisi urutan karakter Unicode yang valid.
  • 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 ...

Batas ukuran objek khusus namespace

Ukuran maksimum nama objek bervariasi bergantung pada namespace bucket:

  • Ukuran nama objek dalam bucket namespace datar: 1-1.024 byte jika berenkode UTF-8.

  • Ukuran nama objek di bucket yang diaktifkan dengan Namespace hierarkis: Nama objek dapat dibagi menjadi dua bagian:

    • Nama folder: Nama folder tempat objek berada. Ukuran maksimum untuk nama folder adalah 512 byte saat dienkode UTF-8.
    • Nama dasar: Nama objek yang berada di folder. Ukuran maksimum untuk nama dasar adalah 512 byte jika berenkode UTF-8.

    Misalnya, jalur my-folder/my-object.txt mewakili objek dengan nama dasar sebagai my-object.txt yang disimpan dalam folder bernama my-folder/.

Saran

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

Anda dapat menyimpan objek di namespace berikut:

Namespace datar

Bucket dengan namespace datar menyimpan objek dalam struktur datar tanpa hierarki, yang berarti tidak ada direktori atau folder.

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

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

Namun, karena objek memiliki / dalam namanya, beberapa alat menerapkan 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 bernama folder1, lalu file1.txt akan tunduk pada kebijakan akses yang ditetapkan 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 serta XML API memiliki kemampuan yang memungkinkan Anda mendesain skema penamaan Anda sendiri untuk menyimulasikan folder. Klik tab berikut untuk melihat cara berbagai alat 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 mencapai ilusi hierarki file, 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 akan memperlakukan URL tujuan sebagai folder. Misalnya, pertimbangkan perintah berikut, dengan your-file adalah 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, baik dengan menggunakan flag --recursive atau karakter pengganti seperti **, gcloud CLI akan memperlakukan URL tujuan sebagai folder. Misalnya, pertimbangkan perintah berikut dengan top-dir adalah folder yang berisi file seperti file1 dan file2:

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

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

  3. Jika tidak satu pun aturan ini berlaku, gcloud CLI akan memeriksa objek dalam bucket untuk menentukan apakah URL tujuan berupa 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 diawali dengan abc/. Jika demikian, gcloud CLI akan memperlakukan abc/ sebagai nama folder, dan perintah akan membuat objek abc/your-file dalam 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$ ke akhir nama objek 0 byte, tetapi tidak memerlukan objek penanda tersebut untuk mengimplementasikan perilaku penamaan yang konsisten dengan perintah UNIX.

Selain aturan ini, cara gcloud CLI memperlakukan file sumber bergantung pada apakah Anda menggunakan flag --recursive atau tidak. Jika Anda menggunakan flag, gcloud CLI akan membuat nama objek untuk mencerminkan struktur direktori sumber, dimulai dari titik pemrosesan rekursif. Misalnya, pertimbangkan perintah berikut dengan home/top-dir adalah folder yang berisi file seperti file1 dan sub-dir/file2:

gcloud storage cp home/top-dir gs://your-bucket --recursive

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

Sebaliknya, menyalin tanpa flag --recursive, meskipun beberapa file disalin karena adanya karakter pengganti seperti **, akan menghasilkan objek yang diberi nama oleh komponen jalur akhir file sumber. Misalnya, dengan asumsi lagi bahwa home/top-dir adalah folder yang berisi file seperti file1 dan sub-dir/file2, maka perintahnya:

gcloud storage cp home/top-dir/** gs://your-bucket

membuat objek bernama file1 dan objek bernama file2 di bucket your-bucket.

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 menemukan folder tujuan yang sudah ada, sehingga 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, pada percobaan berikutnya yang berhasil dengan perintah yang sama, gcloud CLI akan membuat objek berikut:

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

Agar gcloud CLI berfungsi secara konsisten di setiap upaya, coba langkah berikut:

  1. Tambahkan garis miring ke 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 cp, kode ini berfungsi secara konsisten terlepas dari ada atau tidaknya subfolder tujuan.

Catatan tambahan

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

  • Saat mendownload ke sistem file lokal, gcloud CLI akan melewati objek yang namanya diakhiri dengan karakter /, karena pembuatan file yang diakhiri dengan / tidak diizinkan di Linux dan macOS.

  • 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://your-bucket/folder/ sebagai objek yang berbeda dengan gs://your-bucket//folder.

REST API

JSON API

Folder tidak ada di JSON API. Anda dapat mempersempit objek yang Anda cantumkan 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 Anda cantumkan 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 simulasi 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 telah menggunakan alat yang membuat objek nol byte sebagai placeholder folder, seperti Konsol Google Cloud, Anda harus menghapus objek nol byte untuk menghapus folder.

Namespace hierarkis

Namespace hierarkis memungkinkan Anda mengatur objek dalam bucket Cloud Storage dalam sistem file seperti hierarki folder. Namespace hierarkis meningkatkan performa dan membantu Anda mengelola data secara efisien. Untuk mempelajari namespace hierarkis lebih lanjut dan kapan harus menggunakannya, lihat Namespace Hierarkis.

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 melakukan hal tersebut secara atomik: hingga upload baru selesai, versi lama objek tersebut ditayangkan kepada pembaca, dan setelah upload menyelesaikan versi baru objek yang ditayangkan kepada pembaca. Satu operasi penggantian menandai akhir dari masa aktif satu objek yang tidak dapat diubah dan awal dari masa aktif objek 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 berikutnya