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