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

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

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

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

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

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

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

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

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

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

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

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

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

आसानी से अपलोड करें

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

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

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

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

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

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

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

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

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

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

यहां दिए गए उदाहरण में काल्पनिक फ़ार्म एपीआई के लिए कई हिस्सों में अपलोड करने का अनुरोध दिखाया गया है.

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 टाइप और साइज़ की सीमाओं की सूची के लिए, एपीआई रेफ़रंस देखें.

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

काल्पनिक फ़ार्म एपीआई के लिए फिर से शुरू करने का सेशन शुरू करने का तरीका, इस उदाहरण में दिखाया गया है.

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-Length हेडर के साथ, Content-Range हेडर भी डालना ज़रूरी है:

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

हिस्से के साइज़ से जुड़ी पाबंदी: सभी डेटा साइज़, 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

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

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 हेडर शामिल होना चाहिए. इससे पता चलता है कि फ़ाइल में मौजूदा लोकेशन के बारे में कोई जानकारी नहीं है. उदाहरण के लिए, अगर आपकी फ़ाइल की कुल लंबाई 20,00,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 सर्वर की गड़बड़ी दिखती है, तो एक्सपोनेंशियल बैकऑफ़ की रणनीति का इस्तेमाल करें. ये गड़बड़ियां तब हो सकती हैं, जब सर्वर पर ज़रूरत से ज़्यादा लोड हो रहा हो. बहुत ज़्यादा समय तक बहुत ज़्यादा अनुरोध करने पर या बहुत ज़्यादा नेटवर्क ट्रैफ़िक होने पर, एक्स्पोनेंशियल बैकऑफ़ से ऐसी समस्याओं को कम किया जा सकता है.
• एक्स्पोनेंशियल बैकऑफ़ की मदद से, दूसरी तरह के अनुरोधों को हैंडल नहीं किया जाना चाहिए. हालांकि, उनमें से कई अनुरोधों को फिर से आज़माया जा सकता है. इन अनुरोधों के लिए दोबारा कोशिश करते समय, इन्हें फिर से कोशिश करने की संख्या सीमित करें. उदाहरण के लिए, किसी गड़बड़ी की शिकायत करने से पहले आपका कोड 10 या उससे कम बार कोशिश कर सकता है.
• दोबारा अपलोड करने से पहले, 404 Not Found और 410 Gone गड़बड़ियों को ठीक करें. इसके लिए, शुरू से दोबारा अपलोड करना शुरू करें.

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

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

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

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

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

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

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

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

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

• .NET
• Java
• PHP
• Python
• रूबी