पुश नोटिफिकेशन

खास जानकारी

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 में आपके प्रोजेक्ट के लिए दिया गया प्रोजेक्ट आईडी है.

सदस्यता बनाना

आपने जो विषय बनाया है उसकी सदस्यता सेट अप करने के लिए, सदस्यों के लिए Cloud Pub/Sub की गाइड में दिया गया तरीका अपनाएं. सदस्यता के टाइप को वेबहुक पुश (यानी कि एचटीटीपी पोस्ट कॉलबैक) या पुल (यानी कि आपके ऐप्लिकेशन से शुरू किया गया) के तौर पर कॉन्फ़िगर करें. इस तरह, आपके आवेदन को अपडेट के लिए सूचनाएं मिलेंगी.

अपने विषय को पब्लिश करने के अधिकार देना

Cloud Pub/Sub को यह ज़रूरी है कि आप Gmail को अपने विषय पर सूचनाएं पब्लिश करने के अधिकार दें.

इसके लिए, आपको publish को gmail-api-push@system.gserviceaccount.com के लिए अनुमतियां देनी होंगी. इसके लिए, संसाधन-स्तर पर ऐक्सेस कंट्रोल करने के निर्देशों का पालन करते हुए, Cloud Pub/Sub Developer Console के अनुमतियों वाले इंटरफ़ेस का इस्तेमाल करें.

आपके संगठन के डोमेन के हिसाब से शेयर करने की सुविधा के कॉन्फ़िगरेशन की वजह से, आपको पब्लिश करने की अनुमतियां देने में समस्या आ सकती है. इस समस्या को हल करने के लिए, इस सेवा खाते के लिए अपवाद कॉन्फ़िगर करें.

Gmail मेलबॉक्स के अपडेट पाना

Cloud Pub/Sub का शुरुआती सेटअप पूरा होने के बाद, Gmail खातों को कॉन्फ़िगर करें, ताकि वे मेलबॉक्स अपडेट की सूचनाएं भेज सकें.

देखने का अनुरोध

Gmail खातों को कॉन्फ़िगर करके, Cloud Pub/Sub विषय पर सूचनाएं भेजी जा सकती हैं. इसके लिए, Gmail API क्लाइंट का इस्तेमाल करके, Gmail उपयोगकर्ता के मेलबॉक्स पर watch को कॉल करें. यह कॉल, 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"
}

एचटीटीपी पोस्ट का मुख्य हिस्सा JSON में होता है और Gmail की सूचना का असली पेलोड, message.data फ़ील्ड में होता है. यह message.data फ़ील्ड, base64url-कोड में बदली गई स्ट्रिंग है. यह डिकोड होकर एक JSON ऑब्जेक्ट में बदल जाती है. इसमें उपयोगकर्ता का ईमेल पता और नया मेलबॉक्स इतिहास आईडी शामिल होता है:

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

इसके बाद, history.list का इस्तेमाल करके, उपयोगकर्ता के last known historyId के बाद हुए बदलावों की जानकारी पाई जा सकती है. इसके लिए, सिंक करने से जुड़ी गाइड देखें.

उदाहरण के लिए, अगर आपको history.list का इस्तेमाल करके, यह पता लगाना है कि आपके शुरुआती watch कॉल और पिछले उदाहरण में शेयर किए गए सूचना वाले मैसेज के बीच क्या बदलाव हुए हैं, तो history.list को startHistoryId के तौर पर 1234567890 पास करें. इसके बाद,9876543210 को last known historyId के तौर पर सेव किया जा सकता है, ताकि इसे आने वाले समय में इस्तेमाल किया जा सके.

अगर आपने पुल सदस्यता को कॉन्फ़िगर किया है, तो मैसेज पाने के बारे में ज़्यादा जानकारी के लिए, सदस्यों के लिए Cloud Pub/Sub की पुल गाइड में दिए गए कोड के सैंपल देखें.

सूचनाओं का जवाब देना

सभी सूचनाओं को स्वीकार करना ज़रूरी है. अगर वेबहुक पुश डिलीवरी का इस्तेमाल किया जाता है, तो सूचना मिलने की पुष्टि करने के लिए, जवाब देना ज़रूरी है. जैसे, एचटीटीपी 200.

अगर पुल डिलीवरी (REST Pull, RPC Pull या RPC StreamingPull) का इस्तेमाल किया जा रहा है, तो आपको पुष्टि करने के लिए कॉल (REST या RPC) करना होगा. आधिकारिक आरपीसी पर आधारित क्लाइंट लाइब्रेरी का इस्तेमाल करके, मैसेज को एसिंक्रोनस तरीके से या सिंक्रोनस तरीके से स्वीकार करने के बारे में ज़्यादा जानने के लिए, Cloud Pub/Sub के सदस्यों के लिए पुल गाइड में दिए गए कोड के सैंपल देखें.

अगर सूचनाओं को स्वीकार नहीं किया जाता है (उदाहरण के लिए, आपका वेबहुक कॉलबैक गड़बड़ी दिखाता है या टाइम आउट हो जाता है), तो Cloud Pub/Sub बाद में सूचना भेजने की कोशिश करेगा.

मेलबॉक्स के अपडेट पाना बंद करना

किसी मेलबॉक्स पर अपडेट पाना बंद करने के लिए, stop को कॉल करें. इसके बाद, कुछ ही मिनटों में सभी नई सूचनाएं मिलनी बंद हो जाएंगी.

सीमाएं

सूचनाएं भेजने की ज़्यादा से ज़्यादा दर

Gmail का इस्तेमाल करने वाले जिस भी व्यक्ति की गतिविधि पर नज़र रखी जा रही है उसे ज़्यादा से ज़्यादा एक सूचना/सेकंड की दर से सूचनाएं मिल सकती हैं. इस दर से ज़्यादा सूचनाएं मिलने पर उन्हें नहीं भेजा जाएगा. सूचनाओं को मैनेज करते समय सावधानी बरतें, ताकि कोई दूसरी सूचना ट्रिगर न हो और सूचनाओं का लूप शुरू न हो.

विश्वसनीयता

आम तौर पर, सभी सूचनाएं कुछ सेकंड में डिलीवर हो जानी चाहिए. हालांकि, कुछ मामलों में सूचनाएं मिलने में देरी हो सकती है या वे डिलीवर नहीं हो सकती हैं. इस स्थिति को ठीक से हैंडल करें, ताकि पुश मैसेज न मिलने पर भी ऐप्लिकेशन सिंक हो सके. उदाहरण के लिए, किसी उपयोगकर्ता को कुछ समय तक सूचनाएं न मिलने पर, समय-समय पर history.list को कॉल करने की सुविधा पर वापस आएं.

Cloud Pub/Sub की सीमाएं

Cloud Pub/Sub API की भी अपनी सीमाएं हैं. इनके बारे में खास तौर पर, कीमत और कोटा से जुड़े दस्तावेज़ में बताया गया है.