लॉन्ग-रनिंग ऑपरेशन (एलआरओ), एक ऐसा एपीआई तरीका है जिसे पूरा होने में, एपीआई रिस्पॉन्स के लिए तय किए गए समय से ज़्यादा समय लगता है. आम तौर पर, आपको टास्क के चलने के दौरान कॉलिंग थ्रेड को खुला नहीं रखना चाहिए, क्योंकि इससे उपयोगकर्ता को खराब अनुभव मिलता है. इसके बजाय, उपयोगकर्ता को किसी तरह का भरोसा दिलाना बेहतर होता है. साथ ही, उसे कुछ समय बाद फिर से जांच करने की अनुमति दें.
Google Drive API, files
रिसॉर्स पर download
तरीके को कॉल करने पर, हर बार एक एलआरओ दिखाता है. इससे Drive API या इसकी क्लाइंट लाइब्रेरी के ज़रिए, किसी फ़ाइल का कॉन्टेंट डाउनलोड किया जा सकता है.
यह तरीका, क्लाइंट को operations
संसाधन दिखाता है. get
तरीके से ऑपरेशन को पोल करके, एपीआई के तरीके की स्थिति को एसिंक्रोनस तरीके से वापस पाने के लिए, operations
संसाधन का इस्तेमाल किया जा सकता है. Drive API में LRO, Google Cloud LRO के डिज़ाइन पैटर्न के मुताबिक काम करते हैं.
ज़्यादा जानकारी के लिए, लंबे समय तक चलने वाले ऑपरेशन देखें.
प्रोसेस से जुड़ी खास जानकारी
नीचे दिए गए डायग्राम में, file.download
तरीके के काम करने के तरीके के बारे में खास जानकारी दी गई है.
कॉल
files.download
: जब आपका ऐप्लिकेशनdownload
तरीके को कॉल करता है, तो यह फ़ाइल के लिए Drive API डाउनलोड करने का अनुरोध लॉन्च करता है. ज़्यादा जानकारी के लिए, फ़ाइलें डाउनलोड करना लेख पढ़ें.अनुमतियों का अनुरोध करना: इस अनुरोध में, Drive API को पुष्टि करने के क्रेडेंशियल भेजे जाते हैं. अगर आपके ऐप्लिकेशन को Drive API को कॉल करने के लिए, उपयोगकर्ता के ऐसे क्रेडेंशियल की ज़रूरत है जिसे अब तक अनुमति नहीं मिली है, तो ऐप्लिकेशन उपयोगकर्ता को साइन इन करने के लिए कहता है. आपका ऐप्लिकेशन, स्कोप के साथ ऐक्सेस करने का अनुरोध भी करता है. ये स्कोप, पुष्टि करने की सुविधा सेट अप करते समय तय किए जाते हैं.
डाउनलोड शुरू करें: फ़ाइल डाउनलोड करने की प्रोसेस शुरू करने के लिए, Drive API से अनुरोध किया जाता है. यह अनुरोध, Google Vids या Google Workspace के किसी अन्य कॉन्टेंट के लिए किया जा सकता है.
एलआरओ शुरू करें: एक लंबी प्रोसेस शुरू होती है और यह डाउनलोड प्रोसेस को मैनेज करती है.
लंबित कार्रवाई की जानकारी: Drive API, लंबित कार्रवाई की जानकारी दिखाता है. इसमें अनुरोध करने वाले उपयोगकर्ता और फ़ाइल के मेटाडेटा के कई फ़ील्ड के बारे में जानकारी होती है.
शुरुआती तौर पर मंज़ूरी बाकी है: आपके ऐप्लिकेशन को, मंज़ूरी बाकी होने की जानकारी मिलती है. साथ ही,
done=null
के तौर पर मंज़ूरी बाकी होने की शुरुआती स्थिति दिखती है. इससे पता चलता है कि फ़ाइल अभी डाउनलोड के लिए तैयार नहीं है और ऑपरेशन का स्टेटस 'लंबित है' है.operations.get
को कॉल करें और नतीजे की पुष्टि करें: आपका ऐप्लिकेशन,get
को सुझाए गए इंटरवल पर कॉल करता है, ताकि ऑपरेशन के नतीजे को पोल किया जा सके. साथ ही, लंबे समय तक चलने वाले ऑपरेशन की मौजूदा स्थिति के बारे में जानकारी मिल सके. अगरdone=false
की स्थिति 'कार्रवाई पूरी नहीं हुई' के तौर पर दिखती है, तो आपके ऐप्लिकेशन को तब तक पोलिंग जारी रखनी होगी, जब तक कार्रवाई पूरी नहीं हो जाती (done=true
). बड़ी फ़ाइलों के लिए, आपको कई बार पोलिंग करनी पड़ सकती है. ज़्यादा जानकारी के लिए, लंबे समय तक चलने वाले ऑपरेशन के बारे में जानकारी पाना लेख पढ़ें.'कार्रवाई पूरी नहीं हुई' स्थिति की जांच करें: अगर एलआरओ से
done=true
की 'कार्रवाई पूरी नहीं हुई' स्थिति मिलती है, तो इसका मतलब है कि फ़ाइल डाउनलोड के लिए तैयार है और ऑपरेशन की स्थिति 'पूरी हो गई' है.डाउनलोड यूआरआई के साथ पूरा हो चुका ऑपरेशन वापस पाएं: एलआरओ पूरा होने के बाद, 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 | application/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
}
}
इस आउटपुट में ये वैल्यू शामिल होती हैं:
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');
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 |
अनुरोध में, कार्रवाई के लिए पुष्टि करने वाले मान्य क्रेडेंशियल नहीं हैं. | समस्या ठीक किए बिना, फिर से कोशिश न करें. |