लंबे समय तक चलने वाली कार्रवाइयों को मैनेज करें

लंबे समय तक चलने वाला ऑपरेशन (एलआरओ), एपीआई का एक ऐसा तरीका है जिसे पूरा होने में, एपीआई रिस्पॉन्स के लिए ज़रूरी समय से ज़्यादा समय लगता है. आम तौर पर, टास्क के चलने के दौरान कॉलिंग थ्रेड को खुला नहीं रखना चाहिए, क्योंकि इससे उपयोगकर्ता को खराब अनुभव मिलता है. इसके बजाय, उपयोगकर्ता को कोई वादा करें और उसे बाद में वापस आने के लिए कहें.

Google Drive API, हर बार files संसाधन पर download() तरीके को कॉल करने पर, एक एलआरओ दिखाता है. ऐसा, Drive API या उसकी क्लाइंट लाइब्रेरी के ज़रिए किसी फ़ाइल का कॉन्टेंट डाउनलोड करने के लिए किया जाता है.

यह तरीका, क्लाइंट को operations रिसोर्स दिखाता है. operations रिसोर्स का इस्तेमाल करके, एपीआई के तरीके की स्थिति को असींक्रोनस तरीके से पाया जा सकता है. इसके लिए, get() तरीके से ऑपरेशन को पोल किया जाता है. Drive API में मौजूद एलआरओ, Google Cloud के एलआरओ डिज़ाइन पैटर्न का पालन करते हैं.

ज़्यादा जानकारी के लिए, लंबे समय तक चलने वाले ऑपरेशन देखें.

प्रोसेस से जुड़ी खास जानकारी

नीचे दिए गए डायग्राम में, file.download तरीका कैसे काम करता है, इसकी खास जानकारी दी गई है.

1. files.download को कॉल करना: जब आपका ऐप्लिकेशन download() तरीके को कॉल करता है, तो वह फ़ाइल के लिए Drive API डाउनलोड अनुरोध को लॉन्च करता है. ज़्यादा जानकारी के लिए, फ़ाइलें डाउनलोड करना देखें.

2. अनुमतियों का अनुरोध करना: यह अनुरोध, Drive API को पुष्टि करने के क्रेडेंशियल भेजता है. अगर आपके ऐप्लिकेशन को उपयोगकर्ता की पुष्टि करने के लिए, Drive API को कॉल करने की ज़रूरत है और उपयोगकर्ता ने अब तक पुष्टि नहीं की है, तो ऐप्लिकेशन उपयोगकर्ता को साइन इन करने के लिए कहता है. आपका ऐप्लिकेशन, पुष्टि करने की सुविधा सेट अप करते समय बताए गए स्कोप के साथ भी ऐक्सेस मांगता है.

3. डाउनलोड शुरू करना: फ़ाइल को डाउनलोड करने के लिए, Drive API का अनुरोध किया जाता है. यह अनुरोध, Google Vids या Google Workspace के किसी अन्य कॉन्टेंट के लिए किया जा सकता है.

4. एलआरओ शुरू करना: लंबे समय तक चलने वाला ऑपरेशन शुरू होता है और यह डाउनलोड की प्रोसेस को मैनेज करता है.

5. पूरा नहीं हुआ ऑपरेशन दिखाना: Drive API, पूरा नहीं हुआ ऑपरेशन दिखाता है. इसमें, अनुरोध करने वाले उपयोगकर्ता और फ़ाइल के कई मेटाडेटा फ़ील्ड की जानकारी होती है.

6. शुरुआती स्थिति में, कार्रवाई बाकी है: आपके ऐप्लिकेशन को done=null की शुरुआती स्थिति के साथ, कार्रवाई बाकी है का मैसेज मिलता है. इसका मतलब है कि फ़ाइल अभी डाउनलोड के लिए तैयार नहीं है और कार्रवाई का स्टेटस 'मंज़ूरी बाकी है' है.

7. operations.get को कॉल करना और नतीजे की पुष्टि करना: आपका ऐप्लिकेशन, सुझाई गई समयावधि के हिसाब से get() को कॉल करता है, ताकि ऑपरेशन के नतीजे को पोल किया जा सके और लंबे समय से चल रहे ऑपरेशन की नई स्थिति का पता लगाया जा सके. अगर done=false की स्थिति 'पूरी नहीं हुई' के तौर पर दिखती है, तो आपके ऐप्लिकेशन को तब तक पोल करना होगा, जब तक कि कार्रवाई पूरी होने की स्थिति (done=true) न दिखे. बड़ी फ़ाइलों के लिए, कई बार पोल करने की ज़रूरत पड़ सकती है. ज़्यादा जानकारी के लिए, लंबे समय तक चलने वाले ऑपरेशन के बारे में जानकारी पाना लेख पढ़ें.

8. पूरा न होने की स्थिति देखना: अगर LRO से done=true की स्थिति 'पूरा नहीं हुआ' के तौर पर दिखती है, तो इसका मतलब है कि फ़ाइल डाउनलोड के लिए तैयार है और ऑपरेशन की स्थिति पूरी हो गई है.

9. डाउनलोड यूआरआई के साथ पूरा किया गया ऑपरेशन दिखाना: एलआरओ पूरा होने के बाद, Drive API डाउनलोड यूआरआई दिखाता है. इसके बाद, फ़ाइल उपयोगकर्ता के लिए उपलब्ध हो जाती है.

फ़ाइल डाउनलोड करें

लंबे समय तक चलने वाले ऑपरेशन के तहत कॉन्टेंट डाउनलोड करने के लिए, files संसाधन पर download() तरीके का इस्तेमाल करें. यह तरीका, file_id, mime_type, और revision_id के क्वेरी पैरामीटर लेता है:

• ज़रूरी है. file_id क्वेरी पैरामीटर, डाउनलोड की जाने वाली फ़ाइल का आईडी होता है.

• ज़रूरी नहीं. mime_type क्वेरी पैरामीटर से पता चलता है कि जिस तरीके का इस्तेमाल किया जाना है उसका MIME टाइप क्या है. यह सुविधा सिर्फ़ ब्लॉब के अलावा, अन्य मीडिया कॉन्टेंट (जैसे, Google Workspace दस्तावेज़) डाउनलोड करते समय उपलब्ध होती है. काम करने वाले MIME टाइप की पूरी सूची के लिए, Google Workspace दस्तावेज़ों के लिए MIME टाइप एक्सपोर्ट करना लेख पढ़ें.

  अगर MIME टाइप सेट नहीं है, तो Google Workspace दस्तावेज़ को डिफ़ॉल्ट MIME टाइप के साथ डाउनलोड किया जाता है. ज़्यादा जानकारी के लिए, डिफ़ॉल्ट MIME टाइप देखें.

• ज़रूरी नहीं. revision_id क्वेरी पैरामीटर, डाउनलोड की जाने वाली फ़ाइल का रिविज़न आईडी होता है. यह सुविधा सिर्फ़ ब्लॉब फ़ाइलें, Google Docs, और Google Sheets डाउनलोड करते समय उपलब्ध होती है. काम न करने वाली फ़ाइलों पर किसी खास बदलाव को डाउनलोड करते समय, गड़बड़ी का कोड INVALID_ARGUMENT दिखाता है.

download() तरीका, Vids की फ़ाइलों को MP4 फ़ॉर्मैट में डाउनलोड करने का एकमात्र तरीका है. आम तौर पर, यह ज़्यादातर वीडियो फ़ाइलों को डाउनलोड करने के लिए सबसे सही तरीका है.

Google Docs या Sheets के लिए जनरेट किए गए डाउनलोड लिंक, शुरू में एक रीडायरेक्ट दिखाते हैं. फ़ाइल डाउनलोड करने के लिए, नए लिंक पर क्लिक करें.

download() तरीके से किए गए उस अनुरोध और डाउनलोड किए गए फ़ाइनल यूआरआई को फ़ेच करने के अनुरोध, दोनों में संसाधन कुंजियों का इस्तेमाल किया जाना चाहिए. ज़्यादा जानकारी के लिए, रिसॉर्स पासकोड का इस्तेमाल करके, लिंक की गई Drive फ़ाइलों को ऐक्सेस करना लेख पढ़ें.

अनुरोध का प्रोटोकॉल यहां दिखाया गया है.

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

FILE_ID को उस फ़ाइल के fileId से बदलें जिसे आपको डाउनलोड करना है.

डिफ़ॉल्ट MIME टाइप

अगर ब्लॉब कॉन्टेंट को डाउनलोड करते समय MIME टाइप सेट नहीं किया जाता है, तो ये डिफ़ॉल्ट MIME टाइप असाइन किए जाते हैं:

