लंबे समय तक चलने वाला ऑपरेशन (एलआरओ), एपीआई का एक ऐसा तरीका है जिसे पूरा होने में, एपीआई रिस्पॉन्स के लिए ज़रूरी समय से ज़्यादा समय लगता है. आम तौर पर, टास्क के चलने के दौरान कॉलिंग थ्रेड को खुला नहीं रखना चाहिए, क्योंकि इससे उपयोगकर्ता को खराब अनुभव मिलता है. इसके बजाय, उपयोगकर्ता को कोई वादा करें और उसे बाद में वापस आने के लिए कहें.
Google Drive API, हर बार download()
तरीके को files
संसाधन पर कॉल करने पर, एक एलआरओ दिखाता है. ऐसा, Drive API या उसकी क्लाइंट लाइब्रेरी के ज़रिए किसी फ़ाइल का कॉन्टेंट डाउनलोड करने के लिए किया जाता है.
यह तरीका, क्लाइंट को operations
रिसोर्स दिखाता है. operations
रिसोर्स का इस्तेमाल करके, एपीआई के तरीके की स्थिति को असींक्रोनस तरीके से पाया जा सकता है. इसके लिए, get()
तरीके से ऑपरेशन को पोल किया जाता है. Drive API में मौजूद एलआरओ, Google Cloud के एलआरओ डिज़ाइन पैटर्न का पालन करते हैं.
ज़्यादा जानकारी के लिए, लंबे समय तक चलने वाले ऑपरेशन देखें.
प्रोसेस से जुड़ी खास जानकारी
नीचे दिए गए डायग्राम में, 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
) के तौर पर न दिख जाए. बड़ी फ़ाइलों के लिए, कई बार पोल करने की ज़रूरत पड़ सकती है. ज़्यादा जानकारी के लिए, लंबे समय तक चलने वाले ऑपरेशन के बारे में जानकारी पाना लेख पढ़ें.पूरा न होने की स्थिति देखना: अगर LRO से
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
क्वेरी पैरामीटर, डाउनलोड की जाने वाली फ़ाइल का रिविज़न आईडी होता है. यह सुविधा सिर्फ़ ब्लॉब फ़ाइलें, Google Docs, और Google Sheets डाउनलोड करते समय उपलब्ध होती है. काम न करने वाली फ़ाइलों पर किसी खास बदलाव को डाउनलोड करते समय, गड़बड़ी का कोडINVALID_ARGUMENT
दिखाता है.
download()
तरीका, Vids की फ़ाइलों को MP4 फ़ॉर्मैट में डाउनलोड करने का एकमात्र तरीका है. आम तौर पर, यह ज़्यादातर वीडियो फ़ाइलों को डाउनलोड करने के लिए सबसे सही होता है.
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 में किए गए बदलावों को, alt=media
यूआरएल के साथ get()
तरीके का इस्तेमाल करके डाउनलोड नहीं किया जा सकता . ऐसा न करने पर, यह 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 |
अनुरोध में, कार्रवाई के लिए पुष्टि करने वाले मान्य क्रेडेंशियल नहीं हैं. | समस्या ठीक किए बिना, फिर से कोशिश न करें. |