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

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

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

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

लंबे समय तक चलने वाली कार्रवाइयां, ऐसे तरीके होते हैं जिन्हें पूरा होने में काफ़ी समय लग सकता है. आम तौर पर, डाउनलोड करने की नई कार्रवाइयों को शुरू में 'लंबित' स्थिति (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 HTTP स्‍थिति कोड ब्यौरा सुझाई गई कार्रवाई
1 CANCELLED 499 Client Closed Request कार्रवाई रद्द कर दी गई थी. आम तौर पर, ऐसा कॉल करने वाला व्यक्ति करता है. कार्रवाई को फिर से चलाएं.
2 UNKNOWN 500 Internal Server Error यह गड़बड़ी तब दिख सकती है, जब किसी दूसरे पते के स्पेस से मिली Status वैल्यू, किसी ऐसे गड़बड़ी वाले स्पेस से जुड़ी हो जिसके बारे में इस पते के स्पेस में जानकारी न हो. अगर एपीआई की गड़बड़ी से पूरी जानकारी नहीं मिलती है, तो हो सकता है कि गड़बड़ी को इस गड़बड़ी में बदल दिया जाए. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें.
3 INVALID_ARGUMENT 400 Bad Request क्लाइंट ने एक अमान्य तर्क बताया. यह गड़बड़ी, FAILED_PRECONDITION से अलग है. INVALID_ARGUMENT ऐसे तर्कों के बारे में बताता है जिनमें सिस्टम की स्थिति से कोई फ़र्क़ नहीं पड़ता. जैसे, गलत फ़ाइल नाम. समस्या ठीक किए बिना, फिर से कोशिश न करें.
4 DEADLINE_EXCEEDED 504 Gateway Timeout कार्रवाई पूरी होने से पहले ही समयसीमा खत्म हो गई. सिस्टम की स्थिति में बदलाव करने वाली कार्रवाइयों के लिए, यह गड़बड़ी तब भी दिख सकती है, जब कार्रवाई पूरी हो गई हो. उदाहरण के लिए, किसी सर्वर से मिला सही जवाब, समयसीमा खत्म होने के बाद मिला हो. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें.
5 NOT_FOUND 404 Not Found अनुरोध की गई कुछ इकाइयां, जैसे कि FHIR संसाधन नहीं मिला. समस्या ठीक किए बिना, फिर से कोशिश न करें.
6 ALREADY_EXISTS 409 Conflict क्लाइंट ने जिस इकाई को बनाने की कोशिश की है वह पहले से मौजूद है. जैसे, DICOM इंस्टेंस. समस्या ठीक किए बिना, फिर से कोशिश न करें.
7 PERMISSION_DENIED 403 Forbidden कॉलर के पास, तय की गई कार्रवाई को पूरा करने की अनुमति नहीं है. इस गड़बड़ी के कोड का मतलब यह नहीं है कि अनुरोध मान्य है, अनुरोध की गई इकाई मौजूद है या यह अन्य ज़रूरी शर्तों को पूरा करती है. समस्या ठीक किए बिना, फिर से कोशिश न करें.
8 RESOURCE_EXHAUSTED 429 Too Many Requests किसी संसाधन का इस्तेमाल पूरी तरह से हो गया है. जैसे, हर प्रोजेक्ट के लिए तय किया गया कोटा. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें. समय के साथ, कोटा उपलब्ध हो सकता है.
9 FAILED_PRECONDITION 400 Bad Request इस कार्रवाई को अस्वीकार कर दिया गया है, क्योंकि सिस्टम उस स्थिति में नहीं है जिसमें कार्रवाई को पूरा किया जा सकता है. उदाहरण के लिए, मिटाई जाने वाली डायरेक्ट्री में कुछ फ़ाइलें मौजूद हैं या किसी फ़ाइल पर rmdir ऑपरेशन लागू किया गया है. समस्या ठीक किए बिना, फिर से कोशिश न करें.
10 ABORTED 409 Conflict यह कार्रवाई रोक दी गई है. आम तौर पर, ऐसा एक साथ कई अनुरोध आने की वजह से होता है. जैसे, सीक्वेंसर की जांच पूरी न हो पाना या लेन-देन रुक जाना. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें.
11 OUT_OF_RANGE 400 Bad Request यह कार्रवाई, मान्य सीमा से बाहर की गई है. जैसे, फ़ाइल के आखिर से आगे बढ़ना या पढ़ना. INVALID_ARGUMENT के उलट, इस गड़बड़ी से पता चलता है कि कोई ऐसी समस्या है जिसे सिस्टम की स्थिति बदलने पर ठीक किया जा सकता है. समस्या ठीक किए बिना, फिर से कोशिश न करें.
12 UNIMPLEMENTED 501 Not Implemented यह ऑपरेशन लागू नहीं किया गया है या Drive API में यह सुविधा उपलब्ध/चालू नहीं है. फिर से कोशिश न करें.
13 INTERNAL 500 Internal Server Error सिस्टम की गड़बड़ियां. इससे पता चलता है कि सिस्टम में प्रोसेस करते समय कोई गड़बड़ी हुई है. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें.
14 UNAVAILABLE 503 Service Unavailable Drive API उपलब्ध नहीं है. यह एक अस्थायी समस्या है. इसे एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करके ठीक किया जा सकता है. ध्यान दें कि नॉन-आइटमपोटेंट कार्रवाइयों को फिर से आज़माना हमेशा सुरक्षित नहीं होता. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें.
15 DATA_LOSS 500 Internal Server Error डेटा को वापस नहीं पाया जा सकता या डेटा खराब हो गया. अपने सिस्टम एडमिन से संपर्क करें. अगर डेटा खो गया है या खराब हो गया है, तो सिस्टम एडमिन सहायता प्रतिनिधि से संपर्क कर सकता है.
16 UNAUTHENTICATED 401 Unauthorized अनुरोध में, कार्रवाई के लिए पुष्टि करने वाले मान्य क्रेडेंशियल नहीं हैं. समस्या ठीक किए बिना, फिर से कोशिश न करें.