जवाब डाउनलोड करना

download() तरीके को कॉल करते समय, रिस्पॉन्स बॉडी में एक ऐसा रिसॉर्स होता है जो लंबे समय तक चलने वाले ऑपरेशन को दिखाता है. आम तौर पर, यह तरीका फ़ाइल के कॉन्टेंट को डाउनलोड करने के लिए एक लिंक दिखाता है.

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
    "resourceKey": "RESOURCE_KEY"
  },
  "name": "NAME",
  "response": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
    "downloadUri": "DOWNLOAD_URI",
    "partialDownloadAllowed": false
  }
}

इस आउटपुट में ये वैल्यू शामिल हैं:

• RESOURCE_KEY: संसाधन कुंजी से, आपकी फ़ाइल को अनचाहे ऐक्सेस से सुरक्षित रखने में मदद मिलती है. ज़्यादा जानकारी के लिए, लिंक की मदद से शेयर की गई Drive फ़ाइलों को ऐक्सेस करने के लिए, संसाधन कुंजियों का इस्तेमाल करना लेख पढ़ें.

• NAME: सर्वर से असाइन किया गया नाम.

• DOWNLOAD_URI: फ़ाइल के लिए, डाउनलोड करने का फ़ाइनल यूआरआई.

ध्यान दें कि partialDownloadAllowed फ़ील्ड से पता चलता है कि कुछ हिस्से को डाउनलोड करने की अनुमति है या नहीं. ब्लॉब फ़ाइल का कॉन्टेंट डाउनलोड करते समय True.

लंबे समय तक चलने वाले ऑपरेशन के बारे में जानकारी पाना

लंबे समय तक चलने वाले ऑपरेशन, ऐसे तरीकों के कॉल होते हैं जिन्हें पूरा होने में काफ़ी समय लग सकता है. आम तौर पर, डाउनलोड के लिए शुरू किए गए नए ऑपरेशन, शुरू में 'मंज़ूरी बाकी है' (done=null) स्थिति में दिखते हैं. ऐसा खास तौर पर, Vids फ़ाइलों के लिए होता है.

प्रोसेस किए जा रहे एलआरओ की स्थिति देखने के लिए, Drive API के operations संसाधन का इस्तेमाल किया जा सकता है. इसके लिए, आपको सर्वर से असाइन किया गया यूनीक नाम शामिल करना होगा.

get() तरीके से, लंबे समय तक चलने वाले ऑपरेशन की सबसे नई स्थिति, एसिंक्रोनस तरीके से मिलती है. क्लाइंट इस तरीके का इस्तेमाल करके, एपीआई सेवा के सुझाव के मुताबिक, इंटरवल पर ऑपरेशन के नतीजे को पोल कर सकते हैं.

ज़्यादा समय तक चलने वाली कार्रवाई के लिए पोल करना

उपलब्ध एलआरओ को पोल करने के लिए, जब तक ऑपरेशन पूरा न हो जाए, तब तक get() तरीके को बार-बार कॉल करें. हर पोल अनुरोध के बीच एक्सपोनेंशियल बैकऑफ़ का इस्तेमाल करें, जैसे कि 10 सेकंड.

एलआरओ कम से कम 12 घंटे तक उपलब्ध रहता है. हालांकि, कुछ मामलों में यह इससे ज़्यादा समय तक भी रह सकता है. इस अवधि में बदलाव हो सकता है. साथ ही, यह फ़ाइल के टाइप के हिसाब से अलग-अलग हो सकती है. संसाधन की समयसीमा खत्म होने के बाद, download() के नए तरीके का अनुरोध करना ज़रूरी है.

get() से जुड़े सभी अनुरोधों में, रिसॉर्स कुंजियों का इस्तेमाल किया जाना चाहिए. ज़्यादा जानकारी के लिए, रिसॉर्स पासकोड का इस्तेमाल करके, लिंक की गई Drive फ़ाइलों को ऐक्सेस करना लेख पढ़ें.

अनुरोध के प्रोटोकॉल यहां दिखाए गए हैं.

operations.get(name='NAME');

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

