इस पेज पर बताया गया है कि REST प्रोटोकॉल की मदद से, Google Photos Library API के लिए, फिर से शुरू किए जा सकने वाले अपलोड के लिए अनुरोध कैसे करें. इस प्रोटोकॉल की मदद से, डेटा ट्रांसफ़र में किसी तरह की रुकावट आने पर अपलोड की प्रोसेस फिर से शुरू की जा सकती है.
अगर आप क्लाइंट लाइब्रेरी का इस्तेमाल करने वाले डेवलपर हैं, तो ध्यान रखें कि कुछ क्लाइंट लाइब्रेरी, फिर से शुरू किए जा सकने वाले अपलोड के लिए स्थानीय सहायता देती हैं.
फिर से शुरू किए जा सकने वाले अपलोड विकल्प का इस्तेमाल तब करें, जब:
- बड़ी फ़ाइलें अपलोड की जा रही हैं.
- नेटवर्क में रुकावट या ट्रांसमिशन की किसी अन्य सुविधा के काम न करने की संभावना ज़्यादा होती है. उदाहरण के लिए, अगर किसी मोबाइल ऐप्लिकेशन से फ़ाइल अपलोड की जा रही हो.
फिर से शुरू किए जा सकने वाले अपलोड, नेटवर्क के खराब होने पर आपके बैंडविथ के इस्तेमाल को कम कर सकते हैं, क्योंकि आपको शुरुआत में बड़े फ़ाइल अपलोड को रीस्टार्ट करने की ज़रूरत नहीं होती.
पहला चरण: अपलोड सेशन शुरू करना
https://photoslibrary.googleapis.com/v1/uploads पर POST अनुरोध भेजकर, फिर से शुरू किए जा सकने वाले अपलोड का सेशन शुरू करें. इस अनुरोध में लौटाए गए, फिर से शुरू किए जा सकने वाले अपलोड
यूआरएल का इस्तेमाल करके, फ़ाइल को अपलोड करें.
पोस्ट अनुरोध में नीचे दिए गए हेडर शामिल होने चाहिए:
| हेडर फ़ील्ड | |
|---|---|
Content-Length |
0 पर सेट करें, क्योंकि अनुरोध का मुख्य हिस्सा खाली है. |
X-Goog-Upload-Command |
start पर सेट करें. |
X-Goog-Upload-Content-Type |
फ़ाइल के mime प्रकार पर सेट करें, उदाहरण के लिए, image/jpeg. |
X-Goog-Upload-Protocol |
resumable पर सेट करें. |
X-Goog-Upload-Raw-Size |
ट्रांसफ़र किए जाने वाले फ़ाइल डेटा की कुल बाइट पर सेट करें. |
यहां पोस्ट अनुरोध का हेडर दिया गया है:
POST https://photoslibrary.googleapis.com/v1/uploads Authorization: Bearer oauth2-token Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: mime-type X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: bytes-of-file
दूसरा चरण: सेशन का यूआरएल सेव करना
अगर यह अनुरोध पूरा हो जाता है, तो पोस्ट अनुरोध एक 200 OK एचटीटीपी स्टेटस कोड दिखाता है. इसमें यह हेडर भी शामिल होता है.
X-Goog-Upload-URL: url-to-make-uploads-to X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes
हेडर फ़ील्ड x-goog-upload-chunk-granularity में, क्लाइंट के भेजे गए सभी डेटा हिस्सों के लिए बाइट अलाइनमेंट और साइज़ की जानकारी होती है. अगर एक से ज़्यादा हिस्सों में अपलोड किया जाता है, तो पिछले अपलोड को छोड़कर सभी अपलोड, इस वैल्यू के कई हिस्सों में किए जाने चाहिए. इसका मतलब है कि फ़ाइल की अपलोड बाइट
इस वैल्यू के साथ अलाइन होनी चाहिए. आखिरी हिस्से में, बचे हुए बाइट अपलोड किए जा सकते हैं.
हेडर फ़ील्ड X-Goog-Upload-URL में एक यूनीक यूआरएल होता है. इसका इस्तेमाल, बाकी सभी अनुरोधों के अपलोड को पूरा करने के लिए किया जाना चाहिए. फिर से शुरू किए जा सकने वाले इस सेशन के यूआरएल को कॉपी करें और सेव करें, ताकि आप बाद के अनुरोधों के लिए इसका इस्तेमाल कर सकें.
तीसरा चरण: फ़ाइल अपलोड करना
दोबारा शुरू किए जा सकने वाले सेशन में फ़ाइल अपलोड करने के दो तरीके हैं:
- एक ही अनुरोध में. आम तौर पर, यह तरीका सबसे अच्छा होता है, क्योंकि इसके लिए कम अनुरोधों की ज़रूरत होती है. साथ ही, इसकी परफ़ॉर्मेंस भी बेहतर होती है.
-
कई हिस्सों में. इस तरीके में, डेटा को छोटे-छोटे हिस्सों में भेजकर कई अनुरोधों के ज़रिए अपलोड किया जाता है. डेटा को
x-goog-upload-chunk-granularityके मल्टीपल में बांटा जाता है. अगर ज़रूरी हो, तो छोटे किए गए अनुरोधों को फिर से आज़माने की कोशिश की जा सकती है.इसका इस्तेमाल तब करें, जब:
- आपको किसी भी एक अनुरोध में ट्रांसफ़र किए गए डेटा की मात्रा को कम करना होगा. अलग-अलग अनुरोधों के लिए तय समयसीमा तय होने पर आपको ऐसा करना पड़ सकता है.
- आपको अपलोड की प्रोग्रेस दिखाने वाला एक कस्टमाइज़ किया गया इंडिकेटर दिखाना होगा.
- आपको यह जानने की ज़रूरत है कि डेटा को कब खारिज करना सुरक्षित होता है.
एक अनुरोध
अनुरोध करके फ़ाइल अपलोड करने के लिए:
- फिर से शुरू किए जा सकने वाले सेशन के यूआरएल के लिए,
POSTअनुरोध बनाएं. - अनुरोध के मुख्य हिस्से में फ़ाइल का डेटा जोड़ें.
यहां दिए गए एचटीटीपी हेडर जोड़ें:
Content-Length: फ़ाइल में बाइट की संख्या पर सेट करें.X-Goog-Upload-Command:upload, finalizeपर सेट करें.
अनुरोध भेजें.
अगर अपलोड करने के अनुरोध में रुकावट आती है या आपको 5xx
जवाब मिलता है, तो रोके गए अपलोड को फिर से शुरू करने के लिए दिया गया तरीका अपनाएं.
अगर अनुरोध पूरा हो जाता है, तो आपको जवाब के मुख्य हिस्से में 200 OK एचटीटीपी स्टेटस कोड और अपलोड टोकन मिलता है.
अपलोड टोकन का इस्तेमाल करके, मीडिया आइटम बनाएं.
एक से ज़्यादा हिस्से
फ़ाइल को अलग-अलग हिस्सों में अपलोड करने के लिए:
- फिर से शुरू किए जा सकने वाले सेशन के यूआरएल के लिए,
POSTअनुरोध बनाएं. -
समूह का डेटा, अनुरोध के मुख्य हिस्से में जोड़ें.
अपलोड को पूरा करने वाले आखिरी हिस्से को छोड़कर, स्वीकार किए गए हिस्सों के साइज़ के गुणज में दूसरे समूह बनाएं. समूह के साइज़ को जितना हो सके उतना बड़ा रखें, ताकि अपलोड बेहतर तरीके से हो सके.
-
यहां दिए गए एचटीटीपी हेडर जोड़ें:
Content-Length: हिस्से में बाइट की संख्या पर सेट करें.X-Goog-Upload-Command:uploadपर सेट करें. आखिरी हिस्से के लिए,upload, finalizeपर सेट करें.X-Goog-Upload-Offset: उस ऑफ़सेट पर सेट करें जिस पर बाइट लिखी जानी चाहिए. ध्यान दें कि बाइट क्रम से अपलोड की जानी चाहिए. पहला ऑफ़सेट0है.
- अनुरोध भेजें.
अगर अपलोड करने के अनुरोध में रुकावट आती है या आपको
5xxजवाब मिलता है, तो रोके गए अपलोड को फिर से शुरू करने के लिए दिया गया तरीका अपनाएं. - फ़ाइल में मौजूद हर बचे हुए हिस्से के लिए ऊपर दिया गया तरीका दोहराएं.
अगर अनुरोध पूरा हो जाता है, तो आपको जवाब के मुख्य हिस्से में 200 OK एचटीटीपी स्टेटस कोड और अपलोड टोकन मिलता है.
अपलोड टोकन का इस्तेमाल करके, मीडिया आइटम बनाएं.
उदाहरण
एक अनुरोध
नीचे दिए गए उदाहरण में, एक अनुरोध में 3,039,417-बाइट वाली JPEG फ़ाइल अपलोड करने के लिए फिर से शुरू किया जा सकने वाला अनुरोध दिखाया गया है.
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
जवाब में अपलोड यूआरएल और अनुमानित समूह का साइज़ शामिल है:
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
अपलोड करने का आखिरी अनुरोध:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 3039417 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 0 [BYTES 0-4199999]
एक से ज़्यादा हिस्से
नीचे दिए गए उदाहरण में, 3,039,417-बाइट वाली JPEG फ़ाइल को कई हिस्सों में अपलोड करने का फिर से शुरू किया जा सकने वाला अनुरोध दिखाया गया है. इसमें, फिर से शुरू किए जा सकने वाले सेशन के यूआरएल और पिछले चरण में स्वीकार किए गए डेटा ग्रुप के साइज़ की जानकारी का इस्तेमाल किया गया है.
इस उदाहरण में 262,144 बाइट के साइज़ वाले छोटे ग्रुप का इस्तेमाल किया गया है, जो
अपलोड सेशन शुरू होने पर हेडर फ़ील्ड
x-goog-upload-chunk-granularity में
दिखाया गया था. ध्यान दें कि हर अपलोड में ऐसे बाइट होते हैं
जो 2,62,144 के मल्टीपल में होती हैं.
पिछले चरण में बताए गए तरीके से, अपलोड का यूआरएल और हिस्से का साइज़ पाने के लिए, अपलोड सेशन शुरू करें:
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
जवाब में अपलोड यूआरएल और अनुमानित समूह का साइज़ शामिल है:
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
पहला हिस्सा:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 0 [BYTES 0-1048575]
दूसरा हिस्सा:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 1048576 [BYTES 1048576-2097151]
पिछला हिस्सा:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 942265 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 2097152 [BYTES 2097152-4200000]
रोके गए अपलोड को फिर से शुरू करना
अगर अपलोड करने के अनुरोध में रुकावट आ जाती है या आपको बिना 200 वाला एचटीटीपी स्टेटस कोड मिलता है, तो सर्वर से क्वेरी करके पता लगाएं कि कितना अपलोड हो सका.
फिर से शुरू किए जा सकने वाले सेशन यूआरएल के लिए, यह POST अनुरोध है. X-Goog-Upload-Command
को query पर सेट किया जाना चाहिए.
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: query
सर्वर से मिलने वाले रिस्पॉन्स में, एक 200 OK एचटीटीपी स्टेटस कोड और अपलोड का मौजूदा साइज़ शामिल होता है.
HTTP/1.1 200 OK X-Goog-Upload-Status: active X-Goog-Upload-Size-Received: 100
इसके बाद, इस ऑफ़सेट से फिर से अपलोड करना शुरू किया जा सकता है. आपको सर्वर से दिए गए ऑफ़सेट पर फिर से शुरू करना होगा. हालांकि, इसके लिए ज़रूरी है कि दोनों को एक साथ अपलोड करने और निर्देश देने की प्रोसेस पूरी न की जाए. इस स्थिति में, ऑफ़सेट 0 पर भी फिर से शुरू किया जा सकता है.
अगर आपकी क्वेरी कमांड के एचटीटीपी रिस्पॉन्स में X-Goog-Upload-Status हेडर मौजूद है और वैल्यू active नहीं है, तो इसका मतलब है कि अपलोड को पहले ही बंद किया जा चुका है.