Ringkasan
Gmail API menyediakan notifikasi push server yang memungkinkan Anda mengawasi perubahan pada kotak surat Gmail. Anda dapat menggunakan fitur ini untuk meningkatkan performa aplikasi Anda. Hal ini memungkinkan Anda menghilangkan biaya jaringan dan komputasi tambahan yang terkait dengan resource polling 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 mengirim notifikasi push. Hal ini memungkinkan notifikasi melalui berbagai metode termasuk webhook dan polling pada 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 akan dikirimi notifikasi oleh Gmail API. 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 Google Developers Console).
Sebaiknya gunakan satu topik untuk semua notifikasi push Gmail API untuk aplikasi Anda, karena adanya batas Cloud Pub/Sub terkait jumlah topik.
Membuat langganan
Ikuti Panduan Pelanggan Cloud Pub/Sub untuk menyiapkan langganan ke topik yang Anda buat. Konfigurasi jenis langganan agar menjadi push webhook (yaitu callback HTTP POST) atau pull (yang dimulai oleh aplikasi Anda). Ini adalah cara aplikasi Anda akan menerima notifikasi untuk pembaruan.
Memberikan hak publikasi atas topik Anda
Cloud Pub/Sub mengharuskan Anda memberikan hak istimewa Gmail untuk memublikasikan notifikasi ke topik Anda.
Untuk melakukannya, Anda harus memberikan hak istimewa publish
kepada
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 pembaruan kotak surat Gmail
Setelah penyiapan Cloud Pub/Sub awal selesai, konfigurasikan akun Gmail untuk mengirim notifikasi terkait pembaruan kotak surat.
Permintaan tonton
Untuk mengonfigurasi akun Gmail agar mengirim notifikasi ke topik Cloud Pub/Sub Anda,
cukup gunakan klien Gmail API untuk memanggil
watch
di kotak surat pengguna Gmail yang serupa dengan panggilan API Gmail 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 di Kotak Masuk:
Protocol
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()
Lihat respons
Jika permintaan watch
berhasil,
Anda akan menerima respons seperti:
{
historyId: 1234567890
expiration: 1431990098200
}
dengan kotak surat historyId
saat ini 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 harus menjelaskan sumber masalah, biasanya dengan penyiapan topik dan langganan Cloud Pub/Sub. Baca dokumentasi Cloud Pub/Sub untuk mengonfirmasi bahwa penyiapannya sudah benar dan untuk mendapatkan bantuan terkait proses debug topik dan masalah langganan.
Memperpanjang jam tangan kotak surat
Anda harus memanggil kembali watch
setidaknya setiap
7 hari atau Anda akan berhenti menerima info terbaru untuk pengguna. Sebaiknya
panggil watch
sekali sehari. Respons watch
juga memiliki kolom habis masa berlaku
dengan stempel waktu untuk tanggal habis masa berlaku watch
.
Menerima notifikasi
Setiap kali pembaruan kotak surat terjadi yang cocok dengan watch
, 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 yang sebenarnya ada di kolom message.data
. Kolom message.data
tersebut adalah string berenkode base64url yang mendekode 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 bagi pengguna sejakhistoryId terakhir yang diketahui, sesuai dengan panduan sinkronisasi.
Jika Anda telah mengonfigurasi langganan pull, lihat contoh kode di Panduan Pull Pelanggan Cloud Pub/Sub untuk mengetahui detail lebih lanjut tentang penerimaan pesan.
Menanggapi notifikasi
Semua notifikasi harus dikonfirmasi. Jika Anda menggunakan pengiriman push webhook, berarti respons yang berhasil (misalnya HTTP 200) akan mengonfirmasi notifikasi.
Jika menggunakan pengiriman pull (REST Pull, RPC Pull , atau RPC StreamingPull), Anda harus menindaklanjuti dengan panggilan konfirmasi (REST atau RPC). Lihat contoh kode di Panduan Pull Pelanggan Cloud Pub/Sub untuk mengetahui detail selengkapnya tentang cara mengonfirmasi pesan secara asinkron atau sinkron menggunakan library klien resmi berbasis RPC.
Jika notifikasi tidak dikonfirmasi (misalnya, callback webhook Anda menampilkan error atau waktu tunggu habis), Cloud Pub/Sub akan mencoba mengirimkan notifikasi kembali di lain waktu.
Menghentikan pembaruan kotak surat
Untuk berhenti menerima info terbaru di kotak surat, panggil
stop
dan semua notifikasi baru
akan berhenti dalam beberapa menit.
Batasan
Rasio notifikasi maks
Setiap pengguna Gmail yang sedang dipantau memiliki rasio notifikasi maksimum 1 peristiwa/dtk. Setiap notifikasi pengguna di atas frekuensi tersebut akan dihapus. Berhati-hatilah saat menangani notifikasi untuk memastikan tidak memicu notifikasi lain, sehingga memulai loop notifikasi.
Keandalan
Biasanya, semua notifikasi harus dikirim dengan andal dalam beberapa detik;
tetapi dalam beberapa situasi ekstrem, notifikasi mungkin tertunda atau hilang.
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 batasannya sendiri, khususnya yang dijelaskan dalam dokumentasi pricing dan quotasnya.