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

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

खास जानकारी

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

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

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

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

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

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

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

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

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

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

देखे जा सकने वाले हर Google Calendar API संसाधन से, नीचे दिए गए फ़ॉर्म के यूआरआई में watch तरीका:

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

सूचनाओं का चैनल सेट अप करने के लिए, करते हैं, तो एक POST अनुरोध संसाधन के लिए watch तरीका.

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

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

जवाब देखें

अगर 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 सूचना का चैनल.

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

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

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

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

sync सूचना को अनदेखा करना सुरक्षित है, लेकिन आप उसका इस्तेमाल भी कर सकते हैं. उदाहरण के लिए, अगर आप तय करते हैं कि आपको X-Goog-Channel-ID का इस्तेमाल किया जा सकता है और इस कॉल में X-Goog-Resource-ID की वैल्यू सूचनाएं पाना बंद करने के लिए. Google आपके यूआरएल पैरामीटर को कैसे इस्तेमाल करेगा, यह तय करने के लिए 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 की एपीआई क्लाइंट लाइब्रेरी का इस्तेमाल किया जाता है और Google Calendar API 500,502, 503 या 504 दिखाता है एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करता है. यह माना जाता है कि सामान लौटाने की स्थिति बताने वाले दूसरे हर कोड से, मैसेज नहीं भेजा जा सका.

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 तरीका.

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

  • अगर चैनल किसी सामान्य उपयोगकर्ता खाते से बनाया गया था, तो एक ही क्लाइंट का उपयोगकर्ता (जैसा कि पुष्टि करने के टोकन) के ज़रिए, चैनल बनाने वाले व्यक्ति के पास चैनल को बंद करने का अधिकार होता है.
  • अगर चैनल को सेवा खाते का इस्तेमाल करके बनाया गया था, तो उस चैनल के किसी उपयोगकर्ता ने भी ऐसा किया हो क्लाइंट चैनल को रोक सकता है.

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

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