इस दस्तावेज़ में, पुश नोटिफ़िकेशन का इस्तेमाल करने का तरीका बताया गया है. पुश नोटिफ़िकेशन से, संसाधन में बदलाव होने पर आपके ऐप्लिकेशन को सूचना मिलती है.
खास जानकारी
Google Drive API, पुश नोटिफ़िकेशन की सुविधा देता है. इससे संसाधनों में हुए बदलावों पर नज़र रखी जा सकती है. इस सुविधा का इस्तेमाल करके, अपने ऐप्लिकेशन की परफ़ॉर्मेंस को बेहतर बनाया जा सकता है. इससे आपको यह पता लगाने के लिए, नेटवर्क और कंप्यूटिंग की अतिरिक्त लागत को कम करने में मदद मिलती है कि संसाधनों में बदलाव हुआ है या नहीं. जब भी देखी गई किसी संसाधन में बदलाव होता है, तो Google Drive API आपके ऐप्लिकेशन को इसकी सूचना देता है.
पुश नोटिफ़िकेशन का इस्तेमाल करने के लिए, आपको ये दो काम करने होंगे:
जवाब पाने के लिए यूआरएल या "वेबबुक" कॉलबैक रिसीवर सेट अप करें.
यह एक एचटीटीपीएस सर्वर है. यह एपीआई सूचना वाले उन मैसेज को मैनेज करता है जो किसी संसाधन में बदलाव होने पर ट्रिगर होते हैं.
आपको जिस भी संसाधन एंडपॉइंट पर नज़र रखनी है उसके लिए, एक (सूचना चैनल) सेट अप करें.
चैनल, सूचना वाले मैसेज के लिए राउटिंग की जानकारी देता है. चैनल सेटअप करने के दौरान, आपको उस यूआरएल की पहचान करनी होगी जहां आपको सूचनाएं मिलेंगी. जब भी किसी चैनल के संसाधन में बदलाव होता है, तब Google Drive API, उस यूआरएल पर सूचना वाला मैसेज
POST
अनुरोध के तौर पर भेजता है.
फ़िलहाल, Google Drive API, files
और changes
तरीकों में किए गए बदलावों के लिए सूचनाएं पाने की सुविधा देता है.
सूचना के चैनल बनाना
पुश नोटिफ़िकेशन का अनुरोध करने के लिए, आपको उस हर संसाधन के लिए सूचना चैनल सेट अप करना होगा जिसे आपको मॉनिटर करना है. सूचना चैनल सेट अप करने के बाद, Google Drive API आपके ऐप्लिकेशन को सूचना देता है. यह सूचना तब मिलती है, जब निगरानी में रखी गई किसी संसाधन में बदलाव होता है.
स्मार्टवॉच से अनुरोध करना
Google Drive API के हर ऐसे संसाधन के साथ एक watch
तरीका जुड़ा होता है जिसे देखा जा सकता है. इसका यूआरआई इस तरह होता है:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
किसी संसाधन में हुए बदलावों के बारे में सूचनाएं पाने के लिए, सूचना चैनल सेट अप करने के लिए, संसाधन के watch
तरीके को POST
अनुरोध भेजें.
हर सूचना चैनल, किसी उपयोगकर्ता और किसी संसाधन (या संसाधनों के सेट) से जुड़ा होता है. watch
अनुरोध तब तक पूरा नहीं किया जा सकता, जब तक मौजूदा उपयोगकर्ता या सेवा खाते के पास इस संसाधन का मालिकाना हक न हो या उसके पास इसे ऐक्सेस करने की अनुमति न हो.
उदाहरण
यहां दिए गए कोड के सैंपल में, files.watch
तरीके का इस्तेमाल करके, किसी एक files
संसाधन में हुए बदलावों को देखने के लिए, channels
संसाधन का इस्तेमाल करने का तरीका बताया गया है:
POST https://www.googleapis.com/drive/v3/files/fileId/watch Authorization: Bearer CURRENT_USER_AUTH_TOKEN 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-myFilesChannelDest", // (Optional) Your files channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time. }
यहां दिए गए कोड के सैंपल में, changes.watch
तरीके का इस्तेमाल करके, सभी changes
के लिए channels
संसाधन का इस्तेमाल करने का तरीका बताया गया है:
POST https://www.googleapis.com/drive/v3/changes/watch Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time. }
ज़रूरी प्रॉपर्टी
हर watch
अनुरोध के साथ, आपको ये फ़ील्ड देने होंगे:
-
id
प्रॉपर्टी स्ट्रिंग, जो आपके प्रोजेक्ट में इस नए सूचना चैनल की पहचान करती है. हमारा सुझाव है कि आप यूनीवर्सली यूनीक आइडेंटिफ़ायर (UUID) या इसी तरह की कोई यूनीक स्ट्रिंग इस्तेमाल करें. ज़्यादा से ज़्यादा 64 वर्ण इस्तेमाल किए जा सकते हैं.आपने जो आईडी वैल्यू सेट की है वह आपको इस चैनल के लिए मिलने वाले हर सूचना मैसेज के
X-Goog-Channel-Id
एचटीटीपी हेडर में वापस दिखती है. -
type
प्रॉपर्टी स्ट्रिंग कोweb_hook
वैल्यू पर सेट किया गया है. -
address
प्रॉपर्टी स्ट्रिंग, उस यूआरएल पर सेट होती है जो इस सूचना चैनल के लिए सूचनाएं सुनता है और उनका जवाब देता है. यह आपका वेबहुक कॉलबैक यूआरएल है. इसमें एचटीटीपीएस का इस्तेमाल होना चाहिए.ध्यान दें कि Google Drive API, इस एचटीटीपीएस पते पर सूचनाएं सिर्फ़ तब भेज सकता है, जब आपके वेब सर्वर पर मान्य एसएसएल सर्टिफ़िकेट इंस्टॉल किया गया हो. अमान्य सर्टिफ़िकेट में ये शामिल हैं:
- खुद हस्ताक्षर किए हुए सर्टिफ़िकेट.
- किसी गैर-भरोसेमंद सोर्स के हस्ताक्षर किए हुए सर्टिफ़िकेट.
- वे सर्टिफ़िकेट जो निरस्त कर दिए गए हैं.
- ऐसे सर्टिफ़िकेट जिनका विषय, टारगेट किए गए होस्टनेम से मेल नहीं खाता.
ज़रूरी नहीं है कि ये प्रॉपर्टी मौजूद हों
watch
अनुरोध के साथ, इन वैकल्पिक फ़ील्ड की जानकारी भी दी जा सकती है:
-
token
प्रॉपर्टी, जो चैनल टोकन के तौर पर इस्तेमाल करने के लिए आर्बिट्ररी स्ट्रिंग वैल्यू के बारे में बताती है. सूचना चैनल टोकन का इस्तेमाल कई कामों के लिए किया जा सकता है. उदाहरण के लिए, इस टोकन का इस्तेमाल यह पुष्टि करने के लिए किया जा सकता है कि हर इनकमिंग मैसेज, आपके ऐप्लिकेशन से बनाए गए चैनल के लिए है. इससे यह पक्का किया जा सकता है कि सूचना को स्पूफ़ नहीं किया जा रहा है. इसके अलावा, इस टोकन का इस्तेमाल, चैनल के मकसद के आधार पर मैसेज को आपके ऐप्लिकेशन में सही डेस्टिनेशन पर भेजने के लिए भी किया जा सकता है. ज़्यादा से ज़्यादा वर्ण: 256 वर्ण.यह टोकन, हर सूचना वाले मैसेज में
X-Goog-Channel-Token
एचटीटीपी हेडर में शामिल होता है. यह मैसेज, आपके ऐप्लिकेशन को इस चैनल के लिए मिलता है.अगर सूचना चैनल टोकन का इस्तेमाल किया जाता है, तो हमारा सुझाव है कि आप:
एक्सटेंसिबल एन्कोडिंग फ़ॉर्मैट का इस्तेमाल करें. जैसे, यूआरएल क्वेरी पैरामीटर. उदाहरण:
forwardTo=hr&createdBy=mobile
इसमें OAuth टोकन जैसे संवेदनशील डेटा को शामिल न करें.
-
यह
expiration
प्रॉपर्टी स्ट्रिंग, यूनिक्स टाइमस्टैंप पर सेट होती है. यह टाइमस्टैंप, तारीख और समय के हिसाब से मिलीसेकंड में होता है. इस तारीख और समय के बाद, Google Drive API इस सूचना चैनल के लिए मैसेज भेजना बंद कर देगा.अगर किसी चैनल की समयसीमा खत्म होने वाली है, तो उसे
X-Goog-Channel-Expiration
एचटीटीपी हेडर की वैल्यू के तौर पर शामिल किया जाता है. यह वैल्यू, हर उस सूचना वाले मैसेज में शामिल होती है जो आपके ऐप्लिकेशन को इस चैनल के लिए मिलता है. यह वैल्यू, इंसानों के पढ़ने लायक फ़ॉर्मैट में होती है.
अनुरोध के बारे में ज़्यादा जानने के लिए, एपीआई के रेफ़रंस में files
और changes
तरीकों के लिए 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/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable. }
आपने अनुरोध में जो प्रॉपर्टी भेजी हैं उनके अलावा, जवाब में मिली जानकारी में resourceId
और resourceUri
भी शामिल हैं. इनसे यह पता चलता है कि इस सूचना चैनल पर किस संसाधन को देखा जा रहा है.
आपको मिली जानकारी को सूचना चैनल से जुड़ी अन्य कार्रवाइयों के लिए इस्तेमाल किया जा सकता है. जैसे, सूचनाएं पाना बंद करना.
रिस्पॉन्स के बारे में ज़्यादा जानकारी के लिए, एपीआई के रेफ़रंस में files
और changes
तरीकों के लिए watch
तरीका देखें.
मैसेज सिंक करना
किसी संसाधन को मॉनिटर करने के लिए सूचना चैनल बनाने के बाद, Google Drive API एक sync
मैसेज भेजता है. इससे पता चलता है कि सूचनाएं भेजी जा रही हैं. इन मैसेज के लिए, X-Goog-Resource-State
एचटीटीपी हेडर की वैल्यू sync
है. नेटवर्क टाइमिंग से जुड़ी समस्याओं की वजह से, ऐसा हो सकता है कि आपको sync
तरीके का जवाब मिलने से पहले ही sync
मैसेज मिल जाए.watch
sync
सूचना को अनदेखा किया जा सकता है. हालांकि, इसका इस्तेमाल भी किया जा सकता है. उदाहरण के लिए, अगर आपको चैनल नहीं रखना है, तो X-Goog-Channel-ID
और X-Goog-Resource-ID
वैल्यू का इस्तेमाल करके, सूचनाएं पाना बंद किया जा सकता है. इसके अलावा, sync
सूचना का इस्तेमाल करके, बाद के इवेंट के लिए कुछ शुरुआती कार्रवाइयां भी की जा सकती हैं.
Google Drive 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 Drive API की किसी अंदरूनी सीमा या डिफ़ॉल्ट सेटिंग से तय होती है. इनमें से ज़्यादा पाबंदी वाली वैल्यू का इस्तेमाल किया जाता है. अगर चैनल की सदस्यता की समयसीमा खत्म होने वाली है, तो उसकी जानकारी watch
तरीके से मिली जानकारी में शामिल की जाती है. यह जानकारी यूनिक्स टाइमस्टैंप (मिलीसेकंड में) के तौर पर शामिल की जाती है. इसके अलावा, हर सूचना वाले मैसेज में समयसीमा खत्म होने की तारीख और समय (इंसान के पढ़ने लायक फ़ॉर्मैट में) शामिल होता है. आपका ऐप्लिकेशन, इस चैनल के लिए X-Goog-Channel-Expiration
एचटीटीपी हेडर में यह मैसेज पाता है.
फ़िलहाल, सूचना चैनल को अपने-आप रिन्यू करने का कोई तरीका नहीं है. जब किसी चैनल की समयसीमा खत्म होने वाली हो, तो आपको उसे नए चैनल से बदलना होगा. इसके लिए, watch
तरीके को कॉल करें. हमेशा की तरह, आपको नए चैनल की id
प्रॉपर्टी के लिए एक यूनीक वैल्यू का इस्तेमाल करना होगा. ध्यान दें कि ऐसा हो सकता है कि एक ही संसाधन के लिए, सूचना पाने के दोनों चैनल एक साथ चालू हों. इस दौरान, सूचनाएं "ओवरलैप" हो सकती हैं.
सूचनाएं पाएं
जब भी मॉनिटर की जा रही किसी संसाधन में बदलाव होता है, तब आपके ऐप्लिकेशन को बदलाव के बारे में बताने वाला सूचना मैसेज मिलता है. Google Drive API, इन मैसेज को एचटीटीपीएस POST
अनुरोधों के तौर पर भेजता है. ये अनुरोध, उस यूआरएल पर भेजे जाते हैं जिसे आपने इस सूचना चैनल के लिए address
प्रॉपर्टी के तौर पर सेट किया है.
सूचना वाले मैसेज के फ़ॉर्मैट को समझना
सूचना वाले सभी मैसेज में, एचटीटीपी हेडर का एक सेट शामिल होता है. इनमें X-Goog-
प्रीफ़िक्स होते हैं.
कुछ तरह की सूचनाओं में मैसेज का मुख्य हिस्सा भी शामिल हो सकता है.
हेडर
Google Drive API, सूचनाएं पाने वाले आपके यूआरएल पर सूचना वाले जो मैसेज पोस्ट करता है उनमें ये एचटीटीपी हेडर शामिल होते हैं:
हेडर | ब्यौरा |
---|---|
हमेशा मौजूद | |
|
यूयूआईडी या अन्य यूनीक स्ट्रिंग, जिसका इस्तेमाल आपने इस सूचना चैनल की पहचान करने के लिए किया है. |
|
पूर्णांक, जो इस सूचना चैनल के लिए इस मैसेज की पहचान करता है. sync मैसेज के लिए, वैल्यू हमेशा 1 होती है. चैनल पर हर मैसेज के साथ मैसेज नंबर बढ़ता है, लेकिन यह क्रम से नहीं होता. |
|
यह एक अपारदर्शी वैल्यू है, जो देखे जा रहे संसाधन की पहचान करती है. यह आईडी, एपीआई के सभी वर्शन में एक जैसा रहता है. |
|
संसाधन की नई स्थिति, जिसकी वजह से सूचना ट्रिगर हुई.
इन वैल्यू का इस्तेमाल किया जा सकता है:
sync , add , remove , update ,
trash , untrash या change
.
|
|
यह एपीआई के वर्शन के हिसाब से, मॉनिटर किए जा रहे रिसॉर्स के लिए आइडेंटिफ़ायर होता है. |
कभी-कभी मौजूद होता है | |
|
बदलावों के बारे में ज़्यादा जानकारी.
इन वैल्यू का इस्तेमाल किया जा सकता है:
content ,
parents ,
children या
permissions
.
sync मैसेज नहीं मिले. |
|
सूचना चैनल के खत्म होने की तारीख और समय. इसे ऐसे फ़ॉर्मैट में दिखाया जाता है जिसे कोई भी व्यक्ति आसानी से पढ़ सकता है. यह सिर्फ़ तब मौजूद होता है, जब इसे तय किया गया हो. |
|
सूचना चैनल का टोकन, जिसे आपके ऐप्लिकेशन ने सेट किया था. इसका इस्तेमाल सूचना के सोर्स की पुष्टि करने के लिए किया जा सकता है. यह सिर्फ़ तब मौजूद होता है, जब इसे डिफ़ाइन किया गया हो. |
files
और changes
के लिए सूचना वाले मैसेज खाली हैं.
उदाहरण
files
संसाधनों के लिए सूचना में बदलाव करने का मैसेज. इसमें अनुरोध का मुख्य हिस्सा शामिल नहीं है:
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/drive/v3/files/ret08u3rv24htgh289g X-Goog-Resource-State: update X-Goog-Changed: content,properties X-Goog-Message-Number: 10
changes
संसाधनों के लिए सूचना में बदलाव करने का मैसेज. इसमें अनुरोध का मुख्य हिस्सा शामिल होता है:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 118 X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43 X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes X-Goog-Resource-State: changed X-Goog-Message-Number: 23 { "kind": "drive#changes" }
सूचनाओं का उत्तर दें
सफल होने की जानकारी देने के लिए, इनमें से कोई भी स्टेटस कोड दिखाया जा सकता है:
200
, 201
, 202
, 204
या 102
.
अगर आपकी सेवा Google की API क्लाइंट लाइब्रेरी का इस्तेमाल करती है और 500
,502
, 503
या 504
दिखाती है, तो Google Drive API, एक्सपोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करता है.
वापसी के हर दूसरे स्टेटस कोड को मैसेज डिलीवर न होने की समस्या माना जाता है.
Google Drive API की सूचनाओं से जुड़े इवेंट के बारे में जानकारी
इस सेक्शन में, Google Drive API के साथ पुश नोटिफ़िकेशन इस्तेमाल करने पर मिलने वाले सूचना मैसेज के बारे में जानकारी दी गई है.
डिलीवर कब किया गया | ||
---|---|---|
sync |
files , changes |
चैनल बनाया गया. इसके बाद, आपको इस इवेंट के लिए सूचनाएं मिलनी शुरू हो जाएंगी. |
add |
files |
कोई संसाधन बनाया गया है या शेयर किया गया है. |
|
files |
मौजूदा संसाधन को मिटा दिया गया है या उसकी शेयरिंग रोक दी गई है. |
|
files |
किसी संसाधन की एक या उससे ज़्यादा प्रॉपर्टी (मेटाडेटा) अपडेट की गई हैं. |
|
files |
किसी संसाधन को ट्रैश में ले जाया गया है. |
|
files |
किसी संसाधन को ट्रैश से हटा दिया गया है. |
|
changes |
एक या उससे ज़्यादा बदलाव लॉग आइटम जोड़े गए हैं. |
update
इवेंट के लिए, X-Goog-Changed
एचटीटीपी हेडर दिया जा सकता है. इस हेडर में, कॉमा लगाकर अलग की गई एक सूची होती है. इसमें, किए गए बदलावों के टाइप के बारे में बताया जाता है.
बदलाव का टाइप | यह दिखाता है |
---|---|
content |
संसाधन का कॉन्टेंट अपडेट कर दिया गया है. |
properties |
एक या उससे ज़्यादा संसाधन प्रॉपर्टी अपडेट की गई हैं. |
parents |
एक या उससे ज़्यादा संसाधन पैरंट जोड़े या हटाए गए हैं. |
children |
एक या उससे ज़्यादा संसाधन चाइल्ड जोड़े या हटाए गए हैं. |
permissions |
संसाधन की अनुमतियां अपडेट कर दी गई हैं. |
X-Goog-Changed
हेडर का उदाहरण:
X-Goog-Resource-State: update X-Goog-Changed: content, permissions
सूचनाएं पाने की सुविधा बंद करें
expiration
प्रॉपर्टी से यह कंट्रोल किया जाता है कि सूचनाएं अपने-आप कब बंद होंगी. आपके पास किसी चैनल की सदस्यता खत्म होने से पहले, उसकी सूचनाएं पाने की सुविधा बंद करने का विकल्प होता है. इसके लिए, आपको stop
तरीके का इस्तेमाल करके, इस यूआरआई पर कॉल करना होगा:
https://www.googleapis.com/drive/v3/channels/stop
इस तरीके के लिए, आपको कम से कम चैनल की id
और resourceId
प्रॉपर्टी देनी होंगी. यहां दिए गए उदाहरण में, इन प्रॉपर्टी को दिखाया गया है. ध्यान दें कि अगर Google Drive API में कई तरह के ऐसे संसाधन हैं जिनमें watch
तरीके हैं, तो सिर्फ़ एक stop
तरीका होता है.
चैनल को सिर्फ़ वे लोग बंद कर सकते हैं जिनके पास इसकी अनुमति है. खास तौर पर:
- अगर चैनल को किसी सामान्य उपयोगकर्ता खाते से बनाया गया था, तो सिर्फ़ वही उपयोगकर्ता चैनल को बंद कर सकता है जिसने उसे बनाया था. साथ ही, वह उपयोगकर्ता उसी क्लाइंट से होना चाहिए जिसकी पहचान OAuth 2.0 क्लाइंट आईडी से हुई है. यह आईडी, ऑथराइज़ेशन टोकन से मिलता है.
- अगर चैनल को किसी सेवा खाते से बनाया गया है, तो उसी क्लाइंट का कोई भी उपयोगकर्ता चैनल को बंद कर सकता है.
यहां दिए गए कोड सैंपल में, सूचनाएं पाने की सुविधा बंद करने का तरीका बताया गया है:
POST https://www.googleapis.com/drive/v3/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }