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

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

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

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

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

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

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

file.download तरीके के लिए, हाई-लेवल के चरण.
पहली इमेज. 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 टाइप असाइन किए जाते हैं:

दस्तावेज़ का टाइप फ़ॉर्मैट MIME प्रकार फ़ाइल एक्सटेंशन
Google Apps Script JSON application/vnd.google-apps.script+json .json
Google Docs Microsoft Word application/vnd.openxmlformats-officedocument.wordprocessingml.document .docx
Google Drawings PNG image/png .png
Google Forms पिन application/zip .zip
Google Sheets Microsoft Excel application/vnd.openxmlformats-officedocument.spreadsheetml.sheet .xlsx
Google Sites अधूरा टेक्स्ट text/raw .txt
Google Slides Microsoft PowerPoint application/vnd.openxmlformats-officedocument.presentationml.presentation .pptx
Google Vids MP4 application/mp4 .mp4
Jamboard PDF application/pdf .pdf

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

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
  }
}

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

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

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

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

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

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

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

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

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

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

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

तरीके का इस्तेमाल करके कॉल करना

operations.get(name='NAME');

NAME को सर्वर की ओर से असाइन किए गए उस नाम से बदलें जो download तरीके के अनुरोध के जवाब में दिखाया गया है.

curl

कमांड चलाकर, यह देखा जा सकता है कि कौनसे खाते से लॉग इन किया गया है.
curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

NAME को सर्वर की ओर से असाइन किए गए उस नाम से बदलें जो download तरीके के अनुरोध के जवाब में दिखाया गया है.

इस कमांड में, /drive/v3/operations/NAME पाथ का इस्तेमाल किया गया है.

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

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

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

कोड Enum ब्यौरा सुझाई गई कार्रवाई
1 CANCELLED कार्रवाई रद्द कर दी गई थी. आम तौर पर, ऐसा कॉल करने वाला व्यक्ति करता है. कार्रवाई को फिर से चलाएं.
2 UNKNOWN यह गड़बड़ी तब दिख सकती है, जब किसी दूसरे पते के स्पेस से मिली Status वैल्यू, किसी ऐसे गड़बड़ी वाले स्पेस से जुड़ी हो जिसके बारे में इस पते के स्पेस में जानकारी न हो. अगर एपीआई की गड़बड़ी से पूरी जानकारी नहीं मिलती है, तो गड़बड़ी को इस गड़बड़ी में बदला जा सकता है. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें.
3 INVALID_ARGUMENT क्लाइंट ने एक अमान्य तर्क बताया. यह गड़बड़ी FAILED_PRECONDITION से अलग है. INVALID_ARGUMENT ऐसे तर्कों के बारे में बताता है जिनमें सिस्टम की स्थिति से कोई फ़र्क़ नहीं पड़ता. जैसे, फ़ाइल का गलत नाम. समस्या ठीक किए बिना, फिर से कोशिश न करें.
4 DEADLINE_EXCEEDED कार्रवाई पूरी होने से पहले ही समयसीमा खत्म हो गई. सिस्टम की स्थिति में बदलाव करने वाली कार्रवाइयों के लिए, यह गड़बड़ी तब भी दिख सकती है, जब कार्रवाई पूरी हो गई हो. उदाहरण के लिए, किसी सर्वर से मिला सही जवाब, समयसीमा खत्म होने के बाद मिला हो. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें.
5 NOT_FOUND अनुरोध की गई कुछ इकाई, जैसे कि FHIR संसाधन नहीं मिला. समस्या ठीक किए बिना, फिर से कोशिश न करें.
6 ALREADY_EXISTS क्लाइंट ने जिस इकाई को बनाने की कोशिश की है वह पहले से मौजूद है. जैसे, DICOM इंस्टेंस. समस्या ठीक किए बिना, फिर से कोशिश न करें.
7 PERMISSION_DENIED कॉलर के पास, तय की गई कार्रवाई करने की अनुमति नहीं है. इस गड़बड़ी के कोड का मतलब यह नहीं है कि अनुरोध मान्य है, अनुरोध की गई इकाई मौजूद है या यह अन्य ज़रूरी शर्तों को पूरा करती है. समस्या ठीक किए बिना, फिर से कोशिश न करें.
8 RESOURCE_EXHAUSTED किसी संसाधन का इस्तेमाल पूरी तरह से हो गया है. जैसे, हर प्रोजेक्ट के लिए तय किया गया कोटा. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें. समय के साथ, कोटा उपलब्ध हो सकता है.
9 FAILED_PRECONDITION इस कार्रवाई को अस्वीकार कर दिया गया है, क्योंकि सिस्टम उस स्थिति में नहीं है जिसमें कार्रवाई को पूरा किया जा सकता है. उदाहरण के लिए, मिटाई जाने वाली डायरेक्ट्री में कुछ फ़ाइलें मौजूद हैं या किसी फ़ाइल पर rmdir ऑपरेशन लागू किया गया है. समस्या ठीक किए बिना, फिर से कोशिश न करें.
10 ABORTED आम तौर पर, यह गड़बड़ी एक साथ कई अनुरोध मिलने की वजह से होती है. जैसे, सीक्वेंसर की जांच पूरी न हो पाना या लेन-देन रद्द होना. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें.
11 OUT_OF_RANGE यह कार्रवाई, मान्य सीमा से बाहर की गई है. जैसे, फ़ाइल के आखिर से आगे बढ़ना या पढ़ना. INVALID_ARGUMENT के उलट, इस गड़बड़ी से पता चलता है कि कोई ऐसी समस्या है जिसे सिस्टम की स्थिति बदलने पर ठीक किया जा सकता है. समस्या ठीक किए बिना, फिर से कोशिश न करें.
12 UNIMPLEMENTED यह ऑपरेशन लागू नहीं किया गया है या Drive API में यह सुविधा उपलब्ध/चालू नहीं है. फिर से कोशिश न करें.
13 INTERNAL सिस्टम की गड़बड़ियां. इससे पता चलता है कि सिस्टम में प्रोसेस करते समय कोई गड़बड़ी हुई है. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें.
14 UNAVAILABLE Drive API उपलब्ध नहीं है. यह एक अस्थायी समस्या है. इसे एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करके ठीक किया जा सकता है. ध्यान दें कि नॉन-आइटमपोटेंट कार्रवाइयों को फिर से आज़माना हमेशा सुरक्षित नहीं होता. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें.
15 DATA_LOSS डेटा को वापस नहीं पाया जा सकता या डेटा खराब हो गया. अपने सिस्टम एडमिन से संपर्क करें. अगर डेटा खो गया है या खराब हो गया है, तो सिस्टम एडमिन सहायता प्रतिनिधि से संपर्क कर सकता है.
16 UNAUTHENTICATED अनुरोध में, कार्रवाई के लिए पुष्टि करने वाले मान्य क्रेडेंशियल नहीं हैं. समस्या ठीक किए बिना, फिर से कोशिश न करें.