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

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

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

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

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

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

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

इसके लिए, gmail-api-push@system.gserviceaccount.com को 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"
}

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 के साथ सिंक करना लेख पढ़ें.

इसके अलावा, 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": "user@example.com", "historyId": "9876543210"}

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

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

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

सूचनाओं का उत्तर दें

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

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

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

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

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

सीमाएं

सर्वर पुश नोटिफ़िकेशन का इस्तेमाल करने की ये सीमाएं हैं:

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

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

विश्वसनीयता

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

Cloud Pub/Sub से जुड़ी सीमाएं

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