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

इस दस्तावेज़ में, पुश नोटिफ़िकेशन का इस्तेमाल करने का तरीका बताया गया है. पुश नोटिफ़िकेशन से, संसाधन में बदलाव होने पर आपके ऐप्लिकेशन को सूचना मिलती है.

खास जानकारी

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

पुश नोटिफ़िकेशन का इस्तेमाल करने के लिए, आपको ये दो काम करने होंगे:

  • अपना रिसीविंग यूआरएल या "वेबबुक" कॉलबैक रिसीवर सेट अप करें.

    यह एक एचटीटीपीएस सर्वर है. यह एपीआई सूचना वाले उन मैसेज को मैनेज करता है जो किसी संसाधन में बदलाव होने पर ट्रिगर होते हैं.

  • आपको जिस भी संसाधन एंडपॉइंट पर नज़र रखनी है उसके लिए, एक (सूचना चैनल) सेट अप करें.

    चैनल, सूचना वाले मैसेज के लिए राउटिंग की जानकारी देता है. चैनल सेटअप करने के दौरान, आपको उस यूआरएल की पहचान करनी होगी जहां आपको सूचनाएं चाहिए. जब भी किसी चैनल के संसाधन में बदलाव होता है, तब Google Calendar API, उस यूआरएल पर सूचना वाला मैसेज भेजता है. यह मैसेज, POST अनुरोध के तौर पर भेजा जाता है.

फ़िलहाल, Google Calendar API इन संसाधनों में हुए बदलावों के लिए सूचनाएं पाने की सुविधा देता है: Acl, CalendarList, Events, और Settings.

सूचना के चैनल बनाना

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

स्मार्टवॉच से अनुरोध करना

Google Calendar API के हर ऐसे रिसॉर्स के साथ एक watch तरीका जुड़ा होता है जिसे देखा जा सकता है. यह तरीका, इस फ़ॉर्म में मौजूद यूआरआई पर होता है:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

किसी संसाधन में हुए बदलावों के बारे में सूचनाएं पाने के लिए, सूचना चैनल सेट अप करने के लिए, संसाधन के लिए watch तरीके को POST अनुरोध भेजें.

हर सूचना चैनल, किसी उपयोगकर्ता और किसी संसाधन (या संसाधनों के सेट) से जुड़ा होता है. watch अनुरोध तब तक पूरा नहीं होगा, जब तक मौजूदा उपयोगकर्ता के पास इस संसाधन का मालिकाना हक नहीं है या उसके पास इसे ऐक्सेस करने की अनुमति नहीं है.

उदाहरण

किसी कैलेंडर पर मौजूद इवेंट के कलेक्शन में होने वाले बदलावों को ट्रैक करना:

POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

अनुरोध के मुख्य हिस्से में, अपने चैनल का id, type को web_hook के तौर पर, और address में अपना यूआरएल डालें. आपके पास यह जानकारी देने का विकल्प भी है:

  • चैनल टोकन के तौर पर इस्तेमाल करने के लिए token.
  • आपके अनुरोध किए गए चैनल की सदस्यता खत्म होने का समय, expiration मिलीसेकंड में.

ज़रूरी प्रॉपर्टी

हर watch अनुरोध के साथ, आपको ये फ़ील्ड देने होंगे:

  • id प्रॉपर्टी स्ट्रिंग, जो आपके प्रोजेक्ट में इस नए सूचना चैनल की पहचान करती है. हमारा सुझाव है कि आप यूनिवर्सली यूनीक आइडेंटिफ़ायर (UUID) या इसी तरह की कोई यूनीक स्ट्रिंग इस्तेमाल करें. ज़्यादा से ज़्यादा 64 वर्ण इस्तेमाल किए जा सकते हैं.

    आपने जो आईडी वैल्यू सेट की है वह आपको इस चैनल के लिए मिलने वाले हर सूचना मैसेज के X-Goog-Channel-Id एचटीटीपी हेडर में वापस दिखती है.

  • type प्रॉपर्टी स्ट्रिंग, web_hook वैल्यू पर सेट है.

  • address प्रॉपर्टी स्ट्रिंग को उस यूआरएल पर सेट किया जाता है जो इस सूचना चैनल के लिए सूचनाएं सुनता है और उनका जवाब देता है. यह आपका वेबहुक कॉलबैक यूआरएल है. इसमें एचटीटीपीएस का इस्तेमाल होना चाहिए.

    ध्यान दें कि Google Calendar API, इस एचटीटीपीएस पते पर सूचनाएं सिर्फ़ तब भेज सकता है, जब आपके वेब सर्वर पर मान्य एसएसएल सर्टिफ़िकेट इंस्टॉल किया गया हो. अमान्य सर्टिफ़िकेट में ये शामिल हैं:

    • खुद हस्ताक्षर किए हुए सर्टिफ़िकेट.
    • किसी गैर-भरोसेमंद सोर्स के हस्ताक्षर किए हुए सर्टिफ़िकेट.
    • वे सर्टिफ़िकेट जो निरस्त कर दिए गए हैं.
    • ऐसे सर्टिफ़िकेट जिनका विषय, टारगेट किए गए होस्टनेम से मेल नहीं खाता.

