खास जानकारी
Gmail API, सर्वर पुश नोटिफ़िकेशन उपलब्ध कराता है, जिनसे आप Gmail मेलबॉक्स में होने वाले बदलावों को देख सकते हैं. इस सुविधा का उपयोग करके आप अपने ऐप्लिकेशन की परफ़ॉर्मेंस बेहतर बना सकते हैं. इसकी मदद से, पोलिंग रिसॉर्स में हुए अतिरिक्त नेटवर्क और वहां लगने वाले शुल्क का हिसाब लगाया जा सकता है, ताकि यह पता लगाया जा सके कि वे बदले गए हैं या नहीं. मेलबॉक्स में बदलाव होने पर, Gmail API आपके बैकएंड सर्वर ऐप्लिकेशन को सूचना देता है.
Cloud Pub/Sub का शुरुआती सेटअप
Gmail API पुश नोटिफ़िकेशन डिलीवर करने के लिए, Cloud Pub/Sub API का इस्तेमाल करता है. इससे अलग-अलग तरीकों से सूचना भेजी जा सकती है. जैसे, वेबहुक और एक ही सदस्यता एंडपॉइंट पर पोलिंग.
ज़रूरी शर्तें
इस सेटअप की बाकी प्रक्रिया को पूरा करने के लिए, पक्का करें कि आपने Cloud Pub/Sub की ज़रूरी शर्तें पूरी कर ली हैं. इसके बाद, Cloud Pub/Sub क्लाइंट सेट अप करें.
कोई विषय बनाएं
अपने Cloud Pub/Sub क्लाइंट का इस्तेमाल करके, ऐसा विषय बनाएं
जिस पर Gmail API
सूचना भेज सके. विषय का नाम कोई भी ऐसा नाम हो सकता है जिसे आपने प्रोजेक्ट में चुना हो. जैसे, projects/myproject/topics/*
से मेल खाता हो, जहां myproject
, Google Developers Console में आपके प्रोजेक्ट के लिए मौजूद प्रोजेक्ट आईडी है.
हमारा सुझाव है कि अपने ऐप्लिकेशन के लिए, सभी Gmail API पुश नोटिफ़िकेशन के लिए एक ही विषय का इस्तेमाल करें. ऐसा विषयों की संख्या पर Cloud Pub/Sub की सीमाओं को ध्यान में रखते हुए किया जाता है.
सदस्यता बनाना
आपने जो विषय बनाया है उसकी सदस्यता सेट अप करने के लिए, Cloud Pub/Sub की सदस्यता गाइड देखें. सदस्यता के टाइप को वेबहुक पुश (जैसे कि एचटीटीपी पोस्ट कॉलबैक) या पुल (यानी आपके ऐप्लिकेशन से शुरू किया गया) होने के लिए कॉन्फ़िगर करें. इस तरह से आपके ऐप्लिकेशन को अपडेट के लिए सूचनाएं मिलेंगी.
अपने विषय को पब्लिश करने का अधिकार दें
Cloud Pub/Sub के लिए ज़रूरी है कि आप अपने विषय से जुड़ी सूचनाएं पब्लिश करने के लिए, Gmail के खास अधिकार दें.
ऐसा करने के लिए, आपको
gmail-api-push@system.gserviceaccount.com
को publish
का खास अधिकार देना होगा. ऐसा करने के लिए,
Cloud Pub/Sub डेवलपर कंसोल के अनुमतियां इंटरफ़ेस का इस्तेमाल करें.
इसके लिए, संसाधन-लेवल पर ऐक्सेस कंट्रोल से जुड़े निर्देशों का पालन करें.
Gmail मेलबॉक्स अपडेट पाएं
Cloud Pub/Sub का शुरुआती सेटअप पूरा होने के बाद, Gmail खातों को कॉन्फ़िगर करें, ताकि मेलबॉक्स अपडेट की सूचनाएं भेजी जा सकें.
वीडियो देखने का अनुरोध
अपने Cloud Pub/Sub विषय पर सूचनाएं भेजने के लिए, Gmail खाते कॉन्फ़िगर करें. इसके लिए, अपने Gmail API क्लाइंट का इस्तेमाल करें और
watch
Gmail उपयोगकर्ता के मेलबॉक्स पर कॉल करें. यह कॉल उसी तरह किया जाता है जैसे किसी दूसरे Gmail API कॉल से किया जाता है.
ऐसा करने के लिए, ऊपर बनाए गए विषय का नाम और अपने watch
अनुरोध में बताया गया कोई दूसरा विकल्प दें. जैसे, labels
फ़िल्टर करने के लिए. उदाहरण के लिए, इनबॉक्स में कोई बदलाव किए जाने पर उसकी सूचना पाने के लिए:
प्रोटोकॉल
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()
जवाब देखें
अगर watch
का अनुरोध पूरा हो जाता है,
तो आपको इस तरह का जवाब मिलेगा:
{
historyId: 1234567890
expiration: 1431990098200
}
उपयोगकर्ता के लिए मौजूदा मेलबॉक्स historyId
के साथ. इसके बाद होने वाले सभी बदलावों की सूचना,
historyId
आपके क्लाइंट को दी जाएगी. अगर आपको इस historyId
से पहले के बदलावों को प्रोसेस करना है, तो सिंक करने की गाइड देखें.
इसके अलावा, watch
कॉल पूरे होने पर, आपके Cloud Pub/Sub विषय पर तुरंत एक सूचना भेजी जानी चाहिए.
अगर आपको watch
कॉल से कोई गड़बड़ी मिलती है, तो जानकारी में समस्या की वजह बताई जानी चाहिए. आम तौर पर, इसमें Cloud Pub/Sub विषय और सदस्यता के सेटअप में समस्या होती है. Cloud Pub/Sub दस्तावेज़ देखें और पुष्टि करें कि सेटअप सही है या नहीं. साथ ही, डीबग करने के विषय और सदस्यता से जुड़ी समस्याओं के लिए मदद पाएं.
मेलबॉक्स स्मार्टवॉच को रिन्यू किया जा रहा है
आपको watch
को कम से कम हर सात दिन में एक बार कॉल करना होगा. ऐसा न करने पर, आपको उपयोगकर्ता के अपडेट मिलने बंद हो जाएंगे. हमारा सुझाव है कि
watch
को हर दिन एक बार कॉल करें. watch
रिस्पॉन्स में, खत्म होने की तारीख वाला फ़ील्ड भी होता है, जिसमें watch
की समयसीमा खत्म होने का टाइमस्टैंप होता है.
सूचनाएं मिल रही हैं
जब भी कोई ऐसा मेलबॉक्स अपडेट होगा जो आपके watch
से मेल खाता है, तो आपके ऐप्लिकेशन को
बदलाव का ब्यौरा देने वाला सूचना मैसेज मिलेगा.
अगर आपने कोई पुश सदस्यता कॉन्फ़िगर की है, तो आपके सर्वर पर
वेबहुक सूचना,
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"
}
एचटीटीपी POST का मुख्य हिस्सा JSON है और Gmail की सूचना का असल पेलोड, message.data
फ़ील्ड में है. यह message.data
फ़ील्ड, base64url-एन्कोडेड स्ट्रिंग है
{"emailAddress": "user@example.com", "historyId": "9876543210"}
इसके बाद, history.list
का इस्तेमाल करके, उपयोगकर्ता के पिछली बार पता इतिहास आईडी से हुए बदलावों की जानकारी पाएं. यह जानकारी, सिंक गाइड के मुताबिक दी गई है.
इसके बजाय, अगर आपने पुल की सदस्यता कॉन्फ़िगर की है, तो मैसेज पाने के बारे में ज़्यादा जानकारी के लिए, Cloud Pub/Sub की सदस्यता लेने वाली पुल गाइड में दिए गए कोड सैंपल देखें.
सूचनाओं का जवाब दिया जा रहा है
सभी सूचनाओं को स्वीकार करना ज़रूरी है. अगर वेबहुक पुश डिलीवरी का इस्तेमाल किया जाता है, तो सही तरीके से (जैसे, एचटीटीपी 200) जवाब देने पर सूचना स्वीकार की जाएगी.
अगर पुल डिलीवरी (REST पुल, RPC पुल या RPC StreamingPull) का इस्तेमाल किया जा रहा है, तो आपको स्वीकार करने वाला कॉल (REST या RPC) करना होगा. Cloud Pub/Sub सदस्यता पुल गाइड में दिए गए कोड सैंपल देखें. यहां आरपीसी की आधिकारिक क्लाइंट लाइब्रेरी का इस्तेमाल करके, मैसेज को एसिंक्रोनस या सिंक्रोनस के तौर पर स्वीकार करने के बारे में ज़्यादा जानकारी मिलती है.
अगर आपने सूचनाओं को स्वीकार नहीं किया है (जैसे कि वेबहुक कॉलबैक के लिए कोई गड़बड़ी दिखती है या समय खत्म हो जाता है), तो Cloud Pub/Sub, सूचना पाने की फिर से कोशिश करेगा.
मेलबॉक्स अपडेट रोके जा रहे हैं
मेलबॉक्स पर अपडेट पाना बंद करने के लिए, stop
पर कॉल करें और सभी नई सूचनाएं
कुछ मिनट में बंद हो जाएंगी.
सीमाएं
सूचना मिलने की ज़्यादा से ज़्यादा दर
देखे जा रहे हर Gmail उपयोगकर्ता के लिए, सूचना मिलने की ज़्यादा से ज़्यादा दर एक इवेंट/सेकंड है. अगर इससे ज़्यादा उपयोगकर्ता सूचनाएं नहीं भेजी जाती हैं, तो सूचना नहीं दी जाएगी. सूचनाओं पर काम करते समय सावधानी बरतें, ताकि कोई और सूचना ट्रिगर न हो. इससे सूचना लूप में चलाना शुरू करें.
विश्वसनीयता
आम तौर पर, सभी सूचनाएं कुछ ही सेकंड में डिलीवर हो जानी चाहिए. हालांकि, कुछ खास स्थितियों में, सूचनाएं मिलने में देरी हो सकती है या उन्हें हटा दिया जा सकता है.
इस संभावना को अच्छी तरह से हैंडल करना न भूलें, ताकि कोई पुश मैसेज न मिलने पर भी ऐप्लिकेशन सिंक हो. उदाहरण के लिए, किसी उपयोगकर्ता को कोई सूचना न दिए जाने के बाद, समय-समय पर कॉल history.list
करना.
Cloud Pub/Sub की सीमाएं
Cloud Pub/Sub API की अपनी सीमाएं भी होती हैं. खास तौर पर, pricing और quotas के दस्तावेज़ में, इसकी पूरी जानकारी दी जाती है.