इस दस्तावेज़ में उन पुश नोटिफ़िकेशन के इस्तेमाल का तरीका बताया गया है जो किसी संसाधन में बदलाव होने पर, आपके ऐप्लिकेशन को सूचना देते हैं.
खास जानकारी
Google Drive API से पुश नोटिफ़िकेशन मिलते हैं. इनकी मदद से, संसाधनों में हो रहे बदलावों पर नज़र रखी जा सकती है. इस सुविधा का इस्तेमाल करके, अपने ऐप्लिकेशन की परफ़ॉर्मेंस को बेहतर बनाया जा सकता है. इसकी मदद से, पोलिंग रिसॉर्स में हुए अतिरिक्त नेटवर्क और उसके खर्च का हिसाब लगाकर यह पता लगाया जा सकता है कि वे बदले गए हैं या नहीं. जब भी देखा गया कोई संसाधन बदलता है, तो Google Drive API आपके ऐप्लिकेशन को सूचना देता है.
पुश नोटिफ़िकेशन का इस्तेमाल करने के लिए, आपको दो काम करने होंगे:
पाने वाले यूआरएल या "वेबहुक" कॉलबैक रिसीवर को सेट अप करें.
यह एक एचटीटीपीएस सर्वर है. यह उन एपीआई की सूचनाओं को मैनेज करता है जो किसी संसाधन में बदलाव होने पर ट्रिगर होते हैं.
हर उस रिसॉर्स एंडपॉइंट के लिए एक सूचना चैनल सेट अप करें जिसे आपको देखना है.
चैनल, सूचना वाले मैसेज की रूटिंग की जानकारी देता है. चैनल सेटअप करते समय, आपको उस यूआरएल की पहचान करनी होगी जिस पर आपको सूचनाएं चाहिए. जब भी किसी चैनल के संसाधन में बदलाव होता है, तो Google Drive API उस यूआरएल पर
POST
अनुरोध के तौर पर सूचना वाला मैसेज भेजता है.
फ़िलहाल,
files
और changes
तरीकों में हुए बदलावों की सूचनाएं, Google Drive API पर काम करती हैं.
सूचना के चैनल बनाएं
पुश नोटिफ़िकेशन का अनुरोध करने के लिए, आपको हर उस संसाधन के लिए सूचना वाला चैनल सेट अप करना होगा जिसे आपको मॉनिटर करना है. सूचना चैनल सेट अप होने के बाद, देखे गए किसी भी संसाधन में बदलाव होने पर, 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
तरीके का इस्तेमाल करके channels
के सभी changes
वीडियो देखने के लिए, संसाधन इस्तेमाल करने का तरीका बताया गया है:
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
प्रॉपर्टी स्ट्रिंग, जो आपके प्रोजेक्ट में इस नए सूचना चैनल की खास तौर पर पहचान करती है. हमारा सुझाव है कि आप यूनिवर्सल यूनीक आइडेंटिफ़ायर (यूयूआईडी) या इससे मिलती-जुलती किसी यूनीक स्ट्रिंग का इस्तेमाल करें. ज़्यादा से ज़्यादा 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
है. नेटवर्क टाइमिंग से जुड़ी समस्याओं की वजह से, हो सकता है कि आपको watch
का रिस्पॉन्स मिलने से पहले ही sync
मैसेज मिल जाए.
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 की एपीआई क्लाइंट लाइब्रेरी
का इस्तेमाल करती है और 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" }