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

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

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

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

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

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

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