ज़रूरी नहीं है कि ये प्रॉपर्टी मौजूद हों

watch अनुरोध के साथ, इन वैकल्पिक फ़ील्ड की जानकारी भी दी जा सकती है:

  • token प्रॉपर्टी, जो चैनल टोकन के तौर पर इस्तेमाल करने के लिए आर्बिट्ररी स्ट्रिंग वैल्यू तय करती है. सूचना चैनल टोकन का इस्तेमाल कई कामों के लिए किया जा सकता है. उदाहरण के लिए, इस टोकन का इस्तेमाल यह पुष्टि करने के लिए किया जा सकता है कि हर इनकमिंग मैसेज, आपके ऐप्लिकेशन से बनाए गए चैनल के लिए है. इससे यह पक्का किया जा सकता है कि सूचना को स्पूफ़ नहीं किया जा रहा है. इसके अलावा, इस टोकन का इस्तेमाल, चैनल के मकसद के आधार पर मैसेज को आपके ऐप्लिकेशन में सही जगह पर भेजने के लिए भी किया जा सकता है. ज़्यादा से ज़्यादा वर्ण: 256 वर्ण.

    यह टोकन, हर सूचना मैसेज में X-Goog-Channel-Token एचटीटीपी हेडर में शामिल होता है. यह मैसेज, आपका ऐप्लिकेशन इस चैनल के लिए पाता है.

    अगर सूचना चैनल टोकन का इस्तेमाल किया जाता है, तो हमारा सुझाव है कि आप:

    • एक्सटेंसिबल एन्कोडिंग फ़ॉर्मैट का इस्तेमाल करें. जैसे, यूआरएल क्वेरी पैरामीटर. उदाहरण: forwardTo=hr&createdBy=mobile

    • इसमें OAuth टोकन जैसे संवेदनशील डेटा को शामिल न करें.

  • expiration प्रॉपर्टी स्ट्रिंग, तारीख और समय के यूनिक्स टाइमस्टैंप (मिलीसेकंड में) पर सेट की जाती है. यह वह तारीख और समय होता है जब आपको Google Calendar API को इस सूचना चैनल के लिए मैसेज भेजना बंद करना होता है.

    अगर किसी चैनल की समयसीमा खत्म होने वाली है, तो उसे X-Goog-Channel-Expiration एचटीटीपी हेडर की वैल्यू के तौर पर शामिल किया जाता है. यह वैल्यू, हर सूचना वाले मैसेज में होती है. यह मैसेज, आपके ऐप्लिकेशन को इस चैनल के लिए मिलता है. इस वैल्यू को, आसानी से पढ़े जा सकने वाले फ़ॉर्मैट में दिखाया जाता है.

अनुरोध के बारे में ज़्यादा जानकारी के लिए, एपीआई के रेफ़रंस में Acl, CalendarList, Events, और Settings संसाधनों के लिए watch तरीका देखें.

जवाब देखना

अगर watch अनुरोध से सूचना चैनल बन जाता है, तो यह एचटीटीपी 200 OK स्टेटस कोड दिखाता है.

वॉच रिस्पॉन्स के मैसेज बॉडी में, अभी-अभी बनाए गए सूचना चैनल के बारे में जानकारी दी गई है. इसे यहां दिए गए उदाहरण में देखा जा सकता है.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events",
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

जवाब के मुख्य हिस्से में चैनल की जानकारी दी जाती है. जैसे:

  • kind: इससे पता चलता है कि यह एक एपीआई चैनल संसाधन है.
  • id: इस चैनल के लिए आपने जो आईडी दिया है.
  • resourceId: देखे गए संसाधन का आईडी.
  • resourceUri: देखे गए संसाधन का वर्शन के हिसाब से आईडी.
  • token: अनुरोध के मुख्य हिस्से में दिया गया टोकन.
  • expiration: चैनल की सदस्यता खत्म होने का समय, मिलीसेकंड में Unix टाइमस्टैंप के तौर पर.

आपने अनुरोध में जो प्रॉपर्टी भेजी हैं उनके अलावा, जवाब में मिली जानकारी में resourceId और resourceUri भी शामिल हैं. इनसे यह पता चलता है कि इस सूचना चैनल पर कौनसे संसाधन पर नज़र रखी जा रही है.

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

