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

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

खास जानकारी

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 है. नेटवर्क के समय से जुड़ी समस्याओं की वजह से, हो सकता है कि 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"
}