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

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

खास जानकारी

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

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

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

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

  • हर उस रिसॉर्स एंडपॉइंट के लिए एक सूचना चैनल सेट अप करें जिसे आपको देखना है.

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

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

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

पुश नोटिफ़िकेशन का अनुरोध करने के लिए, आपको हर उस संसाधन के लिए सूचना वाला चैनल सेट अप करना होगा जिसे आपको मॉनिटर करना है. सूचना चैनल सेट अप होने के बाद, देखे गए किसी भी संसाधन में बदलाव होने पर, 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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myCalendarChannelDest", // (Optional) Your channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration time.
}

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

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

  • id प्रॉपर्टी स्ट्रिंग, जो आपके प्रोजेक्ट में इस नए सूचना चैनल की खास तौर पर पहचान करती है. हमारा सुझाव है कि आप यूनिवर्सल यूनीक आइडेंटिफ़ायर (यूयूआईडी) या इससे मिलती-जुलती किसी यूनीक स्ट्रिंग का इस्तेमाल करें. ज़्यादा से ज़्यादा 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, इवेंट, और सेटिंग संसाधनों के लिए watch तरीका देखें.

जवाब देखें

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events", // Version-specific ID of the watched resource.
  "token": "target=myApp-myCalendarChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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

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

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

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

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

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 की एपीआई क्लाइंट लाइब्रेरी का इस्तेमाल करती है और 500,502, 503 या 504 दिखाती है, तो Google Calendar API, एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करता है. आइटम लौटाने के हर दूसरे स्टेटस कोड को मैसेज की असफलता माना जाता है.

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

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

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

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

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"
}