मीडिया फ़ाइल अपलोड करें

मीडिया अपलोड करने की सुविधा, Campaign Manager 360 API को क्लाउड में डेटा स्टोर करने और उसे सर्वर पर उपलब्ध कराने की अनुमति देती है. फ़ोटो, वीडियो, PDF फ़ाइलें, ज़िप फ़ाइलें या अन्य तरह का डेटा अपलोड करने के लिए, आपको जो डेटा चाहिए उसे शामिल किया जा सकता है.

इस दस्तावेज़ में दिए गए उदाहरणों में, काल्पनिक Farm API के लिए मीडिया अपलोड का इस्तेमाल दिखाया गया है. हालांकि, यही सिद्धांत Campaign Manager 360 API पर भी लागू होते हैं.

अपलोड के विकल्प

Campaign Manager 360 API की मदद से, कुछ खास तरह के बाइनरी डेटा या मीडिया को अपलोड किया जा सकता है. मीडिया अपलोड करने की सुविधा वाले किसी भी तरीके के लिए, रेफ़रंस पेज पर अपलोड किए जा सकने वाले डेटा की खास विशेषताओं के बारे में बताया गया है:

  • अपलोड की जा सकने वाली फ़ाइल का ज़्यादा से ज़्यादा साइज़: इस तरीके से, ज़्यादा से ज़्यादा कितना डेटा स्टोर किया जा सकता है.
  • स्वीकार किए गए मीडिया MIME टाइप: इस तरीके का इस्तेमाल करके, बाइनरी डेटा के वे टाइप जिन्हें स्टोर किया जा सकता है.

अपलोड करने के अनुरोध इनमें से किसी भी तरीके से किए जा सकते हैं. uploadType अनुरोध पैरामीटर के साथ इस्तेमाल किया जा रहा तरीका बताएं.

  • सरल अपलोड: uploadType=media. छोटी फ़ाइलों को तुरंत ट्रांसफ़र करने के लिए, जैसे कि पांच एमबी या इससे कम साइज़ की फ़ाइलें.
  • मल्टीपार्ट अपलोड: uploadType=multipart. छोटी फ़ाइलों और मेटाडेटा को तुरंत ट्रांसफ़र करने के लिए. यह एक ही अनुरोध में, फ़ाइल के साथ-साथ उसके बारे में बताने वाले मेटाडेटा को भी ट्रांसफ़र करता है.
  • फिर से शुरू किया जा सकने वाला अपलोड: uploadType=resumable. फ़ाइल ट्रांसफ़र करने के लिए, यह ज़रूरी है. खास तौर पर, बड़ी फ़ाइलों के लिए यह ज़रूरी है. इस तरीके में, सेशन शुरू करने के अनुरोध का इस्तेमाल किया जाता है. इसमें मेटाडेटा शामिल किया जा सकता है. हालांकि, ऐसा करना ज़रूरी नहीं है. ज़्यादातर ऐप्लिकेशन के लिए, यह एक अच्छी रणनीति है. इसकी मदद से, छोटी फ़ाइलों को भी अपलोड किया जा सकता है. हालांकि, इसके लिए हर अपलोड के लिए एक अतिरिक्त एचटीटीपी अनुरोध करना पड़ता है.

मीडिया अपलोड करते समय, एक खास यूआरआई का इस्तेमाल किया जाता है. असल में, मीडिया अपलोड करने की सुविधा वाले तरीकों में दो यूआरआई एंडपॉइंट होते हैं:

  • मीडिया के लिए, /upload यूआरआई. अपलोड एंडपॉइंट का फ़ॉर्मैट “/upload” प्रीफ़िक्स के साथ स्टैंडर्ड रिसॉर्स यूआरआई. मीडिया डेटा को खुद ट्रांसफ़र करते समय, इस यूआरआई का इस्तेमाल करें.

    उदाहरण: POST /upload/farm/v1/animals

  • मेटाडेटा के लिए स्टैंडर्ड रिसॉर्स यूआरआई. अगर संसाधन में कोई डेटा फ़ील्ड, उन फ़ील्ड का इस्तेमाल अपलोड किए गए डेटा की जानकारी देने वाले मेटाडेटा को स्टोर करने के लिए किया जाता है फ़ाइल से लिए जाते हैं. मेटाडेटा वैल्यू बनाते या अपडेट करते समय, इस यूआरआई का इस्तेमाल किया जा सकता है.

    उदाहरण: POST /farm/v1/animals