जवाब के बारे में ज़्यादा जानकारी के लिए, एपीआई रेफ़रंस में Acl, CalendarList, Events, और Settings संसाधनों के लिए watch तरीका देखें.

मैसेज सिंक करना

किसी संसाधन पर नज़र रखने के लिए सूचना चैनल बनाने के बाद, Google Calendar API एक sync मैसेज भेजता है. इससे पता चलता है कि सूचनाएं भेजी जा रही हैं. इन मैसेज के लिए, X-Goog-Resource-State एचटीटीपी हेडर की वैल्यू sync है. नेटवर्क टाइमिंग से जुड़ी समस्याओं की वजह से, ऐसा हो सकता है कि आपको sync मैसेज, watch तरीके के जवाब से पहले ही मिल जाए.

sync सूचना को अनदेखा किया जा सकता है. हालांकि, इसका इस्तेमाल भी किया जा सकता है. उदाहरण के लिए, अगर आपको चैनल नहीं रखना है, तो X-Goog-Channel-ID और X-Goog-Resource-ID वैल्यू का इस्तेमाल करके, सूचनाएं पाना बंद किया जा सकता है. इसके अलावा, sync सूचना का इस्तेमाल करके, कुछ इवेंट के लिए तैयारी की जा सकती है.

Google Calendar API, आपके यूआरएल पर sync मैसेज भेजता है. इसका फ़ॉर्मैट यहां दिखाया गया है.

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

सिंक किए गए मैसेज में हमेशा X-Goog-Message-Number एचटीटीपी हेडर की वैल्यू 1 होती है. इस चैनल के लिए, इसके बाद आने वाली हर सूचना में एक ऐसा मैसेज नंबर होता है जो पिछली सूचना के मैसेज नंबर से बड़ा होता है. हालांकि, मैसेज नंबर क्रम से नहीं होंगे.

सूचना के चैनलों को रिन्यू करना

सूचना चैनल के खत्म होने का समय हो सकता है. इसकी वैल्यू, आपके अनुरोध या Google Calendar API की किसी अंदरूनी सीमा या डिफ़ॉल्ट वैल्यू से तय होती है. इनमें से ज़्यादा पाबंदी वाली वैल्यू का इस्तेमाल किया जाता है. अगर चैनल की सदस्यता की समयसीमा खत्म होने वाली है, तो उसकी जानकारी watch तरीके से मिली जानकारी में शामिल की जाती है. यह जानकारी यूनिक्स टाइमस्टैंप (मिलीसेकंड में) के तौर पर शामिल की जाती है. इसके अलावा, हर सूचना वाले मैसेज में समयसीमा खत्म होने की तारीख और समय (इंसान के पढ़ने लायक फ़ॉर्मैट में) शामिल होता है. आपका ऐप्लिकेशन, इस चैनल के लिए X-Goog-Channel-Expiration एचटीटीपी हेडर में यह सूचना वाला मैसेज पाता है.

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

सूचनाएं पाएं

जब भी मॉनिटर की जा रही किसी संसाधन में बदलाव होता है, तब आपके ऐप्लिकेशन को बदलाव के बारे में बताने वाला सूचना मैसेज मिलता है. Google Calendar API, इन मैसेज को एचटीटीपीएस POST अनुरोधों के तौर पर भेजता है. ये अनुरोध, उस यूआरएल पर भेजे जाते हैं जिसे आपने इस सूचना चैनल के लिए address प्रॉपर्टी के तौर पर सेट किया है.

सूचना वाले मैसेज के फ़ॉर्मैट को समझना

सूचना वाले सभी मैसेज में, एचटीटीपी हेडर का एक सेट शामिल होता है. इसमें X-Goog- प्रीफ़िक्स होते हैं. कुछ तरह की सूचनाओं में मैसेज का मुख्य हिस्सा भी शामिल हो सकता है.

हेडर

Google Calendar API, सूचना वाले मैसेज को आपके रिसीविंग यूआरएल पर पोस्ट करता है. इनमें ये एचटीटीपी हेडर शामिल होते हैं:

