Mengonfigurasi notifikasi push di Gmail API

Dokumen ini menjelaskan cara mengelola notifikasi push di Gmail API.

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

Catatan: Agar notifikasi dapat dikirim ke perangkat milik pengguna (misalnya, aplikasi yang diinstal, perangkat seluler, atau browser), panduan Menyinkronkan klien dengan Gmail API berbasis polling tetap merupakan pendekatan yang direkomendasikan untuk mengambil update.

Penyiapan awal Cloud Pub/Sub

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

Prasyarat

Untuk menyelesaikan penyiapan ini, penuhi prasyarat Cloud Pub/Sub, lalu siapkan 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 (misalnya, cocok dengan projects/myproject/topics/*, dengan myproject adalah Project ID yang tercantum untuk project Anda di konsol Google Cloud).

Membuat langganan

Untuk menyiapkan langganan ke topik yang Anda buat, ikuti panduan jenis langganan Cloud Pub/Sub. Konfigurasi jenis langganan menjadi webhook push (yaitu, callback HTTP POST) atau pull (yaitu, dimulai oleh aplikasi Anda). Berikut cara aplikasi Anda menerima notifikasi untuk update.

Memberikan hak publikasi atas topik Anda

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

Untuk melakukannya, berikan hak istimewa publish kepada [e-mail]. Anda dapat melakukannya menggunakan konsol izin Cloud Pub/Sub di konsol Google Cloud dengan mengikuti petunjuk kontrol akses ini.

Konfigurasi berbagi dengan batasan domain organisasi Anda dapat mencegah Anda memberikan izin publikasi. Untuk mengatasi masalah ini, Anda dapat mengonfigurasi pengecualian untuk akun layanan ini.

Mendapatkan info terbaru kotak surat Gmail

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

Permintaan tonton

Untuk mengonfigurasi akun Gmail agar mengirim notifikasi ke topik Cloud Pub/Sub Anda, gunakan klien Gmail API Anda untuk memanggil metode watch di kotak surat pengguna Gmail. Hal ini serupa dengan panggilan Gmail API lainnya. Berikan nama topik yang Anda buat dan opsi lainnya dalam permintaan watch Anda, seperti labels untuk memfilter. Misalnya, gunakan permintaan berikut untuk diberi tahu setiap kali perubahan dilakukan 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()

Menonton respons

Jika permintaan watch berhasil, Anda akan menerima respons seperti berikut:

{ historyId: 1234567890 expiration: 1431990098200 }

Respons berisi historyId kotak surat saat ini untuk pengguna. Klien Anda menerima notifikasi untuk semua perubahan setelah historyId. Jika Anda perlu memproses perubahan sebelum historyId ini, lihat Menyinkronkan klien dengan Gmail API.

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. Masalah ini 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 dalam men-debug masalah topik dan langganan.

Memperpanjang pemantauan kotak surat

Anda harus memanggil watch setidaknya sekali setiap 7 hari atau Anda akan berhenti menerima pembaruan untuk pengguna. Sebaiknya panggil watch sekali sehari. Respons metode watch juga memiliki kolom expiration dengan stempel waktu untuk masa berlaku watch.

Terima notifikasi

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

Jika Anda 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 adalah string yang dienkode Base64URL yang didekode ke objek JSON yang berisi alamat email dan ID histori kotak surat baru untuk pengguna:

{"emailAddress": "[e-mail]", "historyId": "9876543210"}

Kemudian, Anda dapat menggunakan metode history.list untuk mendapatkan detail perubahan pengguna sejak terakhir diketahui historyId, seperti yang dijelaskan dalam Menyinkronkan klien dengan Gmail API.

Misalnya, gunakan metode history.list untuk mengidentifikasi perubahan yang terjadi antara permintaan watch awal Anda dan penerimaan pesan notifikasi yang dibagikan dalam contoh sebelumnya. Teruskan 1234567890 sebagai startHistoryId ke history.list. Setelah itu, Anda dapat mempertahankan 9876543210 sebagai terakhir diketahui historyId untuk kasus penggunaan mendatang.

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

Menanggapi pemberitahuan

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

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

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

Menghentikan pembaruan kotak surat

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

Batasan

Berikut adalah batasan penggunaan notifikasi push server:

Kecepatan notifikasi maksimum

Setiap pengguna Gmail yang dipantau memiliki kecepatan notifikasi maksimum satu peristiwa per detik. Notifikasi pengguna yang melebihi kecepatan tersebut akan dihentikan. Saat menangani notifikasi, berhati-hatilah agar tidak memicu notifikasi lain, yang dapat memulai loop notifikasi.

Keandalan

Biasanya, semua notifikasi dikirimkan dengan andal dalam beberapa detik; namun, dalam beberapa situasi ekstrem, notifikasi mungkin tertunda atau tidak terkirim. Tangani kemungkinan ini dengan baik sehingga aplikasi tetap disinkronkan meskipun tidak ada pesan push yang diterima. Misalnya, kembali ke pemanggilan metode 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 mendetail dalam dokumentasi harga dan kuota.