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

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

खास जानकारी

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 से जुड़ा अनुरोध तब तक स्वीकार नहीं किया जा सकता, जब तक मौजूदा उपयोगकर्ता या सेवा खाते के पास इस संसाधन का मालिकाना हक हो या उसे ऐक्सेस करने की अनुमति हो.

उदाहरण

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

अनुरोध से जुड़ी ज़्यादा जानकारी के लिए, एपीआई रेफ़रंस में 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 की मदद से पोस्ट किए गए सूचना मैसेज में, यहां दिए गए एचटीटीपी हेडर शामिल होते हैं:

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

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

इस सेक्शन में, 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 तरीका इस्तेमाल होगा.

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

  • अगर चैनल किसी सामान्य उपयोगकर्ता खाते से बनाया गया है, तो सिर्फ़ उस क्लाइंट (जैसा कि पुष्टि करने वाले टोकन से 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"
}