हेडर ब्यौरा
हमेशा मौजूद
X-Goog-Channel-ID यूयूआईडी या अन्य यूनीक स्ट्रिंग, जिसका इस्तेमाल आपने इस सूचना चैनल की पहचान करने के लिए किया है.
X-Goog-Message-Number पूर्णांक, जो इस सूचना चैनल के लिए इस मैसेज की पहचान करता है. sync मैसेज के लिए, वैल्यू हमेशा 1 होती है. चैनल पर मौजूद हर मैसेज के लिए, मैसेज की संख्या बढ़ती है. हालांकि, यह क्रम से नहीं होती.
X-Goog-Resource-ID यह एक अपारदर्शी वैल्यू है, जो देखे जा रहे संसाधन की पहचान करती है. यह आईडी, एपीआई के सभी वर्शन में एक जैसा रहता है.
X-Goog-Resource-State संसाधन की नई स्थिति, जिसकी वजह से सूचना ट्रिगर हुई. इन वैल्यू का इस्तेमाल किया जा सकता है: sync, exists या not_exists.
X-Goog-Resource-URI यह एपीआई के वर्शन के हिसाब से, मॉनिटर किए जा रहे संसाधन के लिए आइडेंटिफ़ायर होता है.
कभी-कभी मौजूद होता है
X-Goog-Channel-Expiration सूचना चैनल के खत्म होने की तारीख और समय. इसे ऐसे फ़ॉर्मैट में दिखाया जाता है जिसे कोई भी व्यक्ति आसानी से पढ़ सकता है. यह सिर्फ़ तब मौजूद होता है, जब इसे तय किया गया हो.
X-Goog-Channel-Token आपके ऐप्लिकेशन ने सूचना चैनल का यह टोकन सेट किया था. इसका इस्तेमाल सूचना के सोर्स की पुष्टि करने के लिए किया जा सकता है. यह सिर्फ़ तब मौजूद होता है, जब इसे तय किया गया हो.

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

उदाहरण

इवेंट के बदले गए कलेक्शन के लिए सूचना का मैसेज:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events
X-Goog-Resource-State:  exists
X-Goog-Message-Number: 10

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

सफल होने का स्टेटस दिखाने के लिए, इनमें से कोई भी स्टेटस कोड दिखाया जा सकता है: 200, 201, 202, 204 या 102.

अगर आपकी सेवा Google की API क्लाइंट लाइब्रेरी का इस्तेमाल करती है और 500,502, 503 या 504 दिखाती है, तो Google Calendar API, एक्सपोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करता है. वापसी के हर दूसरे स्टेटस कोड को मैसेज डिलीवर न होने की समस्या माना जाता है.

Google Calendar API की सूचनाओं से जुड़े इवेंट के बारे में जानकारी

इस सेक्शन में, उन सूचनाओं के बारे में बताया गया है जो आपको Google Calendar API के साथ पुश नोटिफ़िकेशन इस्तेमाल करने पर मिल सकती हैं.

X-Goog-Resource-State इस पर लागू होता है डिलीवर कब किया गया
sync एसीएल, कैलेंडर की सूचियां, इवेंट, सेटिंग. नया चैनल बना दिया गया है. आपको इस सुविधा के लिए सूचनाएं मिलनी शुरू हो जाएंगी.
exists एसीएल, कैलेंडर की सूचियां, इवेंट, सेटिंग. किसी संसाधन में बदलाव हुआ है. संसाधन में ये बदलाव किए जा सकते हैं: नया संसाधन बनाना, मौजूदा संसाधन में बदलाव करना या उसे मिटाना.

सूचनाएं पाने की सुविधा बंद करें

expiration प्रॉपर्टी से यह कंट्रोल किया जाता है कि सूचनाएं अपने-आप कब बंद होंगी. आपके पास किसी चैनल की सदस्यता खत्म होने से पहले, उसकी सूचनाएं पाने की सुविधा बंद करने का विकल्प होता है. इसके लिए, आपको नीचे दिए गए यूआरआई पर stop तरीके का इस्तेमाल करना होगा:

https://www.googleapis.com/calendar/v3/channels/stop

इस तरीके के लिए, आपको कम से कम चैनल की id और resourceId प्रॉपर्टी देनी होंगी. यहां दिए गए उदाहरण में, इन प्रॉपर्टी को दिखाया गया है. ध्यान दें कि अगर Google Calendar API में कई तरह के संसाधन हैं जिनमें watch तरीके हैं, तो सिर्फ़ एक stop तरीका होता है.

चैनल को सिर्फ़ वे उपयोगकर्ता बंद कर सकते हैं जिनके पास इसकी अनुमति है. खास तौर पर:

  • अगर चैनल को किसी सामान्य उपयोगकर्ता खाते से बनाया गया था, तो उसे सिर्फ़ वही उपयोगकर्ता बंद कर सकता है जिसने उसे बनाया था. साथ ही, वह उपयोगकर्ता उसी क्लाइंट से होना चाहिए जिसकी पहचान OAuth 2.0 क्लाइंट आईडी से की गई है. यह आईडी, ऑथराइज़ेशन टोकन से मिलता है.
  • अगर चैनल को किसी सेवा खाते से बनाया गया है, तो उसी क्लाइंट का कोई भी उपयोगकर्ता चैनल को बंद कर सकता है.

यहां दिए गए कोड सैंपल में, सूचनाएं पाने की सुविधा बंद करने का तरीका बताया गया है:

POST https://www.googleapis.com/calendar/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}