आसान अपलोड

फ़ाइल अपलोड करने का सबसे आसान तरीका, बस अपलोड का अनुरोध करना है. यह विकल्प तब चुनें, जब:

  • फ़ाइल इतनी छोटी हो कि अगर इंटरनेट कनेक्शन टूट जाए, तो उसे फिर से पूरी तरह से अपलोड किया जा सके.
  • भेजने के लिए कोई मेटाडेटा नहीं है. ऐसा तब हो सकता है, जब आपके पास इस संसाधन के लिए मेटाडेटा को अलग अनुरोध में भेजने का विकल्प हो या कोई मेटाडेटा काम न कर रहा हो या उपलब्ध न हो.

आसानी से अपलोड करने के लिए, POST या PUT का अनुरोध करें तरीके का /upload यूआरआई और क्वेरी पैरामीटर जोड़ें uploadType=media. उदाहरण के लिए:

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=media

आसानी से अपलोड करने का अनुरोध करते समय, इन एचटीटीपी हेडर का इस्तेमाल किया जा सकता है:

उदाहरण: आसानी से अपलोड करना

नीचे दिए गए उदाहरण में, काल्पनिक Farm API.

POST /upload/farm/v1/animals?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/jpeg
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

JPEG data

अगर अनुरोध पूरा होता है, तो सर्वर किसी भी मेटाडेटा के साथ एचटीटीपी 200 OK स्टेटस कोड दिखाता है:

HTTP/1.1 200
Content-Type: application/json

{
  "name": "Llama"
}

मल्टीपार्ट अपलोड

अगर आपके पास ऐसा मेटाडेटा है जिसे आपको अपलोड किए जाने वाले डेटा के साथ भेजना है, तो एक multipart/related अनुरोध किया जा सकता है. अगर भेजा जा रहा डेटा इतना छोटा है कि कनेक्शन टूटने पर उसे फिर से पूरा अपलोड किया जा सकता है, तो यह एक अच्छा विकल्प है.

एक से ज़्यादा फ़ाइलें अपलोड करने की सुविधा का इस्तेमाल करने के लिए, /upload यूआरआई वाले तरीके के लिए POST या PUT अनुरोध करें. साथ ही, क्वेरी पैरामीटर uploadType=multipart जोड़ें. उदाहरण के लिए:

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=multipart

एक से ज़्यादा हिस्सों वाले अपलोड का अनुरोध करते समय, इन टॉप लेवल एचटीटीपी हेडर का इस्तेमाल किया जाएगा:

  • Content-Type. एक से ज़्यादा हिस्सों/मिलते-जुलते हिस्से पर सेट करें और उस बाउंड्री स्ट्रिंग को शामिल करें जिसका इस्तेमाल, अनुरोध के हिस्सों की पहचान करने के लिए किया जा रहा है.
  • Content-Length. इसे अनुरोध के मुख्य हिस्से में मौजूद बाइट की कुल संख्या पर सेट करें. अनुरोध का मीडिया हिस्सा, इस तरीके के लिए तय किए गए फ़ाइल के ज़्यादा से ज़्यादा साइज़ से कम होना चाहिए.

अनुरोध के मुख्य हिस्से को multipart/related कॉन्टेंट टाइप [RFC2387] के तौर पर फ़ॉर्मैट किया गया है. इसमें सिर्फ़ दो हिस्से शामिल हैं. हिस्सों की पहचान सीमा स्ट्रिंग से की जाती है और आखिरी सीमा स्ट्रिंग के बाद दो हाइफ़न होते हैं.

