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:
Folder terkelola adalah resource Cloud Storage yang menyediakan akses diperluas ke grup objek dengan awalan nama bersama.
Alat seperti Google Cloud Console dan Google Cloud CLI menggunakan karakter garis miring (
/
) sebagai pemisah untuk menyimulasikan folder dalam bucket.
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:
- Di Konsol Google Cloud, buka halaman Buckets Cloud Storage.
Buka bucket.
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:
Jika URL tujuan diakhiri dengan karakter
/
, perintah gcloud CLI memperlakukan URL tujuan sebagai folder. Misalnya, pertimbangkan perintah berikut, denganyour-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 bucketyour-bucket
.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 sepertifile1
danfile2
:gcloud storage cp your-dir gs://your-bucket/abc --recursive
Sebagai hasil dari perintah ini, Cloud Storage membuat objek
abc/your-dir/file1
danabc/your-dir/file2
di bucketyour-bucket
.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 diyour-bucket
yang jalurnya dimulai denganabc/
. Jika demikian, gcloud CLI memperlakukanabc/
sebagai nama folder, dan perintah tersebut akan membuat objekabc/your-file
di bucketyour-bucket
. Jika tidak, gcloud CLI akan membuat objekabc
diyour-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:
Tambahkan garis miring di akhir URL tujuan agar gcloud CLI selalu memperlakukannya sebagai folder.
Gunakan
gcloud storage rsync
. Karenarsync
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 menafsirkangs://my-bucket/folder/
sebagai objek yang berbeda dengangs://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
- Mengupload dan mendownload objek.
- Memindahkan objek yang sudah ada.
- Pelajari bucket, yang merupakan container untuk objek.
- Pelajari folder terkelola.