Notifikasi Push

Ringkasan

Gmail API menyediakan notifikasi push server yang memungkinkan Anda memantau perubahan pada kotak surat Gmail. Anda dapat menggunakan fitur ini untuk meningkatkan performa aplikasi. Hal ini memungkinkan Anda menghilangkan biaya jaringan dan komputasi tambahan yang terkait dengan polling resource untuk menentukan apakah resource tersebut telah berubah. Setiap kali kotak surat berubah, Gmail API akan memberi tahu aplikasi server backend Anda.

Penyiapan Cloud Pub/Sub Awal

Gmail API menggunakan Cloud Pub/Sub API untuk mengirimkan notifikasi push. Hal ini memungkinkan notifikasi melalui berbagai metode, termasuk webhook dan polling di satu endpoint langganan.

Prasyarat

Untuk menyelesaikan penyiapan ini, pastikan Anda memenuhi Prasyarat Cloud Pub/Sub, lalu menyiapkan klien Cloud Pub/Sub.

Membuat topik

Dengan menggunakan klien Cloud Pub/Sub, buat topik yang harus digunakan Gmail API untuk mengirim notifikasi. Nama topik dapat berupa nama apa pun yang Anda pilih di project Anda (yaitu cocok dengan projects/myproject/topics/*, dengan myproject adalah Project ID yang tercantum untuk project Anda di Konsol Developer Google).

Membuat langganan

Ikuti Panduan Pelanggan Cloud Pub/Sub untuk menyiapkan langganan ke topik yang Anda buat. Konfigurasi jenis langganan menjadi webhook push (yaitu callback HTTP POST) atau pull (yaitu dimulai oleh aplikasi Anda). Dengan cara ini, aplikasi Anda akan menerima notifikasi untuk pembaruan.

Memberikan hak publikasi atas topik Anda

Cloud Pub/Sub mengharuskan Anda memberikan hak istimewa kepada Gmail untuk memublikasikan notifikasi ke topik Anda.

Untuk melakukannya, Anda harus memberikan hak istimewa publish ke gmail-api-push@system.gserviceaccount.com. Anda dapat melakukannya menggunakan antarmuka izin Konsol Developer Cloud Pub/Sub dengan mengikuti petunjuk kontrol akses tingkat resource.

Mendapatkan info terbaru kotak surat Gmail

Setelah penyiapan awal Cloud Pub/Sub selesai, konfigurasi akun Gmail untuk mengirim notifikasi untuk pembaruan kotak surat.

Permintaan tonton

Untuk mengonfigurasi akun Gmail agar mengirim notifikasi ke topik Cloud Pub/Sub Anda, cukup gunakan klien Gmail API Anda untuk memanggil watch di kotak surat pengguna Gmail seperti panggilan Gmail API lainnya. Untuk melakukannya, berikan nama topik yang dibuat di atas dan opsi lainnya dalam permintaan watch Anda, seperti labels untuk memfilter. Misalnya, agar diberi tahu setiap kali ada perubahan pada Kotak Masuk:

Protokol

POST "https://www.googleapis.com/gmail/v1/users/me/watch"
Content-type: application/json

{
  topicName: "projects/myproject/topics/mytopic",
  labelIds: ["INBOX"],
  labelFilterBehavior: "INCLUDE",
}

Python

request = {
  'labelIds': ['INBOX'],
  'topicName': 'projects/myproject/topics/mytopic',
  'labelFilterBehavior': 'INCLUDE'
}
gmail.users().watch(userId='me', body=request).execute()

Respons smartwatch

Jika permintaan watch berhasil, Anda akan menerima respons seperti:

{
  historyId: 1234567890
  expiration: 1431990098200
}

dengan kotak surat saat ini historyId untuk pengguna. Semua perubahan setelah itu historyId akan diberi tahu kepada klien Anda. Jika Anda perlu memproses perubahan sebelum historyId ini, lihat panduan sinkronisasi.

Selain itu, panggilan watch yang berhasil akan menyebabkan notifikasi segera dikirim ke topik Cloud Pub/Sub Anda.

Jika Anda menerima error dari panggilan watch, detailnya akan menjelaskan sumber masalah, yang biasanya terkait dengan penyiapan topik dan langganan Cloud Pub/Sub. Lihat dokumentasi Cloud Pub/Sub untuk mengonfirmasi bahwa penyiapan sudah benar dan untuk mendapatkan bantuan terkait masalah topik dan langganan.

Memperpanjang masa berlaku smartwatch kotak surat

Anda harus memanggil ulang watch setidaknya setiap 7 hari atau Anda akan berhenti menerima update untuk pengguna. Sebaiknya panggil watch sekali per hari. Respons watch juga memiliki kolom masa berlaku dengan stempel waktu untuk masa berlaku watch.

Menerima notifikasi

Setiap kali ada pembaruan kotak surat yang cocok dengan watch Anda, aplikasi Anda akan menerima pesan notifikasi yang menjelaskan perubahan tersebut.

Jika Anda telah mengonfigurasi langganan push, notifikasi webhook ke server Anda akan sesuai dengan PubsubMessage:

POST https://yourserver.example.com/yourUrl
Content-type: application/json

{
  message:
  {
    // This is the actual notification data, as base64url-encoded JSON.
    data: "eyJlbWFpbEFkZHJlc3MiOiAidXNlckBleGFtcGxlLmNvbSIsICJoaXN0b3J5SWQiOiAiMTIzNDU2Nzg5MCJ9",

    // This is a Cloud Pub/Sub message id, unrelated to Gmail messages.
    "messageId": "2070443601311540",

    // This is the publish time of the message.
    "publishTime": "2021-02-26T19:13:55.749Z",
  }

  subscription: "projects/myproject/subscriptions/mysubscription"
}

Isi HTTP POST adalah JSON dan payload notifikasi Gmail sebenarnya ada di kolom message.data. Kolom message.data tersebut adalah string berenkode base64url yang didekode ke objek JSON yang berisi alamat email dan ID histori kotak surat baru untuk pengguna:

{"emailAddress": "user@example.com", "historyId": "9876543210"}

Anda kemudian dapat menggunakan history.list untuk mendapatkan detail perubahan pengguna sejak last known historyId-nya, sesuai dengan panduan sinkronisasi.

Misalnya, untuk menggunakan history.list guna mengidentifikasi perubahan yang terjadi antara panggilan watch awal dan penerimaan pesan notifikasi yang dibagikan dalam contoh sebelumnya, teruskan 1234567890 sebagai startHistoryId ke history.list. Setelah itu,9876543210 dapat dipertahankan sebagai historyId terakhir yang diketahui untuk kasus penggunaan mendatang.

Jika Anda telah mengonfigurasi langganan pull, lihat contoh kode di Panduan Pull Pelanggan Cloud Pub/Sub untuk mengetahui detail selengkapnya tentang cara menerima pesan.

Merespons notifikasi

Semua notifikasi harus dikonfirmasi. Jika Anda menggunakan pengiriman push webhook, maka merespons dengan berhasil (misalnya, HTTP 200) akan mengonfirmasi notifikasi.

Jika menggunakan pengiriman pull (REST Pull, RPC Pull , atau RPC StreamingPull) , Anda harus menindaklanjutinya dengan panggilan konfirmasi (REST atau RPC). Lihat contoh kode dalam Panduan Pull Pelanggan Cloud Pub/Sub untuk mengetahui detail selengkapnya tentang cara mengonfirmasi pesan secara asinkron atau sinkron menggunakan library klien berbasis RPC resmi.

Jika notifikasi tidak dikonfirmasi (misalnya, callback webhook Anda menampilkan error atau waktu tunggu habis), Cloud Pub/Sub akan mencoba lagi notifikasi tersebut di lain waktu.

Menghentikan update kotak surat

Untuk berhenti menerima update di kotak surat, panggil stop dan semua notifikasi baru akan berhenti dalam beberapa menit.

Batasan

Frekuensi notifikasi maksimum

Setiap pengguna Gmail yang dipantau memiliki kecepatan notifikasi maksimum 1 peristiwa/detik. Notifikasi pengguna di atas kecepatan tersebut akan dihentikan. Berhati-hatilah saat menangani notifikasi agar tidak memicu notifikasi lain, dan dengan demikian memulai loop notifikasi.

Keandalan

Biasanya semua notifikasi akan dikirimkan dengan andal dalam beberapa detik; namun dalam beberapa situasi ekstrem, notifikasi mungkin tertunda atau tidak terkirim. Pastikan untuk menangani kemungkinan ini dengan baik, sehingga aplikasi tetap disinkronkan meskipun tidak ada pesan push yang diterima. Misalnya, kembali ke memanggil history.list secara berkala setelah periode tanpa notifikasi untuk pengguna.

Batasan Cloud Pub/Sub

Cloud Pub/Sub API juga memiliki batasan sendiri, yang dijelaskan secara khusus dalam dokumentasi harga dan kuota-nya.