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

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

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 क्वेरी पैरामीटर, डाउनलोड की जाने वाली फ़ाइल का रिविज़न आईडी होता है. यह सुविधा सिर्फ़ तब उपलब्ध होती है, जब BLOB फ़ाइलें, 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 फ़ील्ड से पता चलता है कि कुछ हिस्से को डाउनलोड करने की अनुमति है या नहीं. BLOB फ़ाइल का कॉन्टेंट डाउनलोड करते समय सही है.

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

लंबे समय तक चलने वाले ऑपरेशन, ऐसे तरीके से जुड़े कॉल होते हैं जिन्हें पूरा होने में ज़्यादा समय लग सकता है. आम तौर पर, हाल ही में बनाई गई डाउनलोड कार्रवाइयों को शुरुआत में, 'मंज़ूरी बाकी है' स्थिति (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 का कैननिकल गड़बड़ी कोड शामिल होता है.

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

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

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

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