Notifikasi Pub/Sub untuk Cloud Storage

Penyiapan

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:

  • Cloud Functions: Jika Anda hanya ingin memicu fungsi mandiri yang ringan sebagai respons terhadap peristiwa dan tidak ingin mengelola topik Pub/Sub, gunakan Cloud Functions. Dengan Cloud Functions, Anda dapat menjalankan fungsi C#, Go, Java, Node.js, Python, PHP, dan Ruby saat sebuah objek di bucket Anda berubah. Perlu diperhatikan bahwa bucket Anda harus berada dalam project yang sama dengan Cloud Functions. Lihat tutorial terkait untuk melihat demonstrasi penggunaan Cloud Functions dengan Cloud Storage.

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 notificationConfig setiap 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. Ini meliputi penyalinan atau penulisan ulang 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 permintaan JSON POST notificationConfigs.

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 selanjutnya