कई हिस्सों वाले अनुरोध के हर हिस्से के लिए, एक अतिरिक्त Content-Type हेडर की ज़रूरत होती है:

  1. मेटाडेटा का हिस्सा: यह सबसे पहले होना चाहिए. साथ ही, Content-Type को स्वीकार किए गए मेटाडेटा फ़ॉर्मैट में से किसी एक से मैच करना चाहिए.
  2. मीडिया का हिस्सा: दूसरा होना चाहिए. साथ ही, Content-Type को ऐसे मीडिया MIME टाइप से मेल खाना चाहिए जिसे तरीके से स्वीकार किया जाता है.

अपलोड की गई फ़ाइलों के लिए, स्वीकार किए जाने वाले मीडिया MIME टाइप और साइज़ की सीमाओं की सूची के लिए, हर तरीके का एपीआई रेफ़रंस देखें.

ध्यान दें: सिर्फ़ मेटाडेटा का हिस्सा बनाने या अपडेट करने के लिए, उससे जुड़ा डेटा अपलोड किए बिना, स्टैंडर्ड रिसॉर्स एंडपॉइंट पर POST या PUT अनुरोध भेजें: https://www.googleapis.com/farm/v1/animals

उदाहरण: एक से ज़्यादा हिस्सों वाला अपलोड

यहां दिए गए उदाहरण में, काल्पनिक Farm API के लिए, एक से ज़्यादा फ़ाइलें अपलोड करने का अनुरोध दिखाया गया है.

POST /upload/farm/v1/animals?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "name": "Llama"
}

--foo_bar_baz
Content-Type: image/jpeg

JPEG data
--foo_bar_baz--

अनुरोध पूरा होने पर, सर्वर किसी भी मेटाडेटा के साथ एचटीटीपी 200 OK स्टेटस कोड दिखाता है:

HTTP/1.1 200
Content-Type: application/json

{
  "name": "Llama"
}

फिर से अपलोड किया जा सकता है

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

फिर से शुरू किए जाने लायक अपलोड का इस्तेमाल करने के चरणों में ये शामिल हैं:

  1. फिर से शुरू किया जा सकने वाला सेशन शुरू करें. अगर कोई मेटाडेटा हो, तो अपलोड यूआरआई के लिए शुरुआती अनुरोध करें.
  2. फिर से शुरू किए जा सकने वाले सेशन का यूआरआई सेव करें. शुरुआती अनुरोध के रिस्पॉन्स में दिए गए सेशन यूआरआई को सेव करें; इसका इस्तेमाल, इस सेशन के बचे हुए अनुरोधों के लिए किया जाएगा.
  3. फ़ाइल अपलोड करें. मीडिया फ़ाइल को फिर से शुरू किए जाने लायक सेशन यूआरआई पर भेजें.

इसके अलावा, फिर से शुरू किए जा सकने वाले अपलोड का इस्तेमाल करने वाले ऐप्लिकेशन में, बाधित अपलोड को फिर से शुरू करने के लिए कोड होना चाहिए. अगर अपलोड बीच में रुक जाता है, तो पता लगाएं कि कितना डेटा अपलोड हो गया था. इसके बाद, उसी जगह से अपलोड फिर से शुरू करें.

ध्यान दें: अपलोड यूआरआई एक हफ़्ते बाद खत्म हो जाता है.

पहला चरण: फिर से शुरू किया जा सकने वाला सेशन शुरू करना

फिर से शुरू करने लायक अपलोड शुरू करने के लिए, तरीके के /upload यूआरआई के लिए POST या PUT अनुरोध करें और क्वेरी पैरामीटर जोड़ें uploadType=resumable, उदाहरण के लिए:

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable

शुरुआती अनुरोध के लिए, मुख्य हिस्सा खाली होता है या इसमें सिर्फ़ मेटाडेटा होता है. आपको बाद के अनुरोधों में, उस फ़ाइल का असल कॉन्टेंट ट्रांसफ़र करना होगा जिसे अपलोड करना है.

