संसाधनों में बदलाव की सूचनाएं

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

खास जानकारी

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

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

सूचना का हर चैनल किसी खास उपयोगकर्ता और कोई खास संसाधन या संसाधनों का सेट. watch का अनुरोध तब तक सफल नहीं होगा, जब तक मौजूदा उपयोगकर्ता या सेवा खाता इस संसाधन का स्वामी है या उसे ऐक्सेस करने की अनुमति है.

उदाहरण

नीचे दिया गया कोड सैंपल, channels संसाधन का इस्तेमाल करके, किसी files संसाधन में हुए बदलावों को देखने के लिए, files.watch तरीके का इस्तेमाल करने का तरीका बताया गया है:

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

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

जवाब देखें

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

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

जवाब के बारे में ज़्यादा जानकारी पाने के लिए, watch देखें तरीका है.fileschanges

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

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

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

हेडर ब्यौरा
हमेशा मौजूद रहें
X-Goog-Channel-ID इसकी पहचान करने के लिए, यूयूआईडी या कोई अन्य यूनीक स्ट्रिंग सूचना का चैनल.
X-Goog-Message-Number वह पूर्णांक जो इस सूचना के लिए इस मैसेज की पहचान करता है चैनल. sync मैसेज के लिए यह वैल्यू हमेशा 1 होती है. मैसेज करें चैनल पर हर मैसेज की संख्या बढ़ती है, लेकिन क्रम में नहीं.
X-Goog-Resource-ID देखे गए संसाधन की पहचान करने वाली ओपेक वैल्यू. यह आईडी है सभी एपीआई वर्शन में अच्छी तरह से काम करता है.
X-Goog-Resource-State सूचना को ट्रिगर करने वाले संसाधन की नई स्थिति. वैल्यू, इनमें से कोई हो सकती है: sync, add, remove, update, trash, untrash या change को अपनाएं.
X-Goog-Resource-URI देखे गए संसाधन के लिए एपीआई वर्शन के हिसाब से खास आइडेंटिफ़ायर.
कभी-कभी प्रज़ेंट करते हैं
X-Goog-Changed इन बदलावों के बारे में ज़्यादा जानकारी. वैल्यू, इनमें से कोई हो सकती है: content, parents, children या permissions को अपनाएं. sync मैसेज के साथ नहीं दिया गया.
X-Goog-Channel-Expiration सूचना चैनल के खत्म होने की तारीख और समय, जिसे कोई भी व्यक्ति आसानी से पढ़ सकता है. तय होने पर ही मौजूद होता है.
X-Goog-Channel-Token सूचना चैनल टोकन, जिसे आपके ऐप्लिकेशन ने सेट किया है, और जिसकी मदद से सूचना के सोर्स की पुष्टि की जा सकती है. सिर्फ़ तभी मौजूद होता है, जब तय किया गया है.

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 की एपीआई क्लाइंट लाइब्रेरी का इस्तेमाल किया जाता है और Google Drive API 500,502, 503 या 504 दिखाता है एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करता है. यह माना जाता है कि सामान लौटाने की स्थिति बताने वाले दूसरे हर कोड से, मैसेज नहीं भेजा जा सका.

Google Drive API के सूचना इवेंट के बारे में जानकारी

इस सेक्शन में, उन सूचना मैसेज के बारे में जानकारी दी गई है जो पाएं.

X-Goog-Resource-State इस पर लागू होता है इस समय डिलीवर किया गया
sync files, changes चैनल बना दिया गया. आपको इसके लिए सूचनाएं मिलनी शुरू हो सकती हैं.
add files कोई संसाधन बनाया या शेयर किया गया था.
remove files किसी मौजूदा संसाधन को मिटा दिया गया है या उसकी शेयरिंग रोक दी गई है.
update files किसी संसाधन की एक या उससे ज़्यादा प्रॉपर्टी (मेटाडेटा) अपडेट कर दी गई हैं.
trash files कोई संसाधन ट्रैश में ले जाया गया है.
untrash files एक संसाधन को ट्रैश से निकाल दिया गया है.
change 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 तरीका.

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

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

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

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