Halaman ini menyediakan ringkasan notifikasi Pub/Sub untuk Cloud Storage.
Ringkasan
Notifikasi Pub/Sub mengirimkan informasi tentang perubahan pada objek di bucket Anda ke Pub/Sub, di mana informasi tersebut ditambahkan ke topik Pub/Sub pilihan Anda dalam bentuk pesan. Misalnya, Anda dapat melacak objek yang dibuat dan dihapus di bucket Anda. Setiap notifikasi berisi informasi yang menjelaskan peristiwa yang memicunya dan objek yang berubah.
Anda dapat mengirim notifikasi ke topik Pub/Sub mana pun dalam project apa pun yang izinnya Anda miliki secara memadai. Setelah diterima oleh topik Pub/Sub, pelanggan topik tersebut dapat menerima pesan yang terkait. Lihat Prasyarat untuk mengetahui informasi tentang cara menghubungkan bucket Cloud Storage ke topik Pub/Sub.
Opsi notifikasi lain
Berlangganan notifikasi Pub/Sub adalah cara serbaguna untuk memicu pemberitahuan dan tindakan sebagai respons terhadap perubahan dalam bucket. Opsi berikut juga tersedia:
Fungsi Cloud Run: Jika Anda hanya ingin memicu fungsi mandiri yang ringan sebagai respons terhadap peristiwa dan tidak ingin mengelola topik Pub/Sub, gunakan fungsi Cloud Run. Dengan fungsi Cloud Run, Anda dapat menjalankan fungsi C#, Go, Java, Node.js, Python, PHP, dan Ruby saat sebuah objek di bucket Anda berubah. Perhatikan bahwa bucket Anda harus berada dalam project yang sama dengan fungsi Cloud Run. Lihat tutorial terkait untuk melihat demonstrasi penggunaan fungsi Cloud Run dengan Cloud Storage.
Notifikasi perubahan objek: Notifikasi perubahan objek adalah fitur lama yang terpisah dalam Cloud Storage untuk menghasilkan notifikasi. Fitur ini mengirimkan pesan HTTPS ke aplikasi klien yang telah Anda siapkan secara terpisah. Fitur ini umumnya tidak direkomendasikan, karena notifikasi Pub/Sub lebih murah, lebih mudah digunakan, dan lebih fleksibel.
Konfigurasi notifikasi
Konfigurasi notifikasi adalah aturan yang Anda lampirkan ke bucket yang menentukan:
- Topik dalam Pub/Sub yang menerima notifikasi.
- Peristiwa yang memicu pengiriman notifikasi.
- Informasi yang terdapat dalam notifikasi.
Anda dapat melampirkan beberapa konfigurasi notifikasi ke sebuah bucket. Satu bucket dapat memiliki hingga total 100 konfigurasi notifikasi dan hingga 10 konfigurasi notifikasi yang ditetapkan agar dipicu untuk peristiwa tertentu.
Misalnya, jika Anda memiliki konfigurasi notifikasi yang mengirimkan notifikasi penghapusan ke satu topik Pub/Sub, Anda dapat menambahkan konfigurasi notifikasi kedua ke bucket yang mengirimkan notifikasi penghapusan ke topik lain. Namun, jika Anda mencoba membuat lebih dari 10 konfigurasi notifikasi yang melakukannya, Anda akan menerima error. Selain konfigurasi notifikasi ini, Anda juga dapat membuat konfigurasi notifikasi yang mengirim notifikasi untuk peristiwa lain, seperti pembuatan objek, baik ke topik Pub/Sub yang digunakan oleh notifikasi penghapusan, atau ke topik yang berbeda.
Setiap konfigurasi notifikasi diidentifikasi dengan bilangan bulat. Bilangan bulat ini ditampilkan:
- Saat Anda membuat konfigurasi notifikasi.
- Saat Anda mencantumkan konfigurasi notifikasi yang dilampirkan ke bucket.
- Dalam atribut
notificationConfigsetiap notifikasi yang dipicu oleh konfigurasi notifikasi.
Membuat dan menghapus konfigurasi notifikasi akan menambah jumlah metagenerasi bucket.
Jenis peristiwa
Berikut adalah daftar jenis peristiwa yang didukung oleh Cloud Storage:
| Jenis peristiwa | Deskripsi |
|---|---|
OBJECT_FINALIZE |
Dikirim saat objek baru (atau pembuatan ulang objek yang sudah ada) berhasil dibuat dalam bucket. Hal ini termasuk menyalin, menulis ulang, atau memulihkan objek yang sudah ada. Peristiwa ini tidak akan terpicu oleh upload yang gagal. |
OBJECT_METADATA_UPDATE |
Dikirim saat terjadi perubahan terhadap metadata objek yang ada. |
OBJECT_DELETE |
Dikirim saat sebuah objek telah dihapus secara permanen. Ini mencakup objek yang diganti atau dihapus sebagai bagian dari konfigurasi siklus proses bucket. Ini tidak mencakup objek yang menjadi lama (lihat OBJECT_ARCHIVE) atau upload multibagian yang dibatalkan. |
OBJECT_ARCHIVE |
Hanya dikirim saat bucket telah mengaktifkan pembuatan versi objek. Peristiwa ini menunjukkan bahwa versi aktif sebuah objek telah menjadi versi lama, baik karena versi tersebut secara eksplisit dibuat sebagai versi lama maupun karena digantikan oleh objek yang diupload dengan nama yang sama. |
Untuk peristiwa Cloud Storage lainnya, seperti operasi bucket atau pembacaan objek, Anda dapat mengaktifkan jenis log audit yang sesuai di Cloud Audit Logs dan mengarahkan log audit ke Pub/Sub dengan menggunakan filter.
Mengganti objek
Mengganti objek yang ada dengan nama baru yang sama akan memicu dua peristiwa terpisah: OBJECT_FINALIZE untuk versi baru objek, dan OBJECT_ARCHIVE atau OBJECT_DELETE untuk objek yang diganti. Peristiwa
OBJECT_FINALIZE berisi atribut tambahan overwroteGeneration,
yang memberikan nomor pembuatan objek yang diganti. Peristiwa
OBJECT_ARCHIVE atau OBJECT_DELETE berisi atribut tambahan
overwrittenByGeneration, yang memberikan nomor pembuatan objek
baru.
Format notifikasi
Notifikasi yang dikirim ke topik Pub/Sub terdiri dari dua bagian:
- Atribut: Kumpulan key:value pair yang mendeskripsikan peristiwa.
- Payload: String yang berisi metadata objek yang diubah.
Atribut
Atribut adalah key:value pair yang terdapat dalam semua notifikasi yang dikirim oleh Cloud Storage ke topik Pub/Sub Anda. Notifikasi selalu berisi serangkaian key-value pair berikut, terlepas dari payload notifikasi:
| Nama atribut | Contoh | Deskripsi |
|---|---|---|
| notificationConfig | projects/_/buckets/foo/notificationConfigs/3 |
ID untuk konfigurasi notifikasi yang memicu notifikasi ini. |
| eventType | OBJECT_FINALIZE |
Jenis peristiwa yang baru saja terjadi. Lihat Jenis peristiwa untuk daftar kemungkinan nilai. |
| payloadFormat | JSON_API_V1 |
Format payload objek. Lihat Payload untuk mengetahui daftar kemungkinan nilai. |
| bucketId | foo |
Nama bucket yang berisi objek yang diubah. |
| objectId | bar |
Nama objek yang diubah. |
| objectGeneration | 123456 |
Nomor pembuatan objek yang diubah. |
| eventTime | 2021-01-15T01:30:15.01Z |
Waktu berlangsungnya peristiwa, dinyatakan dalam format RFC 3339. |
Notifikasi terkadang berisi serangkaian key-value pair berikut, terlepas dari payload notifikasi:
| Nama atribut | Contoh | Deskripsi |
|---|---|---|
| overwrittenByGeneration | 107458 |
Nomor pembuatan objek yang menggantikan objek yang terkait dengan notifikasi ini. Atribut ini hanya muncul dalam peristiwa OBJECT_ARCHIVE atau OBJECT_DELETE jika terjadi penggantian. |
| overwroteGeneration | 352947 |
Nomor pembuatan objek yang diganti oleh objek yang terkait dengan notifikasi ini. Atribut ini hanya muncul dalam peristiwa OBJECT_FINALIZE dalam hal penggantian. |
Selain atribut di atas, konfigurasi notifikasi dapat berisi hingga 10 atribut khusus. Atribut khusus ditentukan saat membuat
konfigurasi notifikasi, menggunakan --custom-attributes dalam
perintah gcloud storage, atau objek custom_attributes dalam
isi POST notificationConfigs permintaan JSON.
Payload
Payload adalah string yang berisi metadata objek yang diubah. Saat membuat konfigurasi notifikasi, Anda menentukan jenis payload yang akan disertakan dalam notifikasi yang dipicu oleh konfigurasi tersebut. Anda dapat menentukan jenis payload berikut:
| Jenis payload | Deskripsi |
|---|---|
| TIDAK ADA | Tidak ada payload yang disertakan dengan notifikasi. |
| JSON_API_V1 | Payload akan berupa string UTF-8 yang berisi representasi resource metadata objek. |
Untuk notifikasi OBJECT_DELETE, metadata yang dimuat dalam payload menampilkan metadata objek seperti sebelum penghapusan, bersama dengan properti timeDeleted tambahan. Untuk semua notifikasi lainnya, metadata yang disertakan dalam payload mewakili metadata objek setelah perubahan terjadi.
Misalnya, Anda memiliki konfigurasi notifikasi yang melacak peristiwa OBJECT_METADATA_UPDATE. Jika pengguna mengubah properti contentType sebuah objek dari binary/octet-stream menjadi video/mp4, notifikasi OBJECT_METADATA_UPDATE akan dikirim, dan metadata dalam payload mencakup "contentType":"video/mp4".
Jaminan pengiriman
Ketika Anda menambahkan konfigurasi notifikasi, Cloud Storage mungkin memerlukan waktu hingga 30 detik untuk mulai mengirim notifikasi yang terkait dengannya. Setelah dimulai, Cloud Storage menjamin pengiriman setidaknya satu kali ke Pub/Sub. Pub/Sub juga menawarkan pengiriman minimal satu kali kepada penerima. Artinya, Anda dapat menerima beberapa pesan, dengan beberapa ID, yang mewakili peristiwa Cloud Storage yang sama.
Tidak ada jaminan bahwa notifikasi akan dipublikasikan sesuai pesanan Pub/Sub yang diterima. Jika Anda ingin mengubah objek Cloud Storage berdasarkan notifikasi, sebaiknya gunakan nomor pembuatan dan metagenerasi objek sebagai prasyarat untuk permintaan update Anda.
Jika notifikasi tidak dapat dikirim ke topik Pub/Sub secara konsisten, Cloud Storage dapat menghapus notifikasi tersebut setelah 7 hari. Kegagalan pengiriman dapat terjadi saat topik Pub/Sub tidak ada lagi, Cloud Storage tidak lagi memiliki izin untuk memublikasikan ke topik, atau saat project yang memiliki topik melebihi kuota publikasinya.
Langkah berikutnya
- Konfigurasikan notifikasi Pub/Sub untuk Cloud Storage.
- Pelajari Pub/Sub lebih lanjut.
- Berlangganan bucket untuk menerima notifikasi yang dikirim ke Pub/Sub.
- Gunakan fungsi Cloud Run untuk mengirimkan peristiwa dengan pemicu Cloud Storage.
- Gunakan notifikasi Pub/Sub untuk transfer berbasis peristiwa antara bucket Cloud Storage.