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

खास जानकारी

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 को अपने विषय पर सूचनाएं पब्लिश करने की अनुमतियां दें.

ऐसा करने के लिए, आपको [e-mail] को publish की अनुमतियां देनी होंगी. ऐसा करने के लिए, रिसॉर्स-लेवल के ऐक्सेस कंट्रोल के निर्देशों का पालन करते हुए, Cloud Pub/Sub डेवलपर कंसोल के अनुमतियों वाले इंटरफ़ेस का इस्तेमाल करें.

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

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

वीडियो देखने का अनुरोध

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

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

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

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

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

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

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

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

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

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

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

सीमाएं

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

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

विश्वसनीयता

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

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

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