Notifikasi perubahan objek

Notifikasi perubahan objek dapat digunakan untuk memberi tahu aplikasi saat objek diperbarui atau ditambahkan ke bucket.

Haruskah Anda menggunakan notifikasi perubahan Objek?

Umumnya, Anda tidak boleh menggunakan notifikasi perubahan Objek. Alat yang direkomendasikan untuk menghasilkan notifikasi yang melacak perubahan pada objek di bucket Cloud Storage Anda adalah notifikasi Pub/Sub untuk Cloud Storage, karena lebih cepat, lebih fleksibel, dan lebih mudah disiapkan, dan lebih hemat biaya. Untuk panduan langkah demi langkah dalam menyiapkan notifikasi Pub/Sub untuk Cloud Storage, lihat Mengonfigurasi notifikasi Pub/Sub untuk Cloud Storage.

Cara Kerja notifikasi perubahan Objek

Aplikasi klien dapat mengirim permintaan untuk mengawasi perubahan pada objek dalam bucket tertentu.

Menyelesaikan permintaan mengamati akan membuat saluran notifikasi baru. Saluran notifikasi adalah sarana yang digunakan untuk mengirim pesan notifikasi ke aplikasi yang mengamati bucket. Hanya satu jenis saluran notifikasi, yaitu hook web, yang saat ini didukung.

Setelah saluran notifikasi dimulai, Cloud Storage akan memberi tahu aplikasi setiap kali objek ditambahkan, diperbarui, atau dihapus dari bucket. Misalnya, saat Anda menambahkan gambar baru ke bucket, aplikasi dapat diberi tahu untuk membuat thumbnail.

Detail notifikasi perubahan Objek

Terminologi

Tabel berikut berisi deskripsi beberapa istilah yang digunakan di seluruh dokumentasi notifikasi perubahan Objek:

Masa Berlaku	Deskripsi
URL aplikasi	URL aplikasi Anda. Ini adalah alamat pengiriman notifikasi. Perhatikan bahwa ini harus berupa URL HTTPS; URL HTTP tidak diizinkan.
ID Saluran	ID untuk saluran notifikasi. Harus unik dalam bucket tertentu, yaitu jika ada beberapa saluran notifikasi untuk satu bucket, setiap saluran notifikasi harus memiliki ID saluran yang berbeda. ID ini akan dikirim ke aplikasi Anda bersama dengan setiap pesan notifikasi.
ID Resource	ID buram untuk resource yang sedang dipantau. ID resource diperlukan untuk menghentikan saluran notifikasi. Anda dapat mengambil ID ini dari respons ke permintaan pemantauan atau dari header `X-Goog-Resource-Id` pesan peristiwa notifikasi.
Token Klien	(opsional) Token klien dapat digunakan untuk memvalidasi peristiwa notifikasi. Untuk melakukannya, tetapkan token klien kustom dengan permintaan pemantauan Anda. Pesan notifikasi akan berisi token ini, sehingga Anda dapat memverifikasi bahwa pesan tersebut asli.

Memantau Bucket

Untuk mulai mengamati bucket peristiwa notifikasi perubahan, buat permintaan watchAll. Tindakan ini akan membuat saluran notifikasi yang mengirimkan peristiwa notifikasi ke address yang diberikan untuk bucket tertentu. Saluran notifikasi mencakup token klien kustom dan ID saluran jika ditentukan.

Contoh permintaan POST untuk mengamati bucket:

POST /storage/v1/b/BucketName/o/watch?alt=json HTTP/1.1
Host: storage.googleapis.com
Content-Length: 200
User-Agent: google-api-python-client/1.0
Content-Type: application/json
Authorization: Bearer oauth2_token

{
  "token": "ClientToken",
  "type": "web_hook",
  "id": "ChannelId",
  "address": "ApplicationUrl"
}

Otorisasi Notifikasi

Saat mengamati bucket, saluran notifikasi yang dibuat akan dikaitkan dengan project Konsol Google Cloud dari aplikasi yang memulai permintaan API. Ini berarti, misalnya, jika pengguna memberikan akses ke aplikasi yang terinstal atau aplikasi web melalui alur OAuth2, saluran notifikasi yang dibuat aplikasi tersebut akan dikaitkan dengan project aplikasi tersebut, bukan project yang berisi bucket yang sedang dipantau.

Karena akun layanan terkait dengan project, jika Anda menggunakan akun layanan untuk mengamati bucket, saluran notifikasi akan dibuat di project akun layanan tersebut.

Menghapus Saluran Notifikasi

Untuk menghentikan saluran notifikasi, buat permintaan stop. Tindakan ini akan menghentikan semua peristiwa notifikasi ke pasangan ID resource (resourceId) dan ID saluran (id) yang ditentukan. Saluran aktif tambahan untuk resource yang sama tidak terpengaruh. ID resource dan channel dapat ditemukan dalam respons atas permintaan menonton atau dalam isi pesan peristiwa notifikasi.

Contoh permintaan POST untuk menghentikan saluran:

POST /storage/v1/channels/stop HTTP/1.1
Host: storage.googleapis.com
Content-Length: 200
User-Agent: google-api-python-client/1.0
Content-Type: application/json
Authorization: Bearer oauth2_token

