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. Fitur ini menghilangkan biaya jaringan dan komputasi tambahan untuk sumber daya polling guna menentukan apakah sumber daya tersebut telah berubah. Setiap kali kotak surat berubah, Gmail API akan memberi tahu aplikasi server backend Anda.

Catatan: Untuk notifikasi ke perangkat milik pengguna (misalnya, aplikasi terinstal, perangkat seluler, atau browser), panduan Sinkronkan klien berbasis polling dengan Gmail API masih merupakan pendekatan yang direkomendasikan untuk mengambil update.

Penyiapan awal Cloud Pub/Sub

Gmail API menggunakan Cloud Pub/Sub API untuk mengirimkan push notifikasi. 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 klien Cloud Pub/Sub, buat topik yang akan digunakan Gmail API untuk mengirim notifikasi. Nama topik dapat berupa nama apa pun yang Anda pilih di project Anda (misalnya, yang 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 push webhook (yaitu, callback HTTP POST) atau pull (yaitu, dimulai oleh aplikasi Anda). Dengan cara ini, aplikasi Anda akan 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 ke [e-mail]. Anda dapat melakukannya menggunakan konsol izin Cloud Pub/Sub di konsol Google Cloud dengan mengikuti petunjuk kontrol akses ini.

Konfigurasi berbagi yang dibatasi domain organisasi Anda mungkin mencegah Anda memberikan izin publikasi. Untuk mengatasinya, Anda dapat mengonfigurasi pengecualian untuk akun layanan ini.

Mendapatkan update kotak surat Gmail

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

Memantau permintaan

Untuk mengonfigurasi akun Gmail agar mengirim notifikasi ke topik Cloud Pub/Sub Anda, gunakan klien Gmail API untuk memanggil metode watch di kotak surat pengguna Gmail. Hal ini mirip 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 mendapatkan notifikasi 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()

Memantau 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 akan menerima notifikasi untuk semua perubahan setelah historyId tersebut. Jika Anda perlu me mproses perubahan sebelum historyId, lihat Sinkronkan 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. Hal ini biasanya merupakan masalah pada 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 update untuk pengguna. Sebaiknya panggil watch sekali per hari. Respons metode watch juga memiliki kolom expiration dengan stempel waktu untuk masa berlaku watch.

Menerima notifikasi

Setiap kali update kotak surat terjadi yang cocok dengan watch, 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 bagi pengguna sejak terakhir yang diketahui historyId, seperti yang dijelaskan dalam Sinkronkan klien dengan Gmail API.

Misalnya, gunakan metode history.list untuk mengidentifikasi perubahan yang terjadi antara permintaan watchawal Anda dan penerimaan pesan notifikasi yang dibagikan dalam contoh sebelumnya. Teruskan 1234567890 sebagai startHistoryId ke history.list. Setelah itu, Anda dapat mempertahankan 9876543210 sebagai historyId terakhir yang diketahui untuk kasus penggunaan di masa 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, respons yang berhasil (misalnya, HTTP 200) akan mengonfirmasi notifikasi.

Jika Anda menggunakan pengiriman pull (REST Pull, RPC Pull, atau RPC StreamingPull), Anda harus menindaklanjuti dengan panggilan konfirmasi (REST atau RPC). Lihat contoh kode di panduan langganan pull 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 Anda menampilkan error atau waktu tunggu habis), Cloud Pub/Sub akan mencoba kembali notifikasi tersebut di lain waktu.

Menghentikan update kotak surat

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

Batasan

Berikut adalah batasan saat menggunakan notifikasi push server:

Laju notifikasi maksimum

Setiap pengguna Gmail yang dipantau memiliki laju notifikasi maksimum satu peristiwa per detik. Notifikasi pengguna yang melebihi laju 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 dihentikan. Tangani kemungkinan ini dengan baik sehingga aplikasi tetap disinkronkan meskipun tidak ada pesan push yang diterima. Misalnya, kembali ke panggilan secara berkala history.list metode setelah periode tanpa notifikasi untuk pengguna.

Batasan Cloud Pub/Sub

Cloud Pub/Sub API juga memiliki batasannya sendiri, yang dijelaskan dalam dokumentasi harga dan kuotanya.