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

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

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

यह तरीका, क्लाइंट को operations संसाधन दिखाता है. operations संसाधन का इस्तेमाल करके, एपीआई के तरीके की स्थिति को एसिंक्रोनस तरीके से वापस पाया जा सकता है. इसके लिए, get तरीके का इस्तेमाल करके कार्रवाई को पोल करें. Drive API में LRO, Google Cloud LRO डिज़ाइन पैटर्न का पालन करते हैं.

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

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

नीचे दिए गए डायग्राम में, 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 डाउनलोड यूआरआई दिखाता है. इसके बाद, उपयोगकर्ता के लिए फ़ाइल उपलब्ध हो जाती है.

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

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

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

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

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

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

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

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

डिफ़ॉल्ट एमआईएमई टाइप

अगर नॉन-ब्लॉब कॉन्टेंट डाउनलोड करते समय 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 होता है, जब blob फ़ाइल का कॉन्टेंट डाउनलोड किया जाता है.

ज़्यादा समय तक चलने वाली कार्रवाई के बारे में जानकारी पाना

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

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

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 के वर्शन को get तरीके से डाउनलोड नहीं किया जा सकता. इसके लिए, alt=media यूआरएल का इस्तेमाल करना होगा. ऐसा न होने पर, यह 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 गड़बड़ी कोड शामिल होता है.

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

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

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

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