शुरुआती अनुरोध के साथ, इन एचटीटीपी हेडर का इस्तेमाल करें:

  • X-Upload-Content-Type. बाद के अनुरोधों में ट्रांसफ़र किए जाने वाले अपलोड किए गए डेटा के मीडिया MIME टाइप पर सेट करें.
  • X-Upload-Content-Length. इसकी वैल्यू, अपलोड किए गए उस डेटा के बाइट की संख्या पर सेट करें जिसे बाद के अनुरोधों में ट्रांसफ़र करना है. अगर अनुरोध करते समय लंबाई की जानकारी नहीं है, तो इस हेडर को छोड़ा जा सकता है.
  • अगर मेटाडेटा दिया जा रहा है, तो: Content-Type. मेटाडेटा के डेटा टाइप के हिसाब से सेट किया जाता है.
  • Content-Length. इस शुरुआती अनुरोध के मुख्य हिस्से में दी गई बाइट की संख्या पर सेट करें. अगर इकट्ठा किए गए ट्रांसफ़र को कोड में बदलने के तरीके का इस्तेमाल किया जा रहा है, तो यह ज़रूरी नहीं है.

अपलोड की गई फ़ाइलों के लिए, स्वीकार किए जाने वाले मीडिया MIME टाइप और साइज़ की सीमाओं की सूची के लिए, हर तरीके का एपीआई रेफ़रंस देखें.

उदाहरण: सेशन को फिर से शुरू करने का अनुरोध

इस उदाहरण में, काल्पनिक Farm API के लिए, फिर से शुरू किया जा सकने वाला सेशन शुरू करने का तरीका बताया गया है.

POST /upload/farm/v1/animals?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: image/jpeg
X-Upload-Content-Length: 2000000

{
  "name": "Llama"
}

ध्यान दें: मेटाडेटा के बिना, फिर से शुरू किए जा सकने वाले अपडेट के शुरुआती अनुरोध के लिए, अनुरोध का मुख्य हिस्सा खाली छोड़ें और Content-Length हेडर को 0 पर सेट करें.

अगले सेक्शन में, रिस्पॉन्स को मैनेज करने का तरीका बताया गया है.

दूसरा चरण: फिर से शुरू किए जा सकने वाले सेशन का यूआरआई सेव करना

अगर सेशन शुरू करने का अनुरोध पूरा हो जाता है, तो एपीआई सर्वर एक 200 OK एचटीटीपी स्टेटस कोड के साथ जवाब देता है. इसके अलावा, यह एक Location हेडर भी उपलब्ध कराता है, जो फिर से शुरू किए जा सकने वाले सेशन का यूआरआई बताता है. नीचे दिए गए उदाहरण में दिखाया गया Location हेडर, upload_id क्वेरी पैरामीटर का एक हिस्सा शामिल करता है. इससे इस सेशन के लिए इस्तेमाल करने के लिए, यूनीक अपलोड आईडी मिलता है.

उदाहरण: फिर से शुरू किए जा सकने वाले सेशन शुरू करने का जवाब

पहले चरण में किए गए अनुरोध का जवाब यहां दिया गया है:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

ऊपर दिए गए उदाहरण के मुताबिक, Location हेडर की वैल्यू सेशन यूआरआई है. फ़ाइल को अपलोड करने या अपलोड के स्टेटस से जुड़ी क्वेरी के लिए, एचटीटीपी एंडपॉइंट के तौर पर इसका इस्तेमाल किया जाएगा.

सेशन यूआरआई को कॉपी करके सेव करें, ताकि आप बाद के अनुरोधों के लिए इसका इस्तेमाल कर सकें.

चरण 3: फ़ाइल अपलोड करें

फ़ाइल अपलोड करने के लिए, पिछले चरण में मिले अपलोड यूआरआई पर PUT अनुरोध भेजें. अपलोड करने के अनुरोध का फ़ॉर्मैट:

PUT session_uri

फ़ाइल अपलोड करने के ऐसे अनुरोध करते समय इस्तेमाल किए जाने वाले एचटीटीपी हेडर में Content-Length शामिल होता है. इसे इस अनुरोध में अपलोड किए जाने वाले बाइट की संख्या पर सेट करें, जो आम तौर पर अपलोड की जाने वाली फ़ाइल का साइज़ होता है.