{
  "resourceId": "ResourceId",
  "id": "ChannelId"
}

Jenis Pesan Peristiwa Notifikasi

Sinkronkan

Peristiwa notifikasi dikirim saat saluran notifikasi baru dibuat setelah mengeluarkan permintaan pemantauan. Setelah menerima peristiwa sinkronisasi, semua perubahan berikutnya pada bucket akan dikirim ke URL aplikasi yang dikonfigurasi untuk saluran tersebut.

Notifikasi akan dikirim sebagai permintaan POST ke URL aplikasi yang dikonfigurasi. Tidak ada isi dalam permintaan. Metadata notifikasi sinkronisasi dimuat dalam header permintaan. Berikut adalah contoh permintaan notifikasi sinkronisasi:

POST /ApplicationUrlPath
Accept: */*
Content-Type: application/json; charset="utf-8"
Content_Length: 0
Host: ApplicationUrlHost
X-Goog-Channel-Id: ChannelId
X-Goog-Channel-Token: ClientToken
X-Goog-Resource-Id: ResourceId
X-Goog-Resource-State: sync
X-Goog-Resource-Uri: https://storage.googleapis.com/storage/v1/b/BucketName/o?alt=json

Penambahan, Pembaruan, atau Penghapusan Objek

Peristiwa notifikasi dikirim saat objek baru ditambahkan ke bucket, konten atau metadata objek yang ada telah diubah, atau objek dihapus dari bucket.

Notifikasi akan dikirim sebagai permintaan POST ke URL aplikasi yang dikonfigurasi. Isi permintaan berisi pesan berenkode JSON seperti yang ditampilkan dalam permintaan notifikasi berikut:

POST /ApplicationUrlPath
Accept: */*
Content-Length: 1097
Content-Type: application/json; charset="utf-8"
Host: ApplicationUrlHost
X-Goog-Channel-Id: ChannelId
X-Goog-Channel-Token: ClientToken
X-Goog-Resource-Id: ResourceId
X-Goog-Resource-State: ResourceState
X-Goog-Resource-Uri: https://storage.googleapis.com/storage/v1/b/BucketName/o?alt=json

{
 "kind": "storage#object",
 "id": "BucketName/ObjectName",
 "selfLink": "https://www.googleapis.com/storage/v1/b/BucketName/o/ObjectName",
 "name": "ObjectName",
 "bucket": "BucketName",
 "generation": "1367014943964000",
 "metageneration": "1",
 "contentType": "application/octet-stream",
 "updated": "2013-04-26T22:22:23.832Z",
 "size": "10",
 "md5Hash": "xHZY0QLVuYng2gnOQD90Yw==",
 "mediaLink": "https://content-storage.googleapis.com/storage/v1/b/BucketName/o/ObjectName?generation=1367014943964000&alt=media",
 "owner": {
  "entity": "user-jane@gmail.com"
 },
 "crc32c": "C7+82w==",
 "etag": "COD2jMGv6bYCEAE="
}

dengan ResourceState adalah:

exists - untuk penambahan dan pembaruan objek.
not_exists - untuk penghapusan objek.

dan dengan isi pesan JSON yang berisi representasi objek saat ini seperti yang dijelaskan dalam Deskripsi Resource Objek.

Pengiriman yang Andal

Notifikasi perubahan Objek akan mencoba mengirimkan notifikasi ke aplikasi Anda dengan cara yang dapat diandalkan. Namun, perhatikan bahwa notifikasi dapat tertunda sampai batas waktu yang tidak ditentukan, dan ketepatan waktu tidak dijamin. Karena aplikasi Anda mungkin tidak selalu tersedia, aturan berikut diikuti saat mengirimkan notifikasi:

Jika upaya pengiriman notifikasi gagal, upaya tambahan akan dilakukan. Interval antara upaya pengiriman tambahan ditentukan oleh algoritma backoff eksponensial yang dimulai dengan percobaan ulang 30 detik setelah kegagalan awal. Pengiriman berikutnya dilakukan dengan interval yang meningkat, hingga interval maksimum 90 menit. Perhatikan bahwa interval percobaan ulang berikutnya sedikit diacak, sehingga tidak terjadi pada nilai eksponensial yang tepat. Setelah interval percobaan ulang maksimum selama 90 menit tercapai, percobaan ulang berikutnya akan dilanjutkan setiap 90 menit selama 7 hari. Jika tidak dapat dikirimkan dalam jangka waktu tersebut, notifikasi akan dihapus permanen.
Jika aplikasi Anda tidak dapat dibuka setelah 20 detik atau jika aplikasi Anda merespons dengan salah satu kode respons HTTP berikut, upaya pengiriman notifikasi akan dianggap gagal dan akan dicoba lagi:
- 500 Error Server Internal
- 502 Gateway Buruk
- 503 Layanan Tidak Tersedia
- 504 Waktu Tunggu Gateway
Jika aplikasi Anda merespons dengan salah satu kode respons HTTP berikut, notifikasi akan dianggap berhasil dikirimkan:
- 102 Memproses
- 200 OK
- 201 Dibuat
- 202 Diterima
- 204 Tidak Ada Konten.
Kode respons HTTP lain yang ditampilkan aplikasi akan dianggap sebagai kegagalan permanen dan tidak akan dicoba lagi.

