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

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

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. कार्रवाई के लंबित होने की स्थिति की जांच करना: अगर एलआरओ से done=true के साथ, कार्रवाई के लंबित होने की जानकारी मिलती है, तो इससे पता चलता है कि फ़ाइल डाउनलोड के लिए तैयार है और कार्रवाई का स्टेटस पूरा हो गया है.

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

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

ज़्यादा समय तक चलने वाली कार्रवाई के तहत कॉन्टेंट डाउनलोड करने के लिए, download तरीके का इस्तेमाल files संसाधन पर करें. इस तरीके में, 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 Vids की फ़ाइलें एक्सपोर्ट करने की कोशिश की जाती है, तो fileNotExportable गड़बड़ी मिलती है.

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 मिलते हैं.

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

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

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

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

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 का कैननिकल गड़बड़ी कोड शामिल होता है.

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

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

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

• फ़ाइलें डाउनलोड और एक्सपोर्ट करना