उदाहरण: फ़ाइल अपलोड करने का अनुरोध, जिसे फिर से शुरू किया जा सकता है

यहां मौजूदा उदाहरण के लिए, पूरी 20,00,000 बाइट वाली JPEG फ़ाइल को अपलोड करने का एक फिर से शुरू किया जा सकने वाला अनुरोध दिया गया है.

PUT https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/jpeg

bytes 0-1999999

अनुरोध पूरा होने पर, सर्वर इस संसाधन से जुड़े किसी भी मेटाडेटा के साथ HTTP 201 Created का जवाब देता है. अगर फिर से शुरू किए जाने वाले सेशन का शुरुआती अनुरोध, PUT से किया गया था, तो किसी मौजूदा संसाधन को अपडेट करने के लिए, इस संसाधन से जुड़े मेटाडेटा के साथ-साथ 200 OK को रिस्पॉन्स मिलेगा.

अगर अपलोड के अनुरोध में रुकावट आती है या आपको सर्वर से HTTP 503 Service Unavailable या कोई अन्य 5xx जवाब मिलता है, तो रुका हुआ अपलोड फिर से शुरू करना में बताए गए तरीके का पालन करें.  

फ़ाइल को हिस्सों में अपलोड करना

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

अगर डेटा को हिस्सों में अपलोड किया जा रहा है, तो Content-Range हेडर के साथ-साथ Content-Length हेडर की भी ज़रूरत होगी, जो पूरी फ़ाइल अपलोड करने के लिए ज़रूरी है:

  • Content-Length. डेटा को डेटा सेगमेंट पर या उससे कम पर सेट करें. ऐसा पिछले अनुरोध के मामले में भी हो सकता है.
  • Content-Range: यह दिखाने के लिए सेट करें कि आपकी अपलोड की जा रही फ़ाइल में कौन-कौनसी बाइट अपलोड की जा रही हैं.  उदाहरण के लिए, Content-Range: bytes 0-524287/2000000 से पता चलता है कि 2,000,000 बाइट की फ़ाइल में, पहले 5,24,288 बाइट (256 x 1024 x 2) दिए जा रहे हैं.

डेटा वाले हिस्से का साइज़ से जुड़ी पाबंदी: सभी डेटा का साइज़ 256 केबी (256 x 1024 बाइट) से ज़्यादा नहीं होना चाहिए. हालांकि, डेटा अपलोड करने के बाद डेटा का वह हिस्सा कुछ ही होना चाहिए. अगर डेटा को अलग-अलग हिस्सों में बांटकर अपलोड किया जा रहा है, तो अपलोड की प्रोसेस को बेहतर बनाने के लिए, चंक्स का साइज़ जितना हो सके उतना बड़ा रखें.

उदाहरण: कई फ़ाइलों को अपलोड करने के अनुरोध को फिर से शुरू किया जा सकता है

पहला 5,24,288 बाइट भेजने वाला अनुरोध कुछ ऐसा दिख सकता है:

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: image/jpeg
Content-Range: bytes 0-524287/2000000

bytes 0-524288

अगर अनुरोध पूरा हो जाता है, तो सर्वर 308 Resume Incomplete के साथ जवाब देता है. साथ ही, Range हेडर भी दिखाता है जो अब तक सेव की गई बाइट की कुल संख्या की पहचान करता है:

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-524287

अगले चंक को कहां से शुरू करना है, यह तय करने के लिए Range हेडर में दी गई ऊपरी वैल्यू का इस्तेमाल करें. फ़ाइल के हर हिस्से को तब तक PUT करते रहें, जब तक पूरी फ़ाइल अपलोड न हो जाए.

