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

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

खास जानकारी

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