Gmail API में पुश नोटिफ़िकेशन कॉन्फ़िगर करना

इस दस्तावेज़ में, Gmail API में पुश नोटिफ़िकेशन मैनेज करने का तरीका बताया गया है.

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

ध्यान दें: उपयोगकर्ता के मालिकाना हक वाले डिवाइसों (जैसे, इंस्टॉल किए गए ऐप्लिकेशन, फ़ोन या टैबलेट या ब्राउज़र) पर सूचनाएं पाने के लिए, अपडेट पाने का सबसे सही तरीका अब भी पोल पर आधारित 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 Cloud Console में आपके प्रोजेक्ट के लिए दिया गया प्रोजेक्ट आईडी है.

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

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

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

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

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

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

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 से पहले बदलावों को प्रोसेस करना है, तो क्लाइंट को Gmail API के साथ सिंक करना लेख पढ़ें.

इसके अलावा, watch कॉल पूरा होने पर, आपके Cloud Pub/Sub विषय को तुरंत एक सूचना भेजी जाती है.

अगर आपको watch कॉल से कोई गड़बड़ी मिलती है, तो जानकारी में समस्या की वजह बताई जानी चाहिए. आम तौर पर, यह Cloud Pub/Sub विषय और सदस्यता के सेटअप से जुड़ी समस्या होती है. Cloud Pub/Sub के दस्तावेज़ देखें. इससे आपको यह पुष्टि करने में मदद मिलेगी कि सेटअप सही है. साथ ही, इससे आपको विषय और सदस्यता से जुड़ी समस्याओं को डीबग करने में भी मदद मिलेगी.

मेलबॉक्स की निगरानी करने की सुविधा को रिन्यू करना

आपको हर सात दिनों में कम से कम एक बार watch को कॉल करना होगा. ऐसा न करने पर, आपको उपयोगकर्ता के लिए अपडेट मिलना बंद हो जाएंगे. हमारा सुझाव है कि आप दिन में एक बार watch पर कॉल करें. watch तरीके के जवाब में, expiration फ़ील्ड भी होता है. इसमें 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": "[e-mail]", "historyId": "9876543210"}

इसके बाद, history.list तरीके का इस्तेमाल करके, उपयोगकर्ता के लिए बदलाव की जानकारी पाई जा सकती है. ऐसा इसलिए, क्योंकि उपयोगकर्ता के आखिरी बार इस्तेमाल किए गए historyId के बाद से बदलाव की जानकारी उपलब्ध होती है. इसके बारे में क्लाइंट को Gmail API के साथ सिंक करना लेख में बताया गया है.

उदाहरण के लिए, history.list तरीके का इस्तेमाल करके, उन बदलावों की पहचान करें जो आपके शुरुआती watch अनुरोध और पिछले उदाहरण में शेयर किए गए सूचना मैसेज के मिलने के बीच हुए थे. history.list को startHistoryId के तौर पर 1234567890 पास करें. इसके बाद, आने वाले समय में इस्तेमाल के उदाहरणों के लिए, 9876543210 को आखिरी बार पता चला 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 की भी कुछ सीमाएं हैं. इनके बारे में ज़्यादा जानकारी, कीमत और कोटा से जुड़े दस्तावेज़ में दी गई है.