अगर किसी चंक के PUT अनुरोध में रुकावट आती है या आपको सर्वर से एचटीटीपी 503 Service Unavailable या कोई अन्य 5xx रिस्पॉन्स मिलता है, तो रुकी हुई अपलोड की प्रोसेस फिर से शुरू करें में बताए गए तरीके का पालन करें. हालांकि, बाकी फ़ाइल को अपलोड करने के बजाय, उस जगह से चंक अपलोड करना जारी रखें.

अहम जानकारी:

  • अगले चंक को कहां से शुरू करना है, यह तय करने के लिए रिस्पॉन्स में Range हेडर का इस्तेमाल करना न भूलें. यह मत मानें कि सर्वर को पिछले अनुरोध में भेजे गए सभी बाइट मिले हैं.
  • हर अपलोड यूआरआई की समयसीमा तय होती है. अगर इसका इस्तेमाल नहीं किया जाता है, तो यह एक दिन या उससे ज़्यादा समय में खत्म हो जाता है. इस वजह से, अपलोड यूआरआई मिलते ही फिर से शुरू करने लायक अपलोड शुरू करना बेहतर होता है. साथ ही, रुकावट आने के कुछ समय बाद ही रोके गए अपलोड को फिर से शुरू किया जा सकता है.
  • अगर अपलोड सेशन के खत्म हो चुके आईडी के साथ अनुरोध भेजा जाता है, तो सर्वर 404 Not Found स्टेटस कोड दिखाता है. जब अपलोड सेशन के दौरान कोई ऐसी गड़बड़ी होती है जिसे ठीक नहीं किया जा सकता, तो सर्वर एक 410 Gone स्टेटस कोड दिखाता है. इन मामलों में, आपको फिर से शुरू किया जा सकने वाला नया अपलोड शुरू करना होगा, एक नया अपलोड यूआरआई हासिल करना होगा और नए एंडपॉइंट का इस्तेमाल करके, शुरुआत से अपलोड शुरू करना होगा.

फ़ाइल पूरी तरह से अपलोड हो जाने पर, सर्वर इस संसाधन से जुड़े किसी भी मेटाडेटा के साथ HTTP 201 Created का जवाब देता है. अगर यह अनुरोध, नई इकाई बनाने के बजाय किसी मौजूदा इकाई को अपडेट कर रहा था, तो अपलोड पूरा होने पर एचटीटीपी रिस्पॉन्स कोड 200 OK होता.

जो अपलोड पूरा नहीं हुआ उसे फिर से शुरू करें