ध्यान दें कि name सिर्फ़ download() अनुरोध के जवाब में दिखता है. इसे वापस पाने का कोई दूसरा तरीका नहीं है, क्योंकि Drive API में List() तरीका काम नहीं करता. अगर name वैल्यू नहीं मिलती है, तो आपको download() तरीके के अनुरोध को फिर से कॉल करके नया जवाब जनरेट करना होगा.

get() अनुरोध के जवाब में, लंबे समय तक चलने वाले ऑपरेशन को दिखाने वाला संसाधन होता है. ज़्यादा जानकारी के लिए, रिस्पॉन्स डाउनलोड करना लेख पढ़ें.

जब जवाब में 'पूरा हो गया' स्टेटस (done=true) दिखता है, तो इसका मतलब है कि लंबे समय तक चलने वाला ऑपरेशन पूरा हो गया है.

बदलाव डाउनलोड करना

नया वर्शन डाउनलोड करने के लिए, files संसाधन के headRevisionId फ़ील्ड की वैल्यू का इस्तेमाल किया जा सकता है. इससे, उस फ़ाइल का बदलाव फ़ेच होता है जो आपने पहले फ़ेच की थी. फ़ाइल के उन सभी पुराने वर्शन का डेटा डाउनलोड करने के लिए जो अब भी क्लाउड में सेव हैं, fileId पैरामीटर के साथ revisions संसाधन पर list() तरीका कॉल किया जा सकता है. इससे फ़ाइल में मौजूद सभी revisionIds दिखते हैं.

ब्लॉब फ़ाइलों के बदलाव किए गए कॉन्टेंट को डाउनलोड करने के लिए, आपको revisions रिसोर्स पर get() तरीके को कॉल करना होगा. इसके लिए, डाउनलोड की जाने वाली फ़ाइल का आईडी, बदलाव का आईडी, और alt=media यूआरएल पैरामीटर की ज़रूरत होगी. alt=media यूआरएल पैरामीटर, सर्वर को बताता है कि जवाब के वैकल्पिक फ़ॉर्मैट के तौर पर, कॉन्टेंट डाउनलोड करने का अनुरोध किया जा रहा है.

Google Docs, Sheets, Slides, और Vids में किए गए बदलावों को, alt=media यूआरएल के साथ get() तरीके का इस्तेमाल करके डाउनलोड नहीं किया जा सकता . ऐसा न करने पर, यह fileNotDownloadable वाली गड़बड़ी जनरेट करता है.

alt=media यूआरएल पैरामीटर, सिस्टम पैरामीटर है. यह Google के सभी REST API में उपलब्ध है. अगर Drive API के लिए क्लाइंट लाइब्रेरी का इस्तेमाल किया जाता है, तो आपको इस पैरामीटर को साफ़ तौर पर सेट करने की ज़रूरत नहीं है.

अनुरोध का प्रोटोकॉल यहां दिखाया गया है.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

इनकी जगह ये डालें:

• FILE_ID: उस फ़ाइल का fileId जिसे आपको डाउनलोड करना है.
• REVISION_ID: उस बदलाव का revisionId जिसे आपको डाउनलोड करना है.

Google Docs, Drawings, और Slides में किए गए बदलावों के बाद, बदलावों की संख्या अपने-आप बढ़ जाती है. हालांकि, अगर बदलावों को मिटा दिया जाता है, तो नंबरों की सीरीज़ में अंतर हो सकता है. इसलिए, बदलावों को वापस पाने के लिए, क्रम से आने वाले नंबरों पर भरोसा नहीं करना चाहिए.

एलआरओ से जुड़ी समस्या हल करना

जब कोई एलआरओ पूरा नहीं होता, तो उसके जवाब में Google Cloud का कैननिकल गड़बड़ी कोड शामिल होता है.

इस टेबल में, हर कोड की वजह के बारे में जानकारी दी गई है. साथ ही, कोड को मैनेज करने का सुझाव भी दिया गया है. कई गड़बड़ियों के लिए, एक्सपोनेंशियल बैकऑफ़ का इस्तेमाल करके, अनुरोध को फिर से करने का सुझाव दिया जाता है.

इस गड़बड़ी के मॉडल और इसके साथ काम करने के तरीके के बारे में ज़्यादा जानने के लिए, एपीआई डिज़ाइन गाइड पढ़ें.

मिलते-जुलते विषय

• फ़ाइलें डाउनलोड और एक्सपोर्ट करना
• फ़ाइल में किए गए बदलावों को मैनेज करना