Catatan: Karena mekanisme coba lagi di atas, notifikasi mungkin akan dikirimkan lebih dari sekali. Pastikan aplikasi Anda bersifat idempoten sehubungan dengan pemrosesan notifikasi unik. Anda dapat melakukannya dengan memilih kombinasi header notifikasi untuk membantu mengidentifikasi notifikasi secara unik, termasuk X-Goog-Channel-Id, X-Goog-Resource-Id, X-Goog-Resource-State, X-Goog-Generation, dan X-Goog-Metageneration.

Contoh Aplikasi Klien

Bagian ini menjelaskan cara membuat aplikasi klien App Engine yang memproses peristiwa notifikasi perubahan.

Aplikasi contoh berisi class bernama MainPage. Saat pengguna memperbarui atau menambahkan objek ke bucket, class MainPage akan memproses peristiwa notifikasi. Untuk mempermudah, metode post yang melakukan pemrosesan sebenarnya hanya mencatat pesan ke dalam log saat notifikasi diterima. Anda dapat mengganti kode ini dengan logika pemrosesan yang sebenarnya. Jika Anda belum terbiasa mengembangkan aplikasi App Engine, coba deploy aplikasi contoh atau ikuti tutorial sebelum melanjutkan kueri.

Mengonfigurasi aplikasi.
Buat file konfigurasi app.yaml untuk menentukan aplikasi klien yang menangani peristiwa notifikasi perubahan bucket.

application: APPLICATION
version: 1
runtime: python38
api_version: 1
threadsafe: true

handlers:
- url: /.*
  script: change_notification_client.app

Membuat Aplikasi.
Contoh berikut mengimplementasikan aplikasi klien untuk menangani peristiwa notifikasi perubahan pada bucket. Beri nama change_notification_client.py, lalu deploy aplikasi Anda:

"""Notification handling for Google Cloud Storage."""

import json
import logging

import webapp2

class MainPage(webapp2.RequestHandler):
  """Process notification events."""
  def get(self):
    logging.info("Get request to notification page.")
    self.response.write("Welcome to the notification app.")

  def post(self):  # pylint: disable-msg=C6409
    """Process the notification event.

    This method is invoked when the notification channel is first created with
    a sync event, and then subsequently every time an object is added to the
    bucket, updated (both content and metadata) or removed. It records the
    notification message in the log.
    """

    logging.debug(
        '%s\n\n%s',
        '\n'.join(['%s: %s' % x for x in self.request.headers.iteritems()]),
        self.request.body)

    # The following code is for demonstration. Replace
    # it with your own notification processing code.

    if 'X-Goog-Resource-State' in self.request.headers:
      resource_state = self.request.headers['X-Goog-Resource-State']
      if resource_state == 'sync':
        logging.info('Sync message received.')
      else:
        an_object = json.loads(self.request.body)
        bucket = an_object['bucket']
        object_name = an_object['name']
        logging.info('%s/%s %s', bucket, object_name, resource_state)
    else:
      logging.info("Other post.")

logging.getLogger().setLevel(logging.DEBUG)
app = webapp2.WSGIApplication([('/', MainPage)], debug=True)

Menetapkan izin akses aplikasi ke bucket.
Jika bucket Anda dimiliki oleh akun layanan yang berbeda dengan aplikasi App Engine, beri aplikasi tersebut akses PEMILIK akses ke bucket tersebut.
Mulai pantau bucket untuk menemukan perubahan objek.
Buat saluran notifikasi ke aplikasi Anda dengan mengamati bucket menggunakan permintaan watchAll dengan address URL untuk aplikasi App Engine Anda, misalnya, https://ApplicationId.appspot.com/.
Menguji Aplikasi.
Untuk mengetahui apakah aplikasi berfungsi sesuai harapan, lakukan langkah-langkah berikut:
1. Untuk memastikan bahwa aplikasi telah di-deploy dan berfungsi dengan benar, jalankan perintah curl berikut:
```
curl -X Post https://APPLICATION_ID.appspot.com
```
  Jika Anda menggunakan nama domain sendiri untuk men-deploy aplikasi, gunakan nama domain tersebut, bukan appspot.com, dalam perintah sebelumnya.
2. Buka halaman Logging untuk project Anda. Perbarui daftar pesan yang dicatat dalam log, jika diperlukan. Pastikan pesan log yang dikeluarkan oleh aplikasi telah dicatat dalam log.
3. Tambahkan objek ke bucket. Cloud Storage memberi tahu aplikasi, yang kemudian mencatat pesan.
4. Buka halaman Logging untuk project Anda. Perbarui daftar pesan yang dicatat dalam log, lalu cari pesan untuk salinan objek.
Menghapus saluran notifikasi
Hapus saluran notifikasi dengan menentukan ID saluran dan resource yang ditampilkan saat Anda mengeluarkan perintah notifikasi untuk memantau bucket.