अगर अपलोड का अनुरोध, जवाब मिलने से पहले ही खत्म हो जाता है या आपको सर्वर से एचटीटीपी 503 Service Unavailable रिस्पॉन्स मिलता है, तो आपको बीच में रुके हुए अपलोड को फिर से शुरू करना होगा. ऐसा करने के लिए:

  1. अनुरोध की स्थिति. अपलोड के मौजूदा स्टेटस की जानकारी पाने के लिए, अपलोड यूआरआई पर खाली PUT अनुरोध करें. इस अनुरोध के लिए, एचटीटीपी हेडर में Content-Range हेडर शामिल होना चाहिए. इससे पता चलता है कि फ़ाइल में मौजूदा स्थिति की जानकारी नहीं है.  उदाहरण के लिए, अगर आपकी फ़ाइल की कुल लंबाई 2,000,000 है, तो Content-Range को */2000000 पर सेट करें. अगर आपको फ़ाइल का पूरा साइज़ नहीं पता है, तो Content-Range को */* पर सेट करें.

    ध्यान दें: डेटा को अलग-अलग हिस्सों में बांटने का अनुरोध किया जा सकता है, न कि सिर्फ़ अपलोड में रुकावट आने पर. उदाहरण के लिए, अगर आपको लेगसी ब्राउज़र के लिए अपलोड की प्रोग्रेस के संकेत दिखाने हैं, तो यह सुविधा काम की है.

  2. जानें कि कितने बाइट अपलोड किए गए. स्टेटस क्वेरी का जवाब प्रोसेस करें. सर्वर अपने रिस्पॉन्स में Range हेडर का इस्तेमाल करके, यह बताता है कि उसे अब तक कौनसे बाइट मिले हैं.  उदाहरण के लिए, 0-299999 का Range हेडर बताता है कि फ़ाइल के पहले 3,00,000 बाइट मिल चुके हैं.
  3. बचे हुए डेटा को अपलोड करें. आखिर में, अब आपको पता है कि अनुरोध को फिर से कहां शुरू करना है, तो बचा हुआ डेटा या मौजूदा डेटा भेजें. ध्यान दें कि आपको दोनों में से किसी भी स्थिति में, बाकी बचे डेटा को एक अलग डेटा ग्रुप के तौर पर इस्तेमाल करना होगा. इसलिए, अपलोड को फिर से शुरू करते समय आपको Content-Range हेडर भेजना होगा.
उदाहरण: किसी रुकावट अपलोड होने की प्रोसेस को फिर से शुरू करना

1) अपलोड की स्थिति के लिए अनुरोध करें.

नीचे दिया गया अनुरोध, Content-Range हेडर का इस्तेमाल करके यह बताता है कि 20,00,000 बाइट वाली फ़ाइल की मौजूदा जगह की जानकारी उपलब्ध नहीं है.

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

2) रिस्पॉन्स से, अब तक अपलोड किए गए बाइट की संख्या निकालें.

सर्वर के रिस्पॉन्स में Range हेडर का इस्तेमाल करके यह दिखाया जाता है कि उसे फ़ाइल के पहले 43 बाइट अब तक मिल चुके हैं. फिर से अपलोड किया गया अपलोड कहां से शुरू करना है, यह तय करने के लिए Range हेडर की ऊपरी वैल्यू का इस्तेमाल करें.

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42

ध्यान दें: ऐसा हो सकता है कि अपलोड पूरा होने पर, स्टेटस 201 Created या 200 OK दिखे. ऐसा तब हो सकता है, जब सभी बाइट अपलोड होने के बाद, क्लाइंट को सर्वर से जवाब मिलने से पहले ही कनेक्शन टूट गया हो.

3) अपलोड को वहीं से दोबारा शुरू करें जहां उसे छोड़ा गया था.

नीचे दिया गया अनुरोध, फ़ाइल के बचे हुए बाइट भेजकर अपलोड को फिर से शुरू करता है. यह बाइट 43 से शुरू होता है.

PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999

सबसे सही तरीके

मीडिया अपलोड करते समय, गड़बड़ी को हैंडल करने के सबसे सही तरीकों के बारे में जानना मददगार होता है.

  • कनेक्शन से जुड़ी रुकावटों या 5xx की गड़बड़ियों की वजह से अपलोड न हो पाने वाले वीडियो, फिर से अपलोड करें या उन्हें फिर से अपलोड करने की कोशिश करें. इनमें ये शामिल हैं:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • अगर अपलोड अनुरोधों को फिर से शुरू करने या फिर से कोशिश करते समय 5xx सर्वर की कोई गड़बड़ी मिलती है, तो एक्सपोनेन्शियल बैकऑफ़ रणनीति का इस्तेमाल करें. अगर सर्वर पर ज़्यादा लोड आ रहा है, तो ये गड़बड़ियां हो सकती हैं. एक्सपोनेन्शियल बैकऑफ़ से अनुरोधों की ज़्यादा संख्या या बहुत ज़्यादा नेटवर्क ट्रैफ़िक के दौरान इस तरह की समस्याओं से बचने में मदद मिल सकती है.
  • अन्य तरह के अनुरोधों को एक्स्पोनेंशियल बैकऑफ़ की मदद से हैंडल नहीं किया जाना चाहिए. हालांकि, फिर भी उनमें से कई अनुरोधों को मैनेज करने की कोशिश की जा सकती है. इन अनुरोधों को दोबारा भेजते समय, उन्हें ज़्यादा बार न भेजें. उदाहरण के लिए, किसी गड़बड़ी की रिपोर्ट करने से पहले आपके कोड को दस या उससे कम बार कोशिश की जा सकती है.
  • फिर से शुरू किए जा सकने वाले अपलोड करते समय, 404 Not Found और 410 Gone गड़बड़ियों को ठीक करने के लिए, पूरा अपलोड फिर से शुरू करें.

एक्सपोनेंशियल बैकऑफ़

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

सही तरीके से इस्तेमाल करने पर, एक्सपोनेंशियल बैकऑफ़, बैंडविड्थ के इस्तेमाल की क्षमता को बढ़ाता है. साथ ही, सही जवाब पाने के लिए ज़रूरी अनुरोधों की संख्या को कम करता है और एक साथ कई अनुरोधों को प्रोसेस करने की क्षमता को बढ़ाता है.

सिंपल एक्स्पोनेंशियल बैकऑफ़ लागू करने का फ़्लो यह है:

  1. एपीआई से अनुरोध करें.
  2. आपको HTTP 503 कोड वाला जवाब मिलता है. इससे पता चलता है कि आपको अनुरोध फिर से करना चाहिए.
  3. 1 सेकंड + random_number_milliseconds इंतज़ार करें और फिर से कोशिश करें.
  4. HTTP 503 रिस्पॉन्स पाएं. इसका मतलब है कि आपको फिर से अनुरोध करना चाहिए.
  5. दो सेकंड और रैंडम_number_मिलीसेकंड से इंतज़ार करें और फिर से अनुरोध करने की कोशिश करें.
  6. HTTP 503 रिस्पॉन्स पाएं. इसका मतलब है कि आपको फिर से अनुरोध करना चाहिए.
  7. चार सेकंड और रैंडम_number_मिलीसेकंड तक इंतज़ार करें और फिर से अनुरोध करें.
  8. आपको HTTP 503 कोड वाला जवाब मिलता है. इससे पता चलता है कि आपको अनुरोध फिर से करना चाहिए.
  9. 8 सेकंड + random_number_milliseconds इंतज़ार करें और फिर से कोशिश करें.
  10. HTTP 503 रिस्पॉन्स पाएं. इसका मतलब है कि आपको फिर से अनुरोध करना चाहिए.
  11. 16 सेकंड और रैंडम नंबर_मिलीसेकंड से ज़्यादा इंतज़ार करें और फिर से अनुरोध करने की कोशिश करें.
  12. बंद करो। गड़बड़ी की शिकायत करें या लॉग इन करें.

ऊपर दिए गए फ़्लो में, random_number_milliseconds एक रैंडम संख्या है, जो 1000 से कम या उसके बराबर होती है. ऐसा करना ज़रूरी है, क्योंकि थोड़ी देर के लिए रुकने से लोड को ज़्यादा बराबर तरीके से बांटा जा सकता है. साथ ही, सर्वर पर एक साथ कई अनुरोधों से बचने में भी मदद मिलती है. हर इंतज़ार के बाद रैंडम_number_मिलीसेकंड की वैल्यू फिर से तय करनी होगी.

ध्यान दें: इंतज़ार हमेशा (2 ^ n) + रैंडम_number_मिलीसेकंड होता है, जहां n एक क्रमिक रूप से बढ़ने वाला पूर्णांक है, जिसे शुरुआत में 0 के रूप में दिखाया जाता है. हर अनुरोध (हर अनुरोध) के लिए, पूर्णांक n की वैल्यू 1 से बढ़ती है.

एल्गोरिदम n के 5 होने पर खत्म हो जाता है. यह सीमा, क्लाइंट को बार-बार कोशिश करने से रोकती है. साथ ही, किसी अनुरोध को "ठीक नहीं की जा सकने वाली गड़बड़ी" माना जाने से पहले, करीब 32 सेकंड की देरी होती है. ज़्यादा से ज़्यादा संख्या में कोशिश करने से फ़ायदा हो सकता है. खास तौर पर तब, जब बहुत लंबा वीडियो अपलोड हो रहा हो; कृपया ध्यान रखें कि फिर से कोशिश करने के लिए, एक मिनट से कम का समय दिया गया हो.

एपीआई क्लाइंट लाइब्रेरी से